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

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

工具定义膨胀（Schema Bloat） ：装了三四个 MCP Server 后，还没开始写第一行代码，光 tools/list 里的 JSON Schema 就先吃掉一两万 Token。
上下文供应的两难困境 ：
- 全量平铺打包（如 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

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

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

三层预算治理微内核（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 陷入死循环刷爆账单。
零工具定义膨胀（Zero Schema Bloat） ：
- 默认 tools/list 仅暴露 10 个核心只读检索与导航工具 （外加 10 个按需扩展工具与 2 个管理治理工具，默认隐藏不占上下文），并通过服务端 JSON Schema 极致瘦身（剥离冗余 title / default，压缩描述），把启动阶段固定开销压到最低。
增量 Tree-sitter AST + SQLite WAL 持久化图索引 ：
- 基于文件 mtime_ns 与字节级 SHA-256 增量更新，支持 Python、JS/TS、Go、Rust、Java、C/C++ 多语言符号提取、跨文件调用图（Call Graph）与安全的文件监听自动失效（Watcher）。

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

在 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）不够用？三大范式直观对比

客观定位 ：我们非常欣赏 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 个预先注册的真实定位与修改任务 进行了端到端实测：

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,652	33 / 59 (55.9%)	2 / 59 (3.4%)	11 / 59 (18.6%)	13 / 59 (22.0%)
`ContextCraft v0.3.2`（`8k` 预算 + `--focus "<任务描述>"`）	7,469	2 / 59 (3.4%)	0 / 59 (0.0%)	28 / 59 (47.5%)	29 / 59 (49.2%)
`ContextCraft v0.3.2`（`32k` 预算 + `--focus "<任务描述>"`，4 倍预算）	29,773	6 / 59 (10.2%)	4 / 59 (6.8%)	40 / 59 (67.8%)	9 / 59 (15.3%)
`ContextCraft v0.3.2`（`8k` 默认无 Focus 全库快照）	7,450	1 / 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 倍）。

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

🚀 30 秒极速安装与接入

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

bash 复制代码

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

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

接入 Claude Code / Cursor / Claude Desktop

1. Claude Code

bash 复制代码

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

添加至配置文件中：

json 复制代码

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

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