mcp-server-tree-sitter

MCP 树托管服务器

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

特征

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

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

安装

先决条件

• Python 3.10+
• 适用于您首选语言的 Tree-sitter 语言解析器

基本安装

开发安装

快速入门

使用 Claude Desktop 运行

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

使用 MCP CLI

使用 Claude Desktop 注册服务器：

手动配置

或者，您可以手动配置 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：

使用 Makefile 目标：

使用已安装的脚本：

与 MCP 检查器一起使用

直接使用 MCP CLI：

或者使用 Makefile 目标：

您还可以传递参数：

用法

注册项目

首先注册一个项目来分析：

探索文件

列出项目中的文件：

查看文件内容：

分析代码结构

获取语法树：

提取符号：

搜索代码

搜索文本：

运行 tree-sitter 查询：

分析复杂性

直接使用 Python

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

配置

创建 YAML 配置文件：

加载它：

日志配置

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

有关日志记录配置的完整信息，请参阅日志记录文档。有关命令行界面的详细信息，请参阅CLI 文档。

关于 preferred_languages

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

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

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

您还可以配置特定设置：

或者使用环境变量：

环境变量使用格式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 服务器包含一个诊断框架，可帮助识别和修复问题：

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

类型安全注意事项

MCP 树型服务器通过精心设计模式和协议，在与树型服务器库交互时保持类型安全。如果您要扩展代码库，请查看类型安全指南，了解有关处理树型服务器 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 - 创建项目概述分析的提示

执照

麻省理工学院