Treesitter MCP

树保姆MCP服务器

AST是编码剂的首选MCP。它不会将原始文件粘贴到上下文窗口中，而是返回紧凑的结构答案：签名、使用行、重点编辑上下文、影响摘要和具有明确令牌预算的审查包。

Token efficiency comparison: MCP vs agent-style shell baselines

所得

下面的数字将MCP有效载荷与代理实际会使用的shell工作流进行比较 接触（grep、find+head、targeted reads）——而不是反对猫的一切稻草人。

• 文件概览~2.7×更小 比 cat file （签名而非正文）。
• 聚焦编辑~5.0倍小 比 cat file （一个符号加上直接deps，而不是整个文件）。
• 回购搜索~小4.5倍 比 grep -rn -C3 symbol，增加了每次点击的范围、所有者和使用类型。
• 目录映射~3.2×更小 比 find -type f + head -50 每个文件，结构化而非原始文本。
• 调用图跟踪~57×更小 然后抓取每个匹配的文件（“谁调用X？”的工作流程）。
• 约2071个代币 添加到代理上下文窗口以注册服务器。
• 有效载荷大小回归未通过CI --如果重构使工具输出膨胀，则构建会中断。

这些是Rust、TypeScript、Python和JavaScript在18次运行中的指示性平均值 固定装置——将其视为“数量级”，而不是精确的保证。仅节省代币 不能证明质量取胜；看见 BENCHMARK.md 用于精度基准 这个项目正在构建的方法论。

它做什么

treesitter-mcp 通过四种重复模式减少令牌负载：

1. 结构过滤：当不需要完整代码时，返回AST派生的符号和签名，而不是原始正文。
2. 集中提取：返回一个符号，再加上对该任务重要的依赖关系、导入、类型和测试。
3. 紧凑型分组：使用稳定的、面向行的模式，这样重复的键和散文就不会主导有效载荷。
4. 预算感知截断：使用 tiktoken 计数和明确 max_tokens 限制以保持结果有界。

这是核心定位：它不仅仅是一个解析器，它是一个 用于代码工作流的上下文压缩器.

安装

自制（macOS）

brew tap christoph/treesitter-mcp
brew install treesitter-mcp

claude mcp add --scope project treesitter-mcp -- /opt/homebrew/bin/treesitter-mcp

发布二进制文件（Linux和Windows）

预构建的发布二进制文件可在 页面。

• Linux：下载目标的发布存档，解压缩它，并将MCP客户端指向 treesitter-mcp 二进制
• Windows：下载Windows版本存档，解压缩它，然后将MCP客户端指向 treesitter-mcp.exe

其他来源构建

如果你没有使用Homebrew或发布二进制文件 cargo build --release flow也可以在其他支持的平台上使用Rust工具链。

配置

克劳德代码CLI

将服务器添加到当前项目中：

claude mcp add --scope project treesitter-mcp -- /ABSOLUTE/PATH/TO/treesitter-mcp

您可以通过以下方式验证Claude Code是否看到它：

claude mcp list

或者直接将其添加到项目级别 .mcp.json:

{
  "mcpServers": {
    "treesitter-mcp": {
      "command": "/ABSOLUTE/PATH/TO/treesitter-mcp",
      "args": []
    }
  }
}

连接后，让Claude Code显式使用它，例如：

Use treesitter-mcp to map the src directory, then inspect the service layer before proposing changes.

法典

将服务器添加到 ~/.codex/config.toml:

[mcp_servers.treesitter-mcp]
command = "/ABSOLUTE/PATH/TO/treesitter-mcp"

然后重新启动Codex并确认其可用：

codex mcp list

配置后，提示Codex直接使用MCP，例如：

Use treesitter-mcp to find all usages of UserService, then show the smallest edit context for update_user.

其他MCP客户端

对于任何其他MCP客户端，将其配置为直接运行二进制文件：

/path/to/treesitter-mcp

或者，您可以通过Cargo运行它（启动速度较慢）：

cargo run --release --manifest-path /path/to/treesitter-mcp/Cargo.toml

构建二进制文件：

cargo build --release

将您的MCP客户端指向 target/release/treesitter-mcp，然后从一个小的工作流开始，而不是原始读取：

1. code_map(path="src", detail="minimal", with_types=true)
2. view_code(file_path="...", detail="signatures")
3. minimal_edit_context(file_path="...", symbol_name="...")
4. review_context(file_path="...") after changes

快速开始

如果您需要完整的安装和配置详细信息，请继续阅读下面的内容。有关此README背后的消息和路线图，请参阅 docs/COMMUNICATION.md.

令牌效率比较

