内容
# Arborist MCP
Arborist MCP 是一个混合的 Rust + Python 工作空间，用于语义代码分析、补丁验证、持久化符号索引和轻量级_stdio MCP网关。
当前层:
- `crates/arborist-core`:基于Tree-sitter的Rust解析核心，具有语义提取、符号图索引、补丁验证、VFS状态和SQLite持久化。
- `crates/arborist-py`:PyO3桥接器，将Rust核心暴露给Python作为 `_arborist_core`。
- `python/arborist_mcp`:stdio上的MCP兼容JSON-RPC网关。
## 文档
- [开发指南](docs/development.md)：设置、检查、CI配置文件、测试套件、构建工件和常见故障。
- [协议指南](docs/protocol.md)：MCP用法、旧版JSON-RPC兼容性、工具目录生成和协议验证。
- [工具指南](docs/tools.md)：支持的工具家族、源覆盖层、补丁预览、符号索引、跟踪/上下文工作流和C/C++状态。
- [生成的工具目录](docs/tool-catalog.json)：确切的`tools/list`快照。
## 语言支持
Arborist当前支持Python、C和C++源文件。语言路由基于扩展名：
- Python：`.py`、`.pyi`
- C语法：`.c`、`.h`
- C++语法：`.cc`、`.cpp`、`.cxx`、`.c++`、`.tpp`、`.tcc`、`.ipp`、`.inl`、`.hpp`、`.hh`、`.hxx`、`.h++`
## 已实现工具家族
MCP目录当前返回58种工具：
- 读取工具：29，包括批量读取、语义骨架、补丁预览、有界原始Tree-sitter查询与协同超时预算、符号读取、符号列表/搜索和图支持的读取包。
- 写入工具：2，`patch_ast_node`和`patch_ast_node_at_position`。
- VFS工具：10，包括打开/更改/关闭、虚拟补丁、字节编辑、提交/丢弃和虚拟读取。
- 索引工具：9，涵盖注册、注销、列表、检查、迁移、重建、工作区刷新和文件刷新，用于持久化符号索引。
- 跟踪工具：8，涵盖图/邻域跟踪以及跟踪支持的回放和验证。
## 快速入门
在Windows上：
```powershell
python -m venv .venv
. .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install "maturin>=1.7,<2.0"
maturin develop --locked
.\scripts\sync-extension.ps1 -SkipBuild
python scripts\gateway_smoke.py --require-core
python -m arborist_mcp.gateway --help
```
或者运行：
```powershell
.\scripts\bootstrap.ps1
```
## 索引监视
使用轮询监视命令保持一个持久索引同步而不重写它：
```powershell
arborist-index-watch --workspace-root . --db-path .\symbols.db
arborist-index-watch --workspace-root . --db-path .\symbols.db --once
arborist-index-watch --workspace-root . --db-path .\symbols.db --once --timeout-ms 5000
arborist-index-watch --workspace-root . --db-path .\symbols.db --once --dry-run
arborist-index-watch --workspace-root . --db-path .\symbols.db --check
```
监视器通过增量工作区刷新路径刷新缺失的索引和当前模式新鲜度问题。它在需要手动干预时退出而不写入，例如不支持或外部SQLite模式。`--timeout-ms`限制健康新鲜度读取和工作区协调扫描以及刷新索引工作。`--dry-run`报告`would_refresh`或`would_migrate`而不更改索引。`--check`执行一次无写入检查，并在除非所有目标都健康时返回非零退出状态，这对于CI和部署检查很有用。
## 快速验证
对于正常的本地循环：
```powershell
.\scripts\test.ps1 -Suite inner-loop
```
## MCP用法
最小MCP服务器配置：
```json
{
"mcpServers": {
"arborist": {
"command": "python",
"args": ["-m", "arborist_mcp.gateway"],
"cwd": "E:/workspace/arborist-mcp"
}
}
}
```
## 核心能力
- 具有稳定选择器、符号ID、签名、字节范围、参数、返回类型和文档字符串的语义骨架。
- 用于未保存文件分析的单次源覆盖，包括持久索引读取/跟踪/列表/搜索覆盖，当提供`index_db_path`时。
- 返回验证和统一差异而无需写入磁盘的补丁预览工具。
- MCP资源公开生成的工具目录快照，供喜欢资源读取而非`tools/list`的客户端使用。
- 具有结构化绑定决策、提交门控、绕过审计和跟踪支持的回放验证的语义补丁。
- 具有打开/更改/关闭、虚拟补丁、提交/丢弃和增量Tree-sitter编辑的会话作用域VFS。
- Python/C工作区符号图索引、列表、搜索、读取、跟踪、有界邻域上下文和直接跟踪扩展的可选协同预算。
- SQLite支持的持久符号索引，具有事务性v1-v3到v4模式迁移和源重新索引、健康检查、响应模式版本控制、过时/丢失/不可读/未索引的文件诊断、有界工作区扫描、可选的每个文件字节限制和协同时间预算、部分刷新和损坏或无关数据库的故障关闭处理。
- C include-family跟踪和补丁消歧义，用于头文件/源项目，包括重复全局变量和文件局部`static`符号。
