STARWARCLOUD STARWAR.AI
返回市场
MCP服务器树形解析器

MCP服务器树形解析器

作者：wrale206 星标更新：2025-05-04
安装使用来源：spider==github.com

项目介绍

MseeP.ai 安全评估徽章

MCP Tree-sitter Server

这是一个使用 tree-sitter 提供代码分析能力的模型上下文协议（MCP）服务器，旨在让AI助手能够智能地访问代码库，并进行适当的上下文管理。Claude Desktop 是参考实现目标。

<a href="https://glama.ai/mcp/servers/@wrale/mcp-server-tree-sitter"> <img width="380" height="200" src="https://gips3.baidu.com/it/u=2127562439,4061082180&fm=3081&app=3081&f=PNG?w=760&h=400" alt="mcp-server-tree-sitter MCP 服务器" /> </a>

功能

  • 🔍 灵活探索：在多个粒度级别上检查代码
  • 🧠 上下文管理：提供足够的信息而不使上下文窗口过载
  • 🌐 语言无关性：支持多种编程语言，包括 Python、JavaScript、TypeScript、Go、Rust、C、C++、Swift、Java、Kotlin、Julia 和 APL，通过 tree-sitter-language-pack
  • 🌳 结构感知：基于 AST 的理解，使用高效的游标遍历
  • 🔎 可搜索性：使用文本搜索和 tree-sitter 查询查找特定模式
  • 🔄 缓存：通过解析树缓存优化性能
  • 🔑 符号提取：提取并分析函数、类和其他代码符号
  • 📊 依赖分析：识别并分析代码依赖关系
  • 🧩 状态持久化：在调用之间维护项目注册和缓存数据
  • 🔒 安全：内置的安全边界和输入验证

要查看所有可用命令及其当前实现状态和详细的特性矩阵，请参阅 FEATURES.md 文档。

安装

先决条件

  • Python 3.10+
  • 您首选语言的 tree-sitter 语言解析器

基本安装

pip install mcp-server-tree-sitter

开发安装

git clone https://github.com/wrale/mcp-server-tree-sitter.git
cd mcp-server-tree-sitter
pip install -e ".[dev,languages]"

快速开始

使用 Claude Desktop 运行

您可以通过 MCP CLI 或手动配置 Claude Desktop 来使服务器在 Claude Desktop 中可用。

使用 MCP CLI

将服务器注册到 Claude Desktop：

mcp install mcp_server_tree_sitter.server:mcp --name "tree_sitter"

手动配置

或者，您可以手动配置 Claude Desktop：

  1. 打开您的 Claude Desktop 配置文件：

    • macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    如果不存在，请创建该文件。

  2. 将服务器添加到 mcpServers 部分：

    {
    "mcpServers": {
        "tree_sitter": {
            "command": "python",
            "args": [
                "-m",
                "mcp_server_tree_sitter.server"
            ]
        }
    }
}

    或者，如果您使用的是 uv 或其他包管理器：

    {
    "mcpServers": {
        "tree_sitter": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
                "run",
                "-m",
                "mcp_server_tree_sitter.server"
            ]
        }
    }
}

    注意：请确保将 /ABSOLUTE/PATH/TO/YOUR/PROJECT 替换为您项目的实际绝对路径。

  3. 保存文件并重启 Claude Desktop。

一旦您正确配置了至少一个 MCP 服务器，MCP 工具图标（锤子）将在 Claude Desktop 的界面中出现。然后，您可以通过点击此图标来访问 tree_sitter 服务器的功能。

使用已发布的版本配置

如果您不想从 PyPI（已发布版本）手动安装包或克隆存储库，只需使用以下配置即可：

  1. 打开您的 Claude Desktop 配置文件（位置同上）。

  2. 将 tree-sitter 服务器添加到 mcpServers 部分：

    {
    "mcpServers": {
        "tree_sitter": {
            "command": "uvx",
            "args": [
                "--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
                "mcp-server-tree-sitter"
            ]
        }
    }
}

  3. 保存文件并重启 Claude Desktop。

这种方法使用 uvx 直接运行已安装的 PyPI 包，这是已发布版本的推荐方法。服务器在基本配置下运行不需要任何额外参数。