在重建服务器后，根据当前代码进行测量。 基线模拟了代理实际运行的shell工作流（grep、find+head， 目标读取）-- 不 cat MCP端是精确的JSON 每个工具返回的有效载荷与构建的MCP服务器返回的形状相同。 以下所有令牌计数为 平均值，不是单一的例子。

保存的平均令牌=原始平均令牌-MCP平均令牌。已保存百分比= 1 - MCP/raw.

笔记：

• 回购搜索基线为 grep -rn -C3，不裸露 grep -lBare grep仅返回

位置，因此对于纯定位来说，它似乎比MCP便宜；公平的比较 是“定位+几行上下文”，即 find_usages 返回值加范围 以及使用类型元数据。

• 调用图基线读取文本包含符号的每个文件，因为

在没有LSP的情况下跟踪调用者需要读取这些文件。这就是它的原因 比结构化解析调用者的工具贵得多。

• 样本量（每行3-4个）很小——将乘数视为指示性的，而不是精确的。

使用此内容而不是原始读取

• view_code(detail="signatures") 而不是 cat 当你需要结构而不是身体的时候。
• minimal_edit_context 当你编辑一个已知的符号时，不是聚焦文件读取。
• call_graph 而不是读取多个文件来跟踪一个函数。
• find_usages 而不是连接整个目录来回答一个参考问题。
• code_map 而不是在只需要项目形状时倾倒一棵树。
• review_context 而不是手动组装差异、影响、测试和更改的符号上下文。

沟通承诺

• README以测量值而非内部架构作为开头。
• 基准可通过以下方式复制 cargo test report_average_token_benchmarks -- --ignored --nocapture.
• CI发布了一个基准摘要，因此pull请求直接在管道中显示令牌故事。
• 新的代币节省想法在 docs/COMMUNICATION.md，包括产品中仍然缺失的机会。

测量方法

平均基准测试共使用18次运行：

• 4文件概述跨Rust、TypeScript、Python和JavaScript夹具文件运行
• 4个焦点编辑在相同的四个源文件上运行
• 4个调用图跨此存储库中的分析模块运行
• 3回购搜索运行 src/analysis
• 3个目录映射贯穿其中 src, src/analysis，以及 tests/fixtures/complex_rust_service/src

每次跑步：

• 这 基线 令牌计数模拟了代理实际运行的shell工作流：

- cat file 用于文件概述和重点编辑场景 - grep -rn -C3 用于回购搜索 - grep -rln | xargs cat 用于调用图跟踪（读取每个文件 提到该符号，因为跟踪没有LSP的调用者需要读取它们） - find -type f 上市加 head -n 50 目录映射的每个源文件

• 这 MCP令牌计数 是工具响应JSON文本
• 双方都被计算在内 tiktoken_rs::cl100k_base()
• 基线使用单词边界匹配来近似真实的grep行为，并跳过

服务器无法识别其语言的文件（MCP端使用的过滤器相同）

概述

Tree sitter MCP Server通过MCP协议提供强大的代码分析工具，使AI助手能够：

• 跨多种语言解析和分析代码结构
• 提取没有实现细节的高级文件形状
• 生成整个项目的令牌感知代码映射
• 查找代码库中的符号用法
• 执行自定义树状图查询以进行高级分析
• 分析文件版本之间的结构变化（差异感知分析）
• 在进行更改时识别可能受影响的代码
• 添加mcp时向上下文窗口添加约2071个令牌

支持的语言

• 锈 （.rs）
• python 南美国家巴拉圭的缩写（Paraguay）
• JavaScript （.js、.mjs、.cjs）
• TypeScript （.ts、.tsx）
• 超文本标记语言 （.html、.htm）
• 层叠样式表 （.css）
• 迅速 （.swift）
• C （.cs）
• Java Java
• 去 （.go）

可用工具

快速工具选择指南

为您的任务选择合适的工具：

“我需要理解代码”

• 不知道是哪个文件？ → code_map （目录概述）
• 开始新会话？ → type_map （使用排序类型上下文）
• 知道文件，需要概述吗？ → view_code 和 detail="signatures" （仅签名）
• 知道文件，需要完整的细节吗？ → view_code 和 detail="full" （完整代码）
• 知道具体功能吗？ → view_code 和 focus_symbol （聚焦视图，优化令牌）
• 编辑一个已知的符号？ → minimal_edit_context （最小的有用编辑上下文）

“我需要找点东西”

• 符号X在哪里使用？ → find_usages （使用类型进行语法感知搜索）
• 这叫什么/这叫什么？ → call_graph （紧凑型尽力而为的呼叫者/被叫者）
• 已经有LSP参考？ → format_references （紧凑的上下文用于精确定位）
• 已经有LSP诊断？ → format_diagnostics （与车主进行紧凑型诊断）
• 复杂的图案匹配？ → query_pattern （高级，需要树形图语法）
• N行有什么函数？ → symbol_at_line （具有范围层次结构的符号信息）
• 模板中有哪些可用数据？ → template_context （Askama模板变量）

