MCP 服务器

mcp-server-tree-sitter

一个模型上下文协议 (MCP) 服务器，它使用 tree-sitter 提供代码分析功能，旨在让 Claude 能够智能地访问代码库，并进行适当的上下文管理。

README

MCP Tree-sitter 服务器

一个模型上下文协议 (MCP) 服务器，它使用 tree-sitter 提供代码分析功能，旨在为 Claude 提供智能的代码库访问，并具有适当的上下文管理。

特性

🔍 灵活探索: 以多个粒度级别检查代码
🧠 上下文管理: 提供足够的信息，而不会使上下文窗口不堪重负
🌐 语言无关: 通过 tree-sitter-language-pack 支持多种编程语言，包括 Python、JavaScript、TypeScript、Go、Rust、C、C++、Swift、Java、Kotlin、Julia 和 APL
🌳 结构感知: 使用基于 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：

打开您的 Claude Desktop 配置文件：
- macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
如果文件不存在，请创建它。

将服务器添加到 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 替换为您的项目目录的实际绝对路径。

保存文件并重新启动 Claude Desktop。

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

使用发布的版本进行配置

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

打开您的 Claude Desktop 配置文件（与上述位置相同）。

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

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

保存文件并重新启动 Claude Desktop。

此方法使用 uvx 直接运行已安装的 PyPI 软件包，这是发布版本的推荐方法。服务器不需要任何其他参数即可在其基本配置中运行。

状态持久化

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

项目保持注册状态，直到显式删除或服务器重新启动
解析树根据配置设置进行缓存
语言信息在服务器的整个生命周期中保留

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

作为独立服务器运行

mcp run mcp_server_tree_sitter.server

与 MCP Inspector 一起使用

mcp dev mcp_server_tree_sitter.server

用法

注册项目

首先，注册一个要分析的项目：

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")

关于 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

服务器将在以下位置查找配置：

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

可用资源

服务器提供以下 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