别再把整个代码库塞进 Prompt 了！我做了一个按需拉取的 MCP 代码上下文引擎（附 59 任务实测）

mck35
0 阅读7分钟

平时重度使用 Claude Code、Cursor、Windsurf 等 Coding Agent 写代码的朋友们，大概率都遇到过这两个让人头疼的痛点：

  1. 工具定义膨胀（Schema Bloat）：装了三四个 MCP Server 后，还没开始写第一行代码，光 tools/list 里的 JSON Schema 就先吃掉一两万 Token。
  2. 上下文供应的两难困境：
    • 全量平铺打包（如 Repomix / Gitingest）：把整个仓库拼成一个几十万 Token 的超长文本塞进上下文窗口，不仅极其昂贵，而且直接触发大模型的“大海捞针（Lost-in-the-Middle）”迷失效应。
    • 静态预算裁剪（如 ContextCraft）：在提问前用 AST + PageRank 把全仓库浓缩进 8,000 Token。这在 网页版 ChatGPT / Claude 粘贴提问 时非常好用！但在 多步自主编码 Agent 场景下，静态打包器在提问前并不知道 Agent 最终要改哪几个函数，为了在 8k 预算里塞下全仓的“地图”，往往不得不把绝大多数函数的具体实现裁剪成 仅有函数签名（Signature-only）——而 Agent 改 Bug 恰恰需要看完整的函数实现体（Full Function Body）。

为了解决自主 Agent 的上下文按需供应与 Token 预算失控问题，我开源了 token-context-mcp (v0.3.5) —— 一个专为多步编码 Agent 设计的 交互式、预算感知、AST 级代码上下文 MCP 引擎。

  • 🔗 GitHub 仓库：github.com/MCK564/toke…
  • 📦 PyPI 包名：token-context-mcp (v0.3.5，MIT 协议，纯本地运行，零云端遥测，零外部 API 依赖)
  • 🌐 MCP Registry：官方认证已入库 io.github.MCK564/token-context-mcp

🖼️ 一图看懂核心定位与三大护城河

01_hero_strengths_cn.png

token-context-mcp 不做一次性“盲猜打包”，而是让 Agent 在执行过程中像经验丰富的架构师一样 由粗到细、按需拉取（Progressive Pull）：

  1. 三层预算治理微内核（Governance Microkernel）：
    • 受 Cordis 论文（arXiv:2608.25512）启发设计的 kernel/ 治理层（注：本项目为独立开源实现，与 DeepSeek 官方无关）。
    • 单次响应预算截断（Response Cap）：每次调用均可指定 max_response_tokens（如 512 / 1024），在 AST 语法块边界优雅截断，绝不产生半截残缺代码。
    • 工具级超时熔断（Per-Tool Timeout）：内置 asyncio 执行闸门（如 get_repo_map 10s、search_source 5s），防止超大仓库卡死会话。
    • 150K 会话级防爆舱（Session Budget Tracker）：跨轮次追踪累计 Token 消耗，达到 80% 自动注入预警信号，达到 150,000 Token 硬上限直接熔断拦截，防止 Agent 陷入死循环刷爆账单。
  2. 零工具定义膨胀（Zero Schema Bloat）：
    • 默认 tools/list 仅暴露 10 个核心只读检索与导航工具（外加 10 个按需扩展工具与 2 个管理治理工具，默认隐藏不占上下文），并通过服务端 JSON Schema 极致瘦身（剥离冗余 title / default，压缩描述），把启动阶段固定开销压到最低。
  3. 增量 Tree-sitter AST + SQLite WAL 持久化图索引：
    • 基于文件 mtime_ns 与字节级 SHA-256 增量更新，支持 Python、JS/TS、Go、Rust、Java、C/C++ 多语言符号提取、跨文件调用图（Call Graph）与安全的文件监听自动失效（Watcher）。

⚙️ 真实双阶段流水线与五步渐进式拉取（Progressive Pull）

02_pipeline_architecture_cn.png

在 token-context-mcp 中，Agent 通过 5 个核心原语完成极低成本的精准定位：

  • Step 1 get_repo_map (@512 tokens)：按扇入/扇出中心度（Fan-in / Fan-out Centrality）生成全仓库骨干地图。实测在 53.8 万 Token 的 fastify 仓库 上，仅需 682 个真实 o200k_base Token（占全库 0.13%，约 790 倍体积缩减）！
  • Step 2 search_source / find_symbols：精准搜索字面量、正则表达式或符号定义，返回带行号和上下文的高信噪比片段。
  • Step 3 get_file_skeleton：只看目标文件的类与函数签名骨架，不读实现细节。
  • Step 4 get_symbol_context (@1024 tokens)：按需拉取目标函数的 完整实现源码（Full Body） + 同文件导入声明 + 直接调用者签名。实测单次仅需 523 ~ 843 o200k_base Token。
  • Step 5 get_impact_slice (depth=2)：修改代码前，基于 AST 依赖图一键分析跨文件下游调用链（Blast Radius），单次仅需 260 ~ 496 o200k_base Token。