状态持久化

MCP Tree-sitter 服务器在调用之间维持状态。这意味着：

  • 项目注册直到显式移除或服务器重启
  • 解析树根据配置设置进行缓存
  • 语言信息在整个服务器生命周期内保留

这种持久性在服务器生命周期内使用单例模式的关键组件来维持内存中的状态。

作为独立服务器运行

有几种方式可以运行服务器：

直接使用 MCP CLI：

python -m mcp run mcp_server_tree_sitter.server

使用 Makefile 目标：

# 显示可用目标
make

# 使用默认设置运行服务器
make mcp-run

# 显示帮助信息
make mcp-run ARGS="--help"

# 显示版本信息
make mcp-run ARGS="--version"

# 使用自定义配置文件运行
make mcp-run ARGS="--config /path/to/config.yaml"

# 启用调试日志
make mcp-run ARGS="--debug"

# 禁用解析树缓存
make mcp-run ARGS="--disable-cache"

使用安装脚本：

# 使用默认设置运行服务器
mcp-server-tree-sitter

# 显示帮助信息
mcp-server-tree-sitter --help

# 显示版本信息
m.mcp-server-tree-sitter --version

# 使用自定义配置文件运行
mcp-server-tree-sitter --config /path/to/config.yaml

# 启用调试日志
mcp-server-tree-sitter --debug

# 禁用解析树缓存
mcp-server-tree-sitter --disable-cache

使用 MCP Inspector

直接使用 MCP CLI：

python -m mcp dev mcp_server_tree_sitter.server

或者使用 Makefile 目标：

make mcp-dev

您也可以传递参数：

make mcp-dev ARGS="--debug"

使用

注册项目

首先，注册一个项目以进行分析：

register_project_tool(path="/path/to/your/project", name="my-project")

探索文件

列出项目中的文件：

list_files(project="my-project", pattern="**/*.py")

查看文件内容：

get_file(project="my-project", path="src/main.py")

分析代码结构

获取语法树：

get_ast(project="my-project", path="src/main.py", max_depth=3)

提取符号：

get_symbols(project="my-project", path="src/main.py")

搜索代码

搜索文本：

find_text(project="my-project", pattern="function", file_pattern="**/*.py")

运行 tree-sitter 查询：

run_query(
    project="my-project",
    query='(function_definition name: (identifier) @function.name)',
    language="python"
)

分析复杂性

analyze_complexity(project="my-project", path="src/main.py")

直接使用 Python

虽然主要用途是通过 MCP 服务器，但您也可以直接在 Python 代码中使用该库：

# 从 API 模块导入
from mcp_server_tree_sitter.api import (
    register_project, list_projects, get_config, get_language_registry
)

# 注册一个项目
project_info = register_project(
    path="/path/to/project", 
    name="my-project", 
    description="Description"
)

# 列出项目
projects = list_projects()

# 获取配置
config = get_config()

# 通过依赖注入访问组件
from mcp_server_tree_sitter.di import get_container
container = get_container()
project_registry = container.project_registry
language_registry = container.language_registry

配置

创建一个 YAML 配置文件：

cache:
  enabled: true                # 启用/禁用缓存（默认：true）
  max_size_mb: 100             # 缓存的最大大小（MB，默认：100）
  ttl_seconds: 300             # 缓存条目的时间生存期（秒，默认：300）

security:
  max_file_size_mb: 5          # 处理的最大文件大小（MB，默认：5）
  excluded_dirs:               # 要排除处理的目录
    - .git
    - node_modules
    - __pycache__
  allowed_extensions:          # 可选允许的文件扩展名列表
    # - py
    # - js
    # 留空或省略表示所有扩展名

language:
  default_max_depth: 5         # AST 遍历的默认最大深度（默认：5）
  preferred_languages:         # 在启动时预加载以提高性能的语言列表
    - python                   # 预加载减少首次操作的延迟
    - javascript

log_level: INFO                # 日志级别（DEBUG, INFO, WARNING, ERROR）
max_results_default: 100       # 搜索操作的默认最大结果数

使用以下命令加载它：

configure(config_path="/path/to/config.yaml")

日志配置

服务器的日志详细程度可以通过环境变量控制：

