⚙

代码分析服务器

基于Tree-sitter的代码分析服务器，为AI助手提供智能代码库访问和上下文管理功能。

作者 By wrale

本地部署代码分析 AST解析

GitHub

MCP树保姆服务器

一种模型上下文协议（MCP）服务器，使用树保姆提供代码分析功能，旨在让人工智能助手通过适当的上下文管理智能访问代码库。Claude Desktop是参考实现目标。

特性

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

有关所有可用命令、其当前实施状态和详细功能矩阵的完整列表，请参阅功能.md 文件。

安装

先决条件

Python 3.10+
适用于您首选语言的树型语言解析器

基本安装

BASH``` 1pip install mcp-server-tree-sitter


### 开发安装


BASH```
1
2
3git clone https://github.com/wrale/mcp-server-tree-sitter.git
cd mcp-server-tree-sitter
pip install -e ".[dev]"

快速开始

使用Claude Desktop运行

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

使用MCP CLI

在Claude Desktop注册服务器：

BASH``` 1mcp 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`
- 窗户： `%APPDATA%\Claude\claude_desktop_config.json`


如果文件不存在，则创建该文件。
2. 将服务器添加到 `mcpServers` 章节：


JSON```
1
2
3
4
5
6
7
8
9
10
11{
    "mcpServers": {
        "tree_sitter": {
            "command": "python",
            "args": [
                "-m",
                "mcp_server_tree_sitter.server"
            ]
        }
    }
}

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

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14{ “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（已发布版本）手动安装软件包或克隆存储库，只需对Claude Desktop使用以下配置：


1. 打开您的Claude Desktop配置文件（与上述位置相同）。
2. 将树保姆服务器添加到 `mcpServers` 章节：


JSON```
1
2
3
4
5
6
7
8
9
10
11{
    "mcpServers": {
        "tree_sitter": {
            "command": "uvx",
            "args": [
                "--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
                "mcp-server-tree-sitter"
            ]
        }
    }
}

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

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

状态持久性

MCP树保姆服务器在调用之间维护状态。这意味着：

在明确删除或重新启动服务器之前，项目将保持注册状态
根据配置设置缓存解析树
语言信息将在服务器的整个生命周期内保留

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

作为独立服务器运行

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

直接使用MCP CLI：

BASH``` 1python -m mcp run mcp_server_tree_sitter.server


#### 使用Makefile目标：


BASH```
1
2
3
4
5
6
7
8
9
10
11
12
13
14# Show available targets
make
# Run the server with default settings
make mcp-run
# Show help information
make mcp-run ARGS="--help"
# Show version information
make mcp-run ARGS="--version"
# Run with custom configuration file
make mcp-run ARGS="--config /path/to/config.yaml"
# Enable debug logging
make mcp-run ARGS="--debug"
# Disable parse tree caching
make mcp-run ARGS="--disable-cache"

使用已安装的脚本：

BASH``` 1 2 3 4 5 6 7 8 9 10 11 12# Run the server with default settings mcp-server-tree-sitter

Show help information

mcp-server-tree-sitter —help

Show version information

mcp-server-tree-sitter —version

Run with custom configuration file

mcp-server-tree-sitter —config /path/to/config.yaml

Enable debug logging

mcp-server-tree-sitter —debug

Disable parse tree caching

mcp-server-tree-sitter —disable-cache


### 与MCP检查器一起使用


直接使用MCP CLI：


BASH```
1python -m mcp dev mcp_server_tree_sitter.server

或者使用Makefile目标：

BASH``` 1make mcp-dev


您还可以传递参数：


BASH```
1make mcp-dev ARGS="--debug"

用法

注册项目

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

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

浏览文件

列出项目中的文件：

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

查看文件内容：

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

分析代码结构

获取语法树：

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

提取符号：

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

搜索代码

搜索文本：

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

运行树保姆查询：

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

分析复杂性

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

直接使用Python

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

PYTHON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19# Import from the API module from mcp_server_tree_sitter.api import ( register_project, list_projects, get_config, get_language_registry )

Register a project

project_info = register_project( path=“/path/to/project”, name=“my-project”, description=“Description” )

List projects

projects = list_projects()

Get configuration

config = get_config()

Access components through dependency injection

from mcp_server_tree_sitter.di import get_container container = get_container() project_registry = container.project_registry language_registry = container.language_registry


## 配置


创建一个YAML配置文件：


YAML```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21cache:
  enabled: true                # Enable/disable caching (default: true)
  max_size_mb: 100             # Maximum cache size in MB (default: 100)
  ttl_seconds: 300             # Cache entry time-to-live in seconds (default: 300)
security:
  max_file_size_mb: 5          # Maximum file size to process in MB (default: 5)
  excluded_dirs:               # Directories to exclude from processing
    - .git
    - node_modules
    - __pycache__
  allowed_extensions:          # Optional list of allowed file extensions
    # - py
    # - js
    # Leave empty or omit for all extensions
language:
  default_max_depth: 5         # Default max depth for AST traversal (default: 5)
  preferred_languages:         # List of languages to pre-load at startup for faster performance
    - python                   # Pre-loading reduces latency for first operations
    - javascript
log_level: INFO                # Logging level (DEBUG, INFO, WARNING, ERROR)
max_results_default: 100       # Default maximum results for search operations

加载：

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

日志记录配置

服务器的日志记录详细程度可以使用环境变量进行控制：

BASH``` 1 2 3 4 5 6# Enable detailed debug logging export MCP_TS_LOG_LEVEL=DEBUG

Use normal informational logging (default)

export MCP_TS_LOG_LEVEL=INFO

Only show warning and error messages

export MCP_TS_LOG_LEVEL=WARNING


有关日志配置的全面信息，请参阅 测井文件。有关命令行界面的详细信息，请参阅 CLI文档.


### 关于首选语言


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


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


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


您还可以配置特定设置：

1configure(cache_enabled=True, max_file_size_mb=10, log_level=“DEBUG”)


或者使用环境变量：


BASH```
1
2
3export 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)用于顶级设置。

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

环境变量（最高）
通过设置值 configure() 电话
YAML配置文件
默认值（最低）

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

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

对于开发者

诊断功能

MCP树保姆服务器包括一个诊断框架，以帮助识别和解决问题：

BASH``` 1 2 3 4# Run diagnostic tests make test-diagnostics

CI-friendly version (won’t fail the build on diagnostic issues)

make test-diagnostics-ci


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


### 类型安全注意事项


MCP Tree sitter Server在通过精心设计的模式和协议与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`


看 功能.md 有关每个工具的实现状态、依赖关系和使用示例的详细信息。


## 可用提示


服务器提供以下MCP提示：


- `code_review` -创建检查代码的提示
- `explain_code` -创建解释代码的提示
- `explain_tree_sitter_query` -解释树型查询语法
- `suggest_improvements` -创建提示以建议代码改进
- `project_overview` -创建项目概述分析提示


## 反馈与社区


我们很想知道您是如何使用mcp服务器树保姆的，以及什么会使它对您的工作流程更有用。


- **问题和功能请求**: [GitHub讨论](https://github.com/wrale/mcp-server-tree-sitter/discussions)
- **错误报告**: [GitHub问题](https://github.com/wrale/mcp-server-tree-sitter/issues)


## 许可证


麻省理工学院