“我正在重构/更改代码”

• 在编辑签名之前： preview_impact （首先估算爆炸半径）
• 更改前： find_usages （查看所有用法）
• 更改后： parse_diff （验证符号级别的更改）
• 影响分析： affected_by_diff （什么可能会打破风险水平）
• 我应该运行哪些测试？ relevant_tests （对一个符号的可能测试进行排名）
• 我只是改变了我想改变的东西吗？ verify_edit （紧凑型结构护栏）
• 需要差异的审阅者上下文吗？ review_context （差异+影响+测试+重点上下文）

工具比较矩阵

精确与启发式

这些工具基于AST结构提供了强有力的保证：

• view_code：从解析的AST中精确提取代码
• parse_diff：文件修订版之间的结构差异
• query_pattern：精确的树型AST查询
• symbol_at_line：AST遍历的作用域链
• template_context：Askama结构解析

这些工具使用语法感知匹配（尽最大努力，而不是编译器级）：

• find_usages：通过树状图进行标识符匹配，可以匹配不同范围内的同音异义词
• format_references：信任LSP提供的精确位置，然后添加语法感知上下文
• format_diagnostics：信任LSP提供的诊断，然后添加语法感知的所有者上下文
• minimal_edit_context：相同的文件相关性加上来自导入的直接项目本地依赖签名
• call_graph：项目本地调用提取，首选相同的文件定义，不是编译器级解析
• preview_impact：虚拟签名差异加语法感知影响扫描，无需文件编辑
• affected_by_diff：依赖于 find_usages 用于影响分析
• relevant_tests：通过文件启发式和语法感知符号匹配进行测试发现
• verify_edit：结构差异护栏，不进行语义意图验证
• review_context：现有工具的组成；精度取决于底层差异/用法上下文
• affected_by_diff：依赖于 find_usages 用于影响分析
• code_map：结构概述，范围感知但语义未解析
• type_map：通过AST进行类型识别，使用次数为近似值

对于编译器级符号解析（转到定义，精确查找引用），请在MCP服务器旁边使用LSP服务器。

常见工作流模式

模式1:LLM会话初始化（优化-单程）

1. code_map (path="src", with_types=true, count_usages=true)  → Get both structure AND usage-ranked types
2. Begin coding tasks with full context

模式1b:LLM会话初始化（传统-两遍）

1. type_map (path="src", max_tokens=3000)      → Get usage-ranked types
2. code_map (path="src", detail="minimal")      → Get file structure
3. Begin coding tasks with full type awareness

模式2：探索新的代码库

1. code_map (path="src", detail="minimal", with_types=true)  → Get structure + types in one pass
2. view_code (detail="signatures")              → Understand interfaces
3. view_code (focus_symbol="function_name")     → Deep dive

模式2：重构函数

1. find_usages (symbol="function_name")         → See all call sites
2. Make changes
3. parse_diff ()                                → Verify changes
4. affected_by_diff ()                          → Check impact with risk levels

模式2b：计划签名更改

1. preview_impact (symbol_name="function_name", new_signature="...") → Estimate fallout first
2. Make changes
3. relevant_tests (symbol_name="function_name")                      → Run focused tests
4. verify_edit (target_symbol="function_name")                       → Confirm edit stayed scoped

模式2c：查看本地差异

1. review_context (file_path="src/lib.rs")      → Diff + impact + tests + focused changed-symbol context
2. view_code / minimal_edit_context as needed   → Drill deeper only where needed

模式3：调试错误

1. symbol_at_line (line=error_line)             → Find function
2. view_code (focus_symbol=func_name)           → See implementation
3. find_usages (symbol=variable_name)           → Trace data flow

模式4：理解大文件

1. view_code (detail="signatures")              → See all functions
2. view_code (focus_symbol=main_func)           → Start with entry point
3. view_code (focus_symbol=helper)              → Drill into helpers as needed

代币优化策略

• 低预算（\5000个代币）： 使用 view_code 和 detail="full" 自由， code_map 和 detail="full"

常见反模式（不该做什么）

❌ 使用view_code和detail=“full”进行快速概述 → Use detail="signatures" 相反（便宜10倍）\ ❌ 使用query_pattern进行符号搜索 → Use find_usages 相反（更简单，跨语言）\ ❌ 在大文件上使用detail=“full”的view_code，而不首先检查签名 → 始终从以下内容开始 detail="signatures"\ ❌ 在常用符号上使用find_usages时未设置max_context_lines → 可能导致代币爆炸\ ❌ 编辑特定功能时不使用focus_symbol → Use focus_symbol 节省3倍代币

