Skip to main content
Glama

[!NOTE] 原生智能体工具(正则搜索、路径匹配、文件读取)擅长处理定向查找。aptu-coder 负责机械性、非 AI 的工作:映射目录结构、提取符号、追踪调用图。将这部分工作交给专用工具可以减少 token 消耗,并在提高准确性的同时加速编码。

基准测试

在 Claude Code 上针对 Django(Python)源码树执行的认证迁移任务。完整方法论。

模式

Sonnet 4.6

Haiku 4.5

MCP

112k tokens, $0.39

406k tokens, $0.42

原生

276k tokens, $0.95

473k tokens, $0.53

节省

token 减少 59%,成本降低 59%

token 减少 14%,成本降低 21%

在 Claude Code 上针对 OpenFAST(Fortran)源码树执行的 AeroDyn 集成审计任务。完整方法论。

模式

Sonnet 4.6

Haiku 4.5

MCP

472k tokens, $1.65

687k tokens, $0.72

原生

877k tokens, $2.85

2162k tokens, $2.21

节省

token 减少 46%,成本降低 42%

token 减少 68%,成本降低 68%

Related MCP server: CodeGraphMCPServer

概述

aptu-coder 是一个 Model Context Protocol 服务器,为 AI 智能体提供关于代码库的精确结构上下文:目录树、符号定义和调用图,而无需读取原始文件。它支持 18 种语言(参见支持的语言),并可与任何兼容 MCP 的编排器集成。

支持的语言

语言

扩展名

Astro

.astro

C/C++

.c, .cc, .cpp, .cxx, .h, .hpp, .hxx

C#

.cs

CSS

.css

Fortran

.f, .f77, .f90, .f95, .f03, .f08, .for, .ftn

Go

.go

HTML

.html, .htm

Java

.java

JavaScript

.js, .mjs, .cjs

JSON

.json

Kotlin

.kt, .kts

Markdown

.md, .mdx

Python

.py

Rust

.rs

TOML

.toml

TSX

.tsx

TypeScript

.ts

YAML

.yaml, .yml

安装

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 客户端

提供两种传输方式。当使用会派生委托智能体的编排器(如 goose coder)时,推荐使用 Streamable HTTP:单个服务器进程在编排器和所有智能体之间共享,消除了每个 stdio 子进程获得独立实例时出现的扩展漂移问题。

Streamable HTTP(推荐用于多智能体设置)

使用 Homebrew,一条命令即可在登录时启动服务器并保持其运行:

brew services start aptu-coder

Homebrew 公式默认在端口 49200 上启动服务器。然后只需在 ~/.config/goose/config.yaml 中添加一次扩展:

extensions:
  aptu-coder:
    type: streamable_http
    uri: http://127.0.0.1:49200/mcp
    name: aptu-coder
    timeout: 300

或者用于 Claude Code:

claude mcp add --transport http aptu-coder http://127.0.0.1:49200/mcp

要使用不同的端口,请在重启前设置 APTU_CODER_PORT:

APTU_CODER_PORT=4000 brew services restart aptu-coder

要直接启动而不使用 brew services:

aptu-coder --port 49200
# or equivalently
APTU_CODER_PORT=49200 aptu-coder

stdio(单客户端使用)

适用于只有一个进程需要服务器的情况。客户端拥有进程生命周期并自动启动它:

claude mcp add --transport stdio aptu-coder -- aptu-coder

或者手动添加到项目根目录的 .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

每页条目数

工具

用途

语言

analyze_directory

目录树,包含代码行数、函数和类计数;遵循 .gitignore

全部

analyze_file

函数、类和导入,包含签名和行范围;对不支持的扩展名返回优雅降级(行数、文件头部、无 AST)

全部

analyze_module

轻量级函数和导入索引(比 analyze_file 小约 75%);对不支持的扩展名返回优雅降级(带说明的空索引)

全部

analyze_symbol

目录中命名符号的调用图;调用者、被调用者、调用深度

全部

edit_overwrite

创建或覆盖文件;自动创建父目录

任意文件

edit_replace

替换唯一的精确文本块或所有不重叠的出现(replace_all=true);零个或多个匹配时返回错误;空的 new_text 删除该块;匹配前进行 CRLF 规范化;可选的 expected_content_hash(原始字节的 blake3 十六进制)拒绝过期编辑;对同一文件的并发编辑按路径串行化;返回 occurrences_replaced 计数

全部

exec_command

运行 shell 命令;返回 stdout、stderr、退出码;输出有上限并经过过滤;可选的 timeout_secs(到期时终止)和 drain_timeout_secs(退出后排空窗口);heredoc 在生成前被拒绝(文件写入模式、stdin 消耗标志、stdin 参数冲突或缺少结束分隔符)

任意

工具参数、约束和示例可通过 MCP 客户端的工具检查器或 tools/list 响应获取。

MCP 资源

知识图谱功能暴露了 MCP 资源模板,用于导航在 analyze_symbol 调用期间构建的结构图。资源通过 URI 寻址;使用 resources/templates/list 发现可用的模板。

URI 模板

描述

aptu-coder://graph/{repo_hash}/blast-radius/{symbol}?depth={depth}

从符号向外到可配置深度的 BFS 遍历(默认:3)。以径向布局返回调用者/被调用者链。

aptu-coder://graph/{repo_hash}/subgraph/{symbol}

单个符号的完整子图(调用者、被调用者及其连接)。

分页: 结果分页返回;传递先前响应中的不透明 cursor 值以获取下一页。

深度参数: blast-radius 模板接受可选的 depth 查询参数(1-5 范围内的整数,默认 3)。

冷缓存: 首先在目录上调用 analyze_symbol 以构建图。在图可用之前,资源返回一条信息性消息。

输出管理

对于大型代码库,有几种机制可防止上下文溢出。

分页

analyze_file 和 analyze_symbol 在输出被截断时追加 NEXT_CURSOR: 行。将 token 作为 cursor 传回以获取下一页。summary=true 和 cursor 互斥;同时传递两者会返回错误。

# Response ends with:
NEXT_CURSOR: eyJvZmZzZXQiOjUwfQ==

# Fetch next page:
analyze_symbol path: /my/project symbol: my_function cursor: eyJvZmZzZXQiOjUwfQ==

exec_command 输出上限

exec_command 应用三个独立的字节级上限,以防止大型命令输出淹没上下文:

流

上限

行为

stdout

30,000 字符

保留尾部;保留最后 30k 字符

stderr

10,000 字符

保留尾部;错误出现在末尾

合并后的 output_text

50,000 字符

交错后的安全网

30k stdout 上限是数据驱动的:对 27,981 次观察到的 exec_command 调用的分析显示,只有 0.33% 超过此限制。当任何上限触发时,响应中会设置 output_truncated: true,并记录在 JSONL 指标中。

drain_timeout_secs 控制服务器在子进程退出后等待仍持有管道打开的后台子进程的时间。默认值为 500 毫秒(0 或省略)。负值返回 INVALID_PARAMS。当排空窗口在管道关闭前到期时,会设置 output_truncated: true。

exec_command 输出过滤器

内置过滤器表会在输出到达模型之前抑制来自嘈杂 CLI 工具的逐文件噪音。过滤器仅成功时应用于 stdout、stderr 和交错输出;失败时始终保留原始输出。

命令

行为

git pull

去除 diff-stat 噪音(管道竖线、create mode、delete mode、rename、mode change 行);空输出替换为 ok (up-to-date)

git fetch

去除 From 和引用范围行;限制为 10 行;空输出替换为 ok fetched

git push

去除 remote: 进度行和 To 目标行;限制为 10 行;空输出替换为 ok pushed

git log

限制为 20 行

git status

限制为 20 行

git show

去除补丁块(@@ 头和 +/- diff 行);限制为 200 行

git commit

去除 GPG 签名和 gitleaks 钩子输出;限制为 10 行;空输出替换为 ok committed

git diff

去除 ANSI 转义序列;限制为 100 行;空输出替换为 ok (working tree clean)

git add

去除 gitleaks 钩子输出;限制为 5 行;空输出替换为 ok staged

cargo build

去除 Compiling / Checking / Downloading / Fresh 行;空输出替换为 ok (build clean)

cargo test

去除 Compiling / Checking / Fresh 行

项目本地规则可以添加到 .aptu/filters.toml 中。解析错误和无法识别的 schema_version 值(version != 1)会回退到内置表并记录警告;不会发生崩溃。当过滤器触发时,structuredContent 中的 filter_applied 会标识匹配的规则。

非交互式管道

在单次传递的子代理会话中,提示缓存会被写入但永远不会被重用。基准测试显示,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 客户端会自动将此工作流呈现给代理。

环境变量

缓存和运行时

变量

默认值

描述

APTU_CODER_DIR_CACHE_CAPACITY

20

目录分析结果的 LRU 缓存大小。

APTU_CODER_DISK_CACHE_DIR

$XDG_DATA_HOME/aptu-coder/analysis-cache

analyze_symbol 使用的 L2 磁盘调用图缓存目录。如果不存在则自动创建。

APTU_CODER_DISK_CACHE_DISABLED

未设置

设置为 1 以完全禁用 L2 磁盘缓存。

APTU_CODER_FILE_CACHE_CAPACITY

100

文件分析结果的 LRU 缓存大小。

APTU_CODER_METRICS_EXPORT_FILE

未设置

关闭时一次性 JSONL 指标导出的绝对路径。

APTU_CODER_PORT

未设置

可流式 HTTP 模式的端口。等同于 --port N;--port 优先。当未设置且未传递 --port 时,使用 stdio 模式。

APTU_CODER_BEARER_TOKEN

未设置

Streamable HTTP 传输认证的 Bearer 令牌。如果值少于 32 个字符,会记录警告。

APTU_SHELL

未设置

exec_command 使用的 Shell。默认为 bash,然后是 /bin/sh。

可观测性

有关 JSONL 模式、OTel 配置和跨度属性策略,请参阅:

文档

  • AGENTS.md - 贡献者参考:项目结构、命令、rmcp 陷阱、工具参数约束

  • ARCHITECTURE.md - 设计目标、模块图、数据流、语言处理器系统、缓存策略

  • CONTRIBUTING.md - 开发工作流、提交约定、PR 检查清单

  • DESIGN-GUIDE.md - 设计决策、理由,以及构建高性能 MCP 服务器的复制指南

  • MCP Best Practices - 代理循环、编排模式、MCP 工具设计、内存管理和安全控制的最佳实践

  • METRICS.md - 指标模式、JSONL 格式和保留策略

  • ROADMAP.md - 开发历史和未来方向

  • SECURITY.md - 安全策略和漏洞报告

许可证

Apache-2.0。详情请参阅 LICENSE。

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    A lightning-fast, language-agnostic code analysis MCP (Model Context Protocol) server built in Rust
    9
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    A lightweight, zero-configuration MCP server for source code analysis with GraphRAG capabilities, enabling structural understanding and efficient code completion from MCP-compatible AI tools.
    38 PyPI
    14
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    A persistent, tree-sitter-backed code knowledge cache MCP server that reduces token usage by storing parsed structure and enabling fast symbol lookup, inheritance graph, call graph, and semantic search.
    1
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Universal MCP server that analyzes any codebase and provides structured context to AI assistants. Dynamic, accurate, and token-efficient.
    18
    7 npm
    MIT