# 启用详细的调试日志
export MCP_TS_LOG_LEVEL=DEBUG

# 使用正常的信息日志（默认）
export MCP_TS_LOG_LEVEL=INFO

# 仅显示警告和错误消息
export MCP_TS_LOG_LEVEL=WARNING

有关日志配置的详细信息，请参阅 日志文档。有关命令行接口的详细信息，请参阅 CLI 文档。

关于 preferred_languages

preferred_languages 设置控制哪些语言解析器在服务器启动时预加载而不是按需加载。这提供了几个好处：

  • 更快的初始分析：首次分析预加载语言的文件时没有延迟
  • 早期错误检测：在启动时发现解析器的问题，而不是在使用过程中
  • 可预测的内存分配：为经常使用的解析器提前分配内存

默认情况下，所有解析器都是在首次需要时按需加载的。为了获得最佳性能，请指定您项目中最频繁使用的语言。

您还可以配置特定设置：

configure(cache_enabled=True, max_file_size_mb=10, log_level="DEBUG")

或者使用环境变量：

export MCP_TS_CACHE_MAX_SIZE_MB=256
export MCP_TS_LOG_LEVEL=DEBUG
export MCP_TS_CONFIG_PATH=/path/to/config.yaml

环境变量使用格式 MCP_TS_SECTION_SETTING（例如，MCP_TS_CACHE_MAX_SIZE_MB）用于部分设置，或 MCP_TS_SETTING（例如，MCP_TS_LOG_LEVEL）用于顶级设置。

配置值按照以下优先级顺序应用：

  1. 环境变量（最高）
  2. 通过 configure() 调用设置的值
  3. YAML 配置文件
  4. 默认值（最低）

服务器会查找配置：

  1. configure() 调用中指定的路径
  2. MCP_TS_CONFIG_PATH 环境变量中指定的路径
  3. 默认位置：~/.config/tree-sitter/config.yaml

开发者指南

诊断能力

MCP Tree-sitter 服务器包含一个诊断框架，有助于识别和解决问题：

# 运行诊断测试
make test-diagnostics

# CI友好版本（不会因诊断问题而失败构建）
make test-diagnostics-ci

诊断测试提供关于服务器行为的详细信息，并可以帮助隔离特定问题。有关诊断框架的更多信息，请参阅 诊断文档。

类型安全性考虑

MCP Tree-sitter 服务器在与 tree-sitter 库交互时通过精心设计的模式和协议保持类型安全性。如果您正在扩展代码库，请查阅 类型安全指南，了解处理 tree-sitter API 变化的关键信息。

可用资源

服务器提供的 MCP 资源如下：

  • project://{project}/files - 列出项目中的所有文件
  • project://{project}/files/{pattern} - 列出匹配模式的文件
  • project://{project}/file/{path} - 获取文件内容
  • project://{project}/file/{path}/lines/{start}-{end} - 获取文件中的特定行
  • project://{project}/ast/{path} - 获取文件的 AST
  • project://{project}/ast/{path}/depth/{depth} - 获取具有自定义深度的 AST

可用工具

服务器提供的工具包括：

  • 项目管理：register_project_tool, list_projects_tool, remove_project_tool
  • 语言管理：list_languages, check_language_available
  • 文件操作：list_files, get_file, get_file_metadata
  • AST 分析：get_ast, get_node_at_position
  • 代码搜索：find_text, run_query
  • 符号提取：get_symbols, find_usage
  • 项目分析：analyze_project, get_dependencies, analyze_complexity
  • 查询构建：get_query_template_tool, list_query_templates_tool, build_query, adapt_query, get_node_types
  • 相似代码检测：find_similar_code
  • 缓存管理：clear_cache
  • 配置诊断：diagnose_config

请参阅 FEATURES.md 以获取每个工具的实现状态、依赖项和使用示例的详细信息。

可用提示

服务器提供的 MCP 提示如下：

  • code_review - 创建代码审查提示
  • explain_code - 创建解释代码的提示
  • explain_tree_sitter_query - 解释 tree-sitter 查询语法
  • suggest_improvements - 创建建议代码改进的提示
  • project_overview - 创建项目概述分析提示

许可证

MIT