______________________________________________________________________

1.类型_地图

生成所有项目类型的使用排序图。返回按使用频率排序的结构、类、枚举、接口、特征、协议和类型别名。

主要用例： 在会话开始时为LLM代理提供全面的类型上下文，以防止对类型名称、字段和签名产生幻觉。

使用时间：

• ✅ 启动LLM编码会话（上下文启动）
• ✅ 需要在整个项目中进行准确的类型定义
• ✅ 想要了解哪些类型最重要

在以下情况下请勿使用：

• ❌ 需要函数/方法实现→ use view_code
• ❌ 需要呼叫层次结构或控制流→ use code_map
• ❌ 分析单个文件→ use view_code
• ❌ 需要代码结构和类型→ use code_map 和 with_types=true

代币成本： 中型（中型项目典型的2000-3000个代币）

参数：

• path （字符串，必填）：要扫描的目录
• max_tokens （整数，可选，默认值：2000）：代币预算（tiktoken计数）
• pattern （字符串，可选）：Glob过滤器（例如。， "*.rs", "src/**/*.ts")
• count_usages （boolean，可选，默认值：true）：统计整个项目的使用情况。设置为 false 当您只需要键入位置而不需要使用率排名时，可以获得更快的结果。

退货： 紧凑模式（使用排序类型）

• 输出键： h （标题）和 types （行： name|kind|file|line|usage_count)
• 可选元： @ （例如。 @.t=true 截断时）
• 行以换行符分隔；字段以管道分隔并转义(\\, \n, \r, \|)

{
  "h": "name|kind|file|line|usage_count",
  "types": "User|struct|src/domain/models.rs|11|42\nOrder|struct|src/domain/models.rs|107|37"
}

______________________________________________________________________

2.view_code

查看具有灵活详细级别和从项目依赖关系中自动包含类型的源文件。

使用时间：

• ✅ 需要查看/编辑文件
• ✅ 希望从依赖关系中获得类型定义
• ✅ 需要完整的代码或只是签名
• ✅ 编辑特定功能（使用 focus_symbol)

在以下情况下请勿使用：

• ❌ 探索多个文件→ use code_map
• ❌ 您尚未识别文件→ use code_map 首先

代币成本： 中高（因细节级别而异）

参数:

• file_path （string，必填）：源文件的路径
• detail （字符串，可选，默认值：“full”）：详细程度

- "signatures"：仅函数/类签名（无正文）-便宜10倍 - "full"：完整的实施代码

• focus_symbol （字符串，可选）：关注一个符号，仅显示其完整代码

- 设置后，返回此符号的完整代码+其余符号的签名-便宜3倍

• definition_location （对象，可选）：LSP textDocument/definition 结果或紧凑

{file,line,col} 位置用于包含该定义中的确切依赖类型

• comment_mode （字符串，可选，默认值： "none")：返回代码字段的注释处理

- "none"：当前紧凑行为 - "leading"：在返回的符号代码上方放置连续的前导注释块

汽车包括：来自项目依赖关系（非外部库）的所有结构/类/接口定义

退货：紧凑模式（BREAKING）。

• 输出键： p （相对路径）加行表(h/f/s/c)，以及可选的附加表格(ih/im, bh/bm等等）
• 可选元： @ （例如。 @.t=true 截断时）

{
  "p": "src/calculator.rs",
  "h": "name|line|sig",
  "f": "add|5|pub fn add(a: i32, b: i32) -> i32",
  "s": "Calculator|15|pub struct Calculator"
}

优化：

• 使用 detail="signatures" 快速浏览（便宜10倍）
• 使用 focus_symbol 用于集中编辑（便宜3倍）
• 使用 comment_mode="leading" 当评论中的理由比原始标记最小化更重要时

典型工作流程： code_map → view_code

______________________________________________________________________

3.code_map

生成DIRECTORY的层次结构图（不是单个文件）。返回具有函数/类/类型的多个文件的结构概述。

使用时间：

• ✅ 第一次探索不熟悉的代码库
• ✅ 查找功能在多个文件中的位置
• ✅ 获取项目结构概述
• ✅ 你不知道该检查哪个文件
• ✅ 需要代码结构和类型定义（使用 with_types=true)

在以下情况下请勿使用：

• ❌ 你知道具体的文件→ use view_code
• ❌ 您需要实施细节→ use view_code 识别文件后
• ❌ 分析单个文件→ use view_code

代币成本： 中等（按项目规模缩放）

参数:

• path （string，必填）：文件或目录的路径
• max_tokens （整数，可选，默认值：2000）：输出的最大令牌数（防止溢出的预算限制）
• detail （字符串，可选，默认：“签名”）：详细级别-“最小”（仅限名称）、“签名”（名称+签名）、“完整”（包括代码）
• pattern （字符串，可选）：用于过滤文件的Glob模式（例如，“*.rs“，”src/\*\*/*.ts”）
• with_types （boolean，可选，默认值：false）：同时在同一过程中提取类型定义（结构、枚举、接口等）。比调用更有效 type_map 单独。
• count_usages （布尔值，可选，默认值：false）：当 with_types=true，还计算每种类型的使用情况。设置为 true 对于使用排名类型。

示例:

{
  "path": "/path/to/project/src",
  "max_tokens": 3000,
  "detail": "signatures",
  "pattern": "*.rs"
}

组合模式示例 （替换单独 code_map + type_map 呼叫）：

{
  "path": "/path/to/project/src",
  "max_tokens": 4000,
  "detail": "minimal",
  "with_types": true,
  "count_usages": true
}

优化：

• 开始 detail="minimal" 对于大型项目
• 使用 pattern 过滤文件
• 使用 with_types=true 而不是打电话 type_map 单独（单文件漫游vs两文件漫游）

典型工作流程： code_map → view_code （签名/完整/焦点）

退货：按相对文件路径键控的紧凑模式。

• 顶级密钥是文件路径
• 每个文件密钥： h +可选 f/s/c 行字符串
• 当 with_types=true：包括 types 带类型定义的键
• 可选元： @ （例如。 @.t=true 截断时）

{
  "src/main.rs": {
    "h": "name|line|sig",
    "f": "main|10|fn main()\ninitialize|25|fn initialize()"
  },
  "src/config.rs": {
    "h": "name|line|sig",
    "s": "Config|5|pub struct Config"
  }
}

随着 with_types=true:

{
  "src/main.rs": { "h": "name|line|sig", "f": "main|10|fn main()" },
  "types": {
    "h": "name|kind|file|line|usage_count",
    "rows": "Config|struct|src/config.rs|5|12\nUser|struct|src/models.rs|10|8"
  }
}

______________________________________________________________________

4.查找信息

查找文件中符号（函数、变量、类、类型）的所有用法。语法感知搜索，而不是文本搜索。

使用时间：

• ✅ 重构：需要查看调用函数的所有位置
• ✅ 影响分析：检查更改签名会破坏什么
• ✅ 跟踪数据流：这个变量在哪里使用？
• ✅ 重命名或修改共享代码之前

在以下情况下请勿使用：

• ❌ 你只需要结构性的改变→ use parse_diff
• ❌ 你想要风险评估→ use affected_by_diff （包括风险等级）
• ❌ 你需要复杂的模式匹配→ use query_pattern
• ❌ 符号用于>50个位置→ use affected_by_diff 或设置 max_context_lines=50

代币成本： 中高（按使用次数×上下文线缩放）

参数:

• symbol （字符串，必填）：要搜索的符号名称
• path （字符串，必填）：要搜索的文件或目录路径
• context_lines （整数，可选，默认值：3）：每次使用的上下文行数
• max_context_lines （整数，可选）：限制总上下文以防止令牌爆炸

示例:

{
  "symbol": "helper_fn",
  "path": "/path/to/project",
  "context_lines": 3,
  "max_context_lines": 50
}

优化： 集 max_context_lines=50 用于常用符号，或 context_lines=1 仅适用于地点

典型工作流程： find_usages （变更前）→ 做出改变→ affected_by_diff （验证影响）

退货：紧凑的架构。

• 输出键： sym （符号）， h 头球 u （使用行）
• 可选元： @ （例如。 @.t=true 截断时）

{
  "sym": "helper_fn",
  "h": "file|line|col|type|context|scope|conf|owner",
  "u": "src/main.rs|42|15|call|let result = helper_fn();|main|high|\nsrc/utils.rs|18|9|reference|helper_fn() + 10|Utils::apply|medium|"
}

______________________________________________________________________

5.格式参考

将精确的LSP引用位置格式化为与相同的紧凑模式 find_usages.

使用时间：

• ✅ 您已致电LSP textDocument/references
• ✅ 您需要围绕精确引用的紧凑上下文、范围、使用类型和所有者提示
• ✅ 你需要 find_usages-兼容行 conf=high

在以下情况下请勿使用：

• ❌ 您需要MCP自己发现引用→ use find_usages
• ❌ 您需要按严重性分组的编译器诊断→ use format_diagnostics

代币成本： LOW-MEDIUM（按提供的位置数量×上下文线缩放）

参数:

• symbol （字符串，必填）：这些位置解析为的符号名称
• references （数组，必填）：从1开始 {file,line,col} / {file_path,line,column} 行或LSP {uri,range:{start:{line,character}}} 行
• context_lines （整数，可选，默认值：3）：每个引用周围的上下文行
• max_tokens （整数，可选）：硬输出预算

示例:

{
  "symbol": "helper_fn",
  "references": [
    {
      "uri": "file:///path/to/src/main.rs",
      "range": {
        "start": { "line": 41, "character": 14 }
      }
    }
  ],
  "context_lines": 1
}

退货：紧凑模式与相同 find_usages.

• 输出键： sym （符号）， h 头球 u （使用行）
• conf 是 high 因为假设位置来自精确的LSP分辨率

______________________________________________________________________

6.格式诊断

将LSP诊断格式化为具有结构所有者上下文的紧凑行。

使用时间：

• ✅ 您已经拥有LSP textDocument/diagnostics
• ✅ 您需要一个令牌高效的诊断摘要
• ✅ 您想知道哪个函数/类拥有每个诊断

在以下情况下请勿使用：

• ❌ 您需要自己运行诊断程序→ 使用LSP、编译器或测试工具
• ❌ 您需要非诊断参考→ use find_usages 或 format_references

代币成本： 低-中（带诊断次数的刻度）

参数:

• diagnostics （数组，必填）：从1开始 {file,line,col} / {file_path,line,column} 行或LSP {uri,range:{start:{line,character}}} 行与 severity, message，可选 source，可选 code
• max_tokens （整数，可选，默认值：2000）：硬输出预算

示例:

{
  "diagnostics": [
    {
      "uri": "file:///path/to/src/main.rs",
      "range": {
        "start": { "line": 41, "character": 14 }
      },
      "severity": 1,
      "message": "cannot find value `foo` in this scope",
      "source": "rustc",
      "code": "E0425"
    }
  ],
  "max_tokens": 2000
}

退货：紧凑的架构。

• 输出键： h 头球 d （诊断行）
• 诊断行： severity|file|line|col|owner|source|code|message

{
  "h": "severity|file|line|col|owner|source|code|message",
  "d": "error|src/main.rs|42|15|run|rustc|E0425|cannot find value `foo` in this scope"
}

______________________________________________________________________

7.最小编辑文本

返回用于编辑一个已知符号的最小有用上下文。

使用时间：

• ✅ 编辑一个已知的函数或方法
• ✅ 您需要目标代码以及直接相关的调用者、类型和导入
• ✅ view_code(focus_symbol=...) 对于包含许多符号的文件来说仍然太大

在以下情况下请勿使用：

• ❌ 探索一个不熟悉的文件→ use code_map 或 view_code
• ❌ 您需要完全可传递的项目范围依赖关系解决方案→ use view_code(include_deps=true) 或LSP

代币成本： 低（通常比聚焦小得多 view_code 在大文件上）

参数:

• file_path （string，必填）：源文件的路径
• symbol_name （字符串，必填）：要编辑的符号
• max_tokens （整数，可选，默认值：2000）：硬输出预算
• comment_mode （字符串，可选，默认值： "none")：目标代码行的注释处理

- "none"：当前紧凑行为 - "leading"：将连续的前导注释块放在目标符号上方

示例:

{
  "file_path": "/path/to/src/workflow.ts",
  "symbol_name": "buildSummary",
  "comment_mode": "leading",
  "max_tokens": 2000
}

退货：紧凑的架构。

• target：符号的完整代码行(name|line|sig|code)
• deps：可选的相同文件和直接项目本地依赖签名行(kind|name|line|sig)
• types：可选的相同文件引用类型行(kind|name|line|sig)
• imports：可选的相关导入行(line|text)
• scope：在可用时封闭类/impl作用域

使用 comment_mode="leading" 当目标符号在声明上方的注释中具有重要理由时。

______________________________________________________________________

8.通话图

返回一个函数或方法的紧凑型尽力而为的调用者和被调用者。

使用时间：

• ✅ 你需要知道什么叫符号
• ✅ 你需要知道这个符号叫什么
• ✅ 您需要紧凑的深度-1导航或冲击上下文，而无需手动读取多文件

在以下情况下请勿使用：

• ❌ 您需要跨导入、泛型、特征或重载进行编译器级解析→ 在可用时使用LSP
• ❌ 您正在寻找非电话推荐人→ use find_usages

代币成本： 中低

参数:

• file_path （string，必填）：包含符号的源文件的路径
• symbol_name （string，必填）：要分析的函数或方法
• direction （字符串，可选，默认值： "both"): "callers", "callees"，或 "both"
• depth （整数，可选，默认值：1，最大值：3）：横向深度
• max_tokens （整数，可选，默认值：2000）：硬输出预算

示例:

{
  "file_path": "/path/to/src/workflow.rs",
  "symbol_name": "build_report",
  "direction": "both",
  "depth": 1,
  "max_tokens": 2000
}

退货：紧凑的架构。

• 输出键： sym （符号）， h 头球 edges （边缘行）
• 边缘行： direction|symbol|file|line|scope|depth

{
  "sym": "build_report",
  "h": "direction|symbol|file|line|scope|depth",
  "edges": "callee|normalize_input|src/workflow.rs|8||1\ncaller|render_page|src/workflow.rs|20||1"
}

______________________________________________________________________

9.符号_线条

使用签名和作用域链在特定行获取符号（函数/类/方法）。

使用时间：

• ✅ 从错误/堆栈跟踪中获取行号
• ✅ 需要知道“这条线有什么作用？”
• ✅ 希望在某个位置进行函数签名
• ✅ 理解范围层次结构

在以下情况下请勿使用：

• ❌ 需要完整代码→ use view_code 和 focus_symbol
• ❌ 已知道符号名称→ use view_code 直接

代币成本： 低

参数:

• file_path （string，必填）：源文件的路径
• line （整数，必填）：行号（1-索引）
• column （整数，可选，默认值：1）：列号（1-索引）

示例:

{
  "file_path": "/path/to/file.rs",
  "line": 42,
  "column": 15
}

退货：紧凑的架构。

• 输出键： sym （符号名称）， kind （缩写）， sig （签名）， l （线）， scope （范围链）

{
  "sym": "calculate",
  "kind": "fn",
  "sig": "pub fn calculate(x: i32) -> i32",
  "l": 40,
  "scope": "math::Calculator::calculate"
}

典型工作流程： symbol_at_line （查找符号）→ view_code （见代码）

______________________________________________________________________

10.parse_diff

分析结构变化与git修订。返回符号级别的diff（添加/删除/修改的函数/类），而不是行级别。

使用时间：

• ✅ 在结构层面验证您更改了什么
• ✅ 检查更改是装饰性的（格式化）还是实质性的
• ✅ 无需重新读取整个文件即可理解更改
• ✅ 生成变更摘要

在以下情况下请勿使用：

• ❌ 你需要看看什么会坏→ use affected_by_diff
• ❌ 您尚未进行更改→ use view_code
• ❌ 你需要逐行比较→ use git diff

代币成本： LOW-MEDIUM（比重新读取文件小得多）

参数:

• file_path （string，必填）：要分析的源文件的路径
• compare_to （字符串，可选，默认值：“HEAD”）：要比较的Git版本（例如，“HEAD“，“HEAD~1”，“main”，“abc123”）

示例:

{
  "file_path": "/path/to/calculator.rs",
  "compare_to": "HEAD"
}

典型工作流程： 更改后： parse_diff （验证）→ affected_by_diff （检查影响）

退货：紧凑的架构。

• 输出键： p （相对文件路径）， cmp （比较）， h 头球 changes （行）

{
  "p": "src/calculator.rs",
  "cmp": "HEAD",
  "h": "type|name|line|change",
  "changes": "fn|add|15|sig_changed: fn add(a: i64, b: i64) -> i64\nfn|multiply|25|added"
}

好处:

• 小10-40x 而不是重新读取整个文件
• 符号级别差异，而不是逐行差异
• 检测签名与仅检测身体变化
• 可用于代码生成后的验证

______________________________________________________________________

11.受影响

查找受更改影响的用法。联合 parse_diff + find_usages 显示爆炸半径和风险等级。

使用时间：

• ✅ 修改函数签名后，可能会破坏什么？
• ✅ 运行测试前-预测故障
• ✅ 重构期间-了解影响半径
• ✅ 代码更改的风险评估

在以下情况下请勿使用：

• ❌ 您尚未进行更改→ use find_usages 首先
• ❌ 你只是想看看发生了什么变化→ use parse_diff
• ❌ 更改纯粹是内部更改（没有签名更改）→ parse_diff 就足够了

代币成本： 中高（结合了parse_diff+find_usages）

参数:

• file_path （string，必填）：已更改源文件的路径
• compare_to （字符串，可选，默认值：“HEAD”）：要比较的Git版本
• scope （字符串，可选，默认值：项目根）：搜索受影响用途的目录

示例:

{
  "file_path": "/path/to/calculator.rs",
  "compare_to": "HEAD",
  "scope": "/path/to/project"
}

优化： 使用 scope 限制搜索区域的参数

典型工作流程： parse_diff （见更改）→ affected_by_diff （评估影响）→ 修复问题

退货：紧凑的架构。

• 输出键： p （相对文件路径）， h 头球 affected （行）
• risk 是以下之一： high | medium | low

{
  "p": "src/calculator.rs",
  "h": "symbol|change|file|line|risk",
  "affected": "add|sig_changed|src/main.rs|42|high\nadd|sig_changed|tests/calculator_test.rs|15|high"
}

风险等级:

• 高：影响调用站点的签名更改（错误的参数计数/类型）
• 中等：影响类型引用的签名更改、一般符号更改
• 低：整体变化（行为可能不同，但API相同），新符号

______________________________________________________________________

12.查询模式

执行自定义树型S表达式查询以进行高级AST模式匹配。返回与复杂结构模式的代码上下文匹配的结果。

使用时间：

• ✅ 查找特定语法模式的所有实例（例如，所有if语句）
• ✅ 复杂的结构查询（例如，所有带有try-catch的异步函数）
• ✅ 特定语言模式 find_usages 无法处理
• ✅ 你知道树型查询语法

在以下情况下请勿使用：

• ❌ 查找函数/变量用法→ use find_usages （更简单，跨语言）
• ❌ 你不知道树保姆语法→ use find_usages 或 view_code
• ❌ 简单的符号搜索→ use find_usages

代币成本： 中等（取决于比赛次数）

复杂性： HIGH-需要树型查询知识

建议： 更喜欢 find_usages 适用于90%的用例

参数:

• file_path （string，必填）：源文件的路径
• query （字符串，必填）：S表达式格式的树型查询
• context_lines （整数，可选，默认值：2）：每个匹配项周围的线条

示例:

{
  "file_path": "/path/to/file.rs",
  "query": "(function_item name: (identifier) @name)",
  "context_lines": 2
}

优化： 使查询尽可能具体，以减少匹配

查询语法示例:

; Find all function names
(function_item name: (identifier) @func_name)

; Find all struct definitions
(struct_item name: (type_identifier) @struct_name)

; Find all function calls
(call_expression
  function: (identifier) @function)

; Find all imports
(use_declaration) @import

退货：紧凑的架构。

• 输出键： q （查询）， h 头球 m （匹配行）

{
  "q": "(function_item name: (identifier) @name)",
  "h": "file|line|col|text",
  "m": "src/calculator.rs|5|8|add\nsrc/calculator.rs|10|8|multiply"
}

______________________________________________________________________

13.模板文本

查找与Askama模板文件关联的Rust结构。返回作为模板中变量可用的结构名称、字段和类型（解析深度可达3级）。

使用时间：

• ✅ 编辑Askama HTML模板并需要知道可用变量
• ✅ 了解传递给模板的数据
• ✅ 调试模板渲染问题

在以下情况下请勿使用：

• ❌ 不使用Askama模板
• ❌ 使用非模板文件

代币成本： 中低

参数:

• template_path （字符串，必填）：模板文件的路径（相对或绝对）

示例:

{
  "template_path": "templates/calculator.html"
}

退货：紧凑的架构。

• 输出键： tpl （相对模板路径）
• 上下文行： h + ctx （行： struct|field|type)
• 结构位置： sh + s （行： struct|file|line)

{
  "tpl": "templates/calculator.html",
  "h": "struct|field|type",
  "ctx": "CalculatorContext|result|i32\nCalculatorContext|history|Vec",
  "sh": "struct|file|line",
  "s": "CalculatorContext|src/templates.rs|12"
}

典型工作流程： template_context → 使用已知变量编辑模板

______________________________________________________________________

性能注意事项

• 解析：树型解析器经过高度优化，可以有效地处理大型文件
• 令牌限制：The code_map 该工具尊重令牌预算，以避免压倒性的AI上下文窗口
• 缓存：解析后的树不会在请求之间缓存；更喜欢 view_code 和 detail="signatures" 用于重复的轻量级读取
• 目录遍历：自动跳过隐藏文件， target/，以及 node_modules/

单程优化

两者 code_map 和 type_map 已针对单程文件遍历进行了优化：

建议：

• 使用 type_map 和 count_usages=false 当您只需要键入位置时（跳过使用计数）
• 使用 code_map 和 with_types=true 而不是分别调用这两个工具
• 对于代码结构和类型提取，组合模式只读取每个文件一次

贡献

欢迎投稿！拜托：

1. 遵循现有的代码样式（使用 cargo fmt)
2. 添加新功能的测试（我使用TDD）
3. 确保所有测试通过(cargo test)
4. 运行clippy(cargo clippy)

许可证

麻省理工学院

致谢

• 内置于 树保姆
• 实施 模型上下文协议
• 使用测试驱动开发方法开发