⚖️ 为什么静态打包（Static Pack）不够用？三大范式直观对比

03_pack_vs_pull_paradigms_cn.png

客观定位：我们非常欣赏 ContextCraft 在静态打包领域的精巧设计。如果你习惯在浏览器网页端把代码粘给 ChatGPT / Claude 提问，静态打包器依然是最佳选择；但如果你使用的是 支持 MCP 协议的自主编码 Agent（Claude Code / Cursor / Windsurf / Cline），交互式按需拉取能带来质的飞跃。

📊 硬核实测数据（基于 tiktoken o200k_base 审计）

为了拒绝“拍脑袋宣传”，我们在两个真实大型开源仓库（Python 的 rich 213 个文件 / 50.7 万 Token，以及 JS/TS 的 fastify 291 个文件 / 53.8 万 Token）上，针对 59 个预先注册的真实定位与修改任务 进行了端到端实测：

04_h2h_and_m10_benchmarks_cn.png

1. 59 任务 Head-to-Head：同等 ~7.6k 预算下，完整函数体命中率提升 16.5 倍！

我们使用完全确定性的零 LLM 规则（1 次 search_source + 前 3 个候选符号的 get_symbol_context）对比 ContextCraft v0.3.2：

评测系统与配置（共 59 个任务：rich 29 + fastify 30）中位消耗 (o200k_base)完整函数体命中 (>=90% 代码行)部分函数体 (50%-89%)仅命中函数签名 (Signature Only)未命中 (Missed)
token-context-mcp v0.3.5（交互式拉取，~8k 预算）7,65233 / 59 (55.9%)2 / 59 (3.4%)11 / 59 (18.6%)13 / 59 (22.0%)
ContextCraft v0.3.2（8k 预算 + --focus "<任务描述>"）7,4692 / 59 (3.4%)0 / 59 (0.0%)28 / 59 (47.5%)29 / 59 (49.2%)
ContextCraft v0.3.2（32k 预算 + --focus "<任务描述>"，4 倍预算）29,7736 / 59 (10.2%)4 / 59 (6.8%)40 / 59 (67.8%)9 / 59 (15.3%)
ContextCraft v0.3.2（8k 默认无 Focus 全库快照）7,4501 / 59 (1.7%)0 / 59 (0.0%)12 / 59 (20.3%)46 / 59 (78.0%)

关键结论：

  • 在 同等 ~7.5k-7.6k Token 预算 下，token-context-mcp 交付了 33/59 (55.9%) 的完整函数实现，而静态 8k 打包仅能保留 2/59 (3.4%) 的完整函数体（相差 16.5 倍）。
  • 即便给静态打包器 4 倍预算（32,000 Token，实测中位数 29,773 Token），它虽然能定位到 84.7% (50/59) 的目标符号，但其中 67.8% (40/59) 依然被降级裁剪成了只有一行函数签名（Signature-only），完整函数体仅占 10.2% (6/59)。因为静态打包必须在单次快照里兼顾全仓结构，而 MCP 按需拉取可以把预算 100% 集中投向当前正在修改的 3 个核心函数！

2. M10 同等预算检索评测（rich 30 任务，~1.9k Token 预算）

在相同的 ~1,896 o200k_base Token 预算约束下对比传统 grep：

  • 文件召回率（File Recall）：从截断 Grep 的 0.57 提升至 0.90（+58%）。
  • 符号召回率（Symbol Recall）：从截断 Grep 的 0.10 提升至 0.54（5.4 倍）。

🧩 七维全景技术对比与选型指南

05_comparison_matrix_cn.png

🚀 30 秒极速安装与接入

现在可以通过 uvx 免安装直接启动，也可以通过 pip 安装：

# 方式 1：使用 uvx 一键运行当前目录（推荐）
uvx token-context-mcp quickstart .

# 方式 2：pip 安装
pip install token-context-mcp

接入 Claude Code / Cursor / Claude Desktop

1. Claude Code

claude mcp add --transport stdio --scope user token-context -- uvx token-context-mcp serve

2. Cursor

在 Cursor Settings > Features > MCP Servers 中添加：

  • Name: token-context
  • Type: command
  • Command: uvx token-context-mcp serve

3. Claude Desktop

添加至配置文件中：

{
  "mcpServers": {
    "token-context": {
      "command": "uvx",
      "args": ["token-context-mcp", "serve"]
    }
  }
}

仓库内的 launch/data/ 与 evals/ 目录已开源完整的 59 任务评测脚本与原始 JSON 数据，欢迎各位开发者动手复现、提 Issue 或点个 Star 支持！有任何关于 AST 索引、MCP 预算治理或评测方法的问题，欢迎在评论区交流讨论！

avatar
文章
阅读
粉丝