MCP Tree-sitter 服务器

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

功能特性

• 🔍 灵活探索：以多种粒度级别检查代码

• 🧠 上下文管理：提供恰到好处的信息，而不会让上下文窗口过载

• 🌐 语言无关：通过 tree-sitter-language-pack 支持多种编程语言，包括 Python、JavaScript、TypeScript、Go、Rust、C、C++、C#、Swift、Java、Kotlin、Dart、Julia 和 APL

• 🌳 结构感知：使用基于 AST 的理解，并结合高效的基于光标的遍历

• 🔎 可搜索：使用文本搜索和 tree-sitter 查询查找特定模式

• 🔄 缓存：通过解析树缓存优化性能

• 🔑 符号提取：提取并分析函数、类和其他代码符号

• 📊 依赖分析：识别并分析代码依赖关系

• 🧩 状态持久化：在调用之间维护项目注册和缓存数据

• 🔒 安全：内置安全边界和输入验证

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

Related MCP server: code-index-mcp

安装

先决条件

• 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]"

快速入门

在 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 安装包（发布版本）或克隆存储库，只需为 Claude Desktop 使用以下配置：

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 目标：

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

使用已安装的脚本：

# 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 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 代码中使用该库：

# 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 配置文件：

cache:
 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

使用以下方式加载：

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

日志配置

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

# 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

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 服务器包含一个诊断框架，以帮助识别和修复问题：

# Run diagnostic tests
make test-diagnostics

# CI-friendly version (won't fail the build on diagnostic issues)
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 - 创建用于项目概览分析的提示词

反馈与社区

我们很乐意了解您如何使用 mcp-server-tree-sitter，以及什么能让它对您的工作流程更有帮助。

• 问题与功能请求：GitHub Discussions

• 错误报告：GitHub Issues

许可证

MIT

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• adapt_queryC
• analyze_complexityC
• analyze_projectC
• build_queryC
• check_language_availableC
• clear_cacheC
• configureC
• diagnose_configC