aptu-coder

使用 tree-sitter 进行代码结构分析的独立 MCP 服务器。OpenSSF 银牌认证：仅有不到 1% 的开源项目达到此级别。

## 基准测试 在 Claude Code 上针对 [Django](https://github.com/django/django)（Python）源代码树进行身份验证迁移任务。[完整方法论](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/benchmarks/v12/methodology.md)。 | 模式 | Sonnet 4.6 | Haiku 4.5 | |---|---|---| | MCP | 112k tokens, $0.39 | 406k tokens, $0.42 | | 原生 | 276k tokens, $0.95 | 473k tokens, $0.53 | | **节省** | **减少 59% tokens，节省 59%** | **减少 14% tokens，节省 21%** | 在 Claude Code 上针对 [OpenFAST](https://github.com/OpenFAST/openfast)（Fortran）源代码树进行 AeroDyn 集成审计任务。[完整方法论](https://github.com/clouatre-labs/aptu-coder/blob/main/docs/benchmarks/v13/methodology.md)。 | 模式 | Sonnet 4.6 | Haiku 4.5 | |---|---|---| | MCP | 472k tokens, $1.65 | 687k tokens, $0.72 | | 原生 | 877k tokens, $2.85 | 2162k tokens, $2.21 | | **节省** | **减少 46% tokens，节省 42%** | **减少 68% tokens，节省 68%** | ## 概述 aptu-coder 是一个模型上下文协议服务器，为 AI 代理提供代码库的精确结构上下文：目录树、符号定义和调用图，无需读取原始文件。它支持 Rust、Python、Go、Java、TypeScript、TSX、Fortran、JavaScript、C/C++ 和 C#，并可与任何 MCP 兼容的编排器集成。 ## 支持的语言 所有语言默认启用。可通过 Cargo 特性标志在编译时禁用单个语言。 | 语言 | 扩展名 | 特性标志 | |----------|------------|--------------| | Rust | `.rs` | `lang-rust` | | Python | `.py` | `lang-python` | | TypeScript | `.ts` | `lang-typescript` | | TSX | `.tsx` | `lang-tsx` | | Go | `.go` | `lang-go` | | Java | `.java` | `lang-java` | | Fortran | `.f`, `.f77`, `.f90`, `.f95`, `.f03`, `.f08`, `.for`, `.ftn` | `lang-fortran` | | JavaScript | `.js`, `.mjs`, `.cjs` | `lang-javascript` | | C | `.c` | `lang-cpp` | | C++ | `.cc`, `.cpp`, `.cxx`, `.h`, `.hpp`, `.hxx` | `lang-cpp` | | C# | `.cs` | `lang-csharp` | 若要使用部分语言构建，请禁用默认特性并手动选择： ``` [dependencies] aptu-coder-core = { version = "*", default-features = false, features = ["lang-rust", "lang-python"] } ``` 当前版本已发布在 [crates.io](https://crates.io/crates/aptu-coder-core)。如果您更喜欢固定依赖版本，请将 `"*"` 替换为最新的版本字符串。 ## 安装 ### Homebrew（macOS 和 Linux） ``` brew install clouatre-labs/tap/aptu-coder ``` 更新：`brew upgrade aptu-coder` ### cargo-binstall（无需 Rust） ``` cargo binstall aptu-coder ``` ### cargo install（需要 Rust 工具链） ``` cargo install aptu-coder ``` ## 快速开始 ### 从源码构建 ``` cargo build --release ``` 二进制文件位于 `target/release/aptu-coder`。 ### 配置 MCP 客户端 通过 brew 或 cargo 安装后，使用 Claude Code CLI 注册： ``` claude mcp add --transport stdio aptu-coder -- aptu-coder ``` 如果是从源码构建，请直接使用二进制文件路径： ``` claude mcp add --transport stdio aptu-coder -- /path/to/repo/target/release/aptu-coder ``` stdio 是有意为之的：该服务器在本地运行，直接在磁盘上处理文件。低延迟、零网络开销的传输方式非常适合这种用例。可流式传输的 HTTP 会增加不必要的网络跳转，对本地工具毫无益处。 或者手动添加到项目根目录的 `.mcp.json` 中（通过版本控制与团队共享）： ``` { "mcpServers": { "aptu-coder": { "command": "aptu-coder", "args": [] } } } ``` ## 工具 所有可选参数均可省略。`analyze_directory`、`analyze_file` 和 `analyze_symbol` 的共享可选参数： | 参数 | 类型 | 默认值 | 描述 | |-----------|------|---------|-------------| | `summary` | boolean | auto | 紧凑输出；超过 50K 字符时自动触发 | | `cursor` | string | -- | 分页游标，来自上一次响应的 `next_cursor` | | `page_size` | integer | 100 | 每页项目数 | | `force` | boolean | false | 绕过输出大小警告 | | `verbose` | boolean | false | 完整输出，包含节标题和导入信息 | `summary=true` 和 `cursor` 互斥。同时传递两者会返回错误。 | 工具 | 用途 | 语言 | |------|---------|-----------| | `analyze_directory` | 包含 LOC、函数和类计数的目录树；遵守 `.gitignore` | 全部 | | `analyze_file` | 函数、类和导入，包含签名和行范围 | 全部 | | `analyze_module` | 轻量级函数和导入索引（比 `analyze_file` 小约 75%） | 全部 | | `analyze_symbol` | 命名符号的调用图，跨越目录；调用者、被调用者、调用深度 | 全部 | | `analyze_raw` | 带行号的原始文件内容；可选的起始/结束行范围；通过 `next_start_line` 分页 | 任意文件 | | `edit_overwrite` | 创建或覆盖文件；创建父目录 | 任意文件 | | `edit_replace` | 替换唯一的精确文本块；如果零个或多个匹配则报错 | 全部 | | `edit_rename` | 文件内的 AST 感知重命名；跳过字符串和注释中的标识符 | 全部 | | `edit_insert` | 在命名 AST 节点之前或之后插入内容 | 全部 | | `exec_command` | 运行 shell 命令；返回 stdout、stderr、退出码和超时状态；支持进度通知 | 任意 | 工具参数、约束和示例可通过 MCP 客户端的工具检查器或 `tools/list` 响应获取。 ## 输出管理 对于大型代码库，有两种机制防止上下文溢出： **分页** 当输出被截断时，`analyze_file` 和 `analyze_symbol` 会附加 `NEXT_CURSOR:` 行。将该令牌作为 `cursor` 传回以获取下一页。`summary=true` 和 `cursor` 互斥；同时传递两者会返回错误。 ``` # Response ends with: NEXT_CURSOR: eyJvZmZzZXQiOjUwfQ== # Fetch next page: analyze_symbol path: /my/project symbol: my_function cursor: eyJvZmZzZXQiOjUwfQ== ``` **摘要模式** 当输出超过 50K 字符时，服务器会自动压缩结果，使用聚合统计信息。可通过 `summary: true`（强制压缩）或 `summary: false`（禁用）覆盖此行为。 ``` # Force summary for large project analyze_directory path: /huge/codebase summary: true # Disable summary (get full details, may be large) analyze_directory path: /project summary: false ``` ## 非交互式管道 在单次传递的子代理会话中，提示缓存会被写入但从不重用。基准测试显示，MCP 响应写入缓存的内容比纯原生工作流多约 2 倍，增加成本却无法提升质量。请设置 `DISABLE_PROMPT_CACHING=1`（或对于 Haiku 特定管道设置 `DISABLE_PROMPT_CACHING_HAIKU=1`）以避免此开销。 服务器自身的指令为未知代码库暴露了 4 步推荐工作流：使用 `analyze_directory` 在 `max_depth=2` 下调查仓库根目录，深入源代码包，在关键文件上运行 `analyze_module` 获取函数/导入索引（或者需要签名和类型时使用 `analyze_file`），然后使用 `analyze_symbol` 追踪调用图。公开服务器指令的 MCP 客户端会自动向代理呈现此工作流。 ## 环境变量 | 变量 | 默认值 | 描述 | |---|---|---| | `CODE_ANALYZE_FILE_CACHE_CAPACITY` | `100` | 进程内 LRU 缓存保留的最大文件分析结果数量。对于需要重复查询大量文件的大型仓库，请增加此值。 | | `CODE_ANALYZE_DIR_CACHE_CAPACITY` | `20` | 进程内 LRU 缓存保留的最大目录分析结果数量。 | | `DISABLE_PROMPT_CACHING` | 未设置 | 设置为1` 以禁用提示缓存（建议用于单次传递的子代理会话）。 | | `DISABLE_PROMPT_CACHING_HAIKU` | 未设置 | 设置为 `1` 仅对 Haiku 特定管道禁用提示缓存。 | ## 可观测性 所有十个工具都会将指标发送到 `$XDG_DATA_HOME/aptu-coder/`（回退：`~/.local/share/aptu-coder/`）中每日轮换的 JSONL 文件。每条记录包含工具名称、耗时、输出大小和结果状态。文件保留 30 天。完整模式请参阅 [docs/OBSERVABILITY.md](

标签：AI开发工具, Fortran分析, IPv6支持, JS文件枚举, MCP, Model Context Protocol, Python分析, Rust, tree-sitter, UML, 云安全监控, 代码分析, 代码导航, 代码搜索引擎, 代码理解, 代码索引, 代码结构, 凭证管理, 可视化界面, 数据可视化, 日志审计, 符号分析, 网络流量审计, 调用图分析, 软件分析工具, 逆向工具, 通知系统, 静态分析