jcodemunch-mcp Skill：让 AI 代码探索节省 95%+ token 的 MCP Server

总结

jcodemunch-mcp 是一个基于 tree-sitter AST 的精确代码检索 MCP Server，让 AI Agent 在探索代码库时节省 95%+ 的 token 消耗。传统 Agent 靠 grep+整文件读取扫描代码上下文，平均每次查询消耗约 27 倍 token；jcodemunch-mcp 索引一次代码库，之后每次只取函数、类、方法、符号级别的精确代码片段，token 降幅实测中位数 27.4 倍。截至 2026-08-26，项目已为用户节省超过 838B tokens、136,000+ 次安装报告、$4.2M+ 的 AI 支出，在 GitHub 累计获得约 2,600 星。

功能与原则

jcodemunch-mcp 的核心功能是将代码库解析为结构化符号索引（signature、kind、qualified name、byte offsets），Agent 查询时只返回精确符号实现而非整文件读取。它采用 three-step 工作流：索引（index once，解析所有源文件的 AST）→ 符号检索（search_symbols 找函数/类/方法）→ 精确拉取（get_symbol_source 按 byte offset 取实现片段）。设计原则是”精度优于广度”——让 AI 的 context window 留给真正的业务逻辑，而不是浪费在扫描无关代码行上。

认可度

• GitHub Star：约 2,600 星（截至 2026-08-26），创建于 2026-02-09，6 个月内从 0 增长至 2,600 星，增长曲线陡峭
• 安装量：136,000+ 次安装报告（平台统计）
• 节省数据：838B+ tokens saved，$4.2M+ AI spend avoided，100,000+ kg CO₂ prevented
• Trendy 特征：2026 年 8 月持续出现在 GitHub Topics/token-efficient 列表头部，被多个 MCP 排行榜收录（Official MCP Registry、Glama、Claude Skills Info 等）
• ** forks：357（高 Fork/Star 比，说明有大量用户拿去二次开发）

链接

GitHub：https://github.com/jgravelle/jcodemunch-mcp

原作者

jgravelle（GitHub username）——专注代码效率工具的独立开发者，主导 jcodemunch 系列（MCP Server + VS Code 插件 + OSS 代码健康观测平台），理念是”context is the scarce resource”。

介绍

大多数 AI Agent 探索代码库的方式是：先用 grep 定位相关文件，再整文件读取、扫描无关行。这个过程在 token 层面极其昂贵——以 Express.js（186 文件）为例，一次普通函数查找平均消耗 15,724 tokens，FastAPI（1,186 文件）则高达 85,296 tokens。

jcodemunch-mcp 改变了这个范式。它用 tree-sitter 解析源代码，构建本地符号索引（包含每个符号的签名、类型、qualified name、byte offsets），Agent 查询时只取目标函数的精确字节范围，而非整个文件。实测数据：Express.js 平均 1,002 tokens（节省 15.7 倍），FastAPI 平均 2,271 tokens（节省 37.6 倍），Gin 平均 1,577 tokens（节省 20.3 倍）。整体中位数节省 27.4 倍，97% 以上的 token 消耗被消除。

项目同时提供 get_blast_radius（改 X 会影响哪些模块）、find_importers（谁在调用这个函数）、get_class_hierarchy（类继承链）、find_dead_code（死代码检测）等高级查询能力，这些都是传统 grep+Read 工具无法原生回答的结构化问题。

特点

• 86-99% token 节省：实测中位数 27.4 倍 fewer tokens，per-query 范围从 7.3 倍到 79.8 倍不等
• tree-sitter AST 解析：支持 25+ 编程语言，符号级精度而非文本匹配
• 爆炸半径分析：get_blast_radius 能回答”改这个函数会影响哪些调用方”，传统工具做不到
• 零额外上下文污染：只拉取符号的精确实现，不附带周围的无关代码行
• 多客户端兼容：官方支持 Claude Code、Cursor、VS Code、Codex CLI、Windsurf、Continue，通用 MCP 协议使其可接入任何兼容客户端
• MCP 协议标准实现：在 Official MCP Registry 登记，版本活跃（v1.108.300，2026-08-26 最新）

使用方法

安装 MCP Server：

# 方式1：uvx（推荐，零全局安装）
uvx jcodemunch-mcp

# 方式2：pip
pip install jcodemunch-mcp

配置 MCP 客户端（以 Claude Code 为例，在 ~/.claude/settings.json 或项目级 MCP 配置）：

{
  "mcpServers": {
    "jcodemunch-mcp": {
      "command": "uvx",
      "args": ["jcodemunch-mcp"]
    }
  }
}

基本调用流程：

1. 首次使用，jcodemunch-mcp 自动对当前目录代码库建立索引（只跑一次）
2. 询问 Agent：”Find the authenticate_user function and show me who calls it”
3. Agent 调用 search_symbols 定位符号，再调用 get_symbol_source 取精确实现
4. 若需分析影响范围，调用 get_blast_radius 查调用链

最小示例：

User: Explain what the validate_token function does and list all its callers.

Agent (uses jcodemunch-mcp):
  → search_symbols: "validate_token"
  → get_symbol_source: <token 函数实现>
  → find_importers: <所有调用方>

使用场景与人群

适用场景：

• 大型代码库（500+ 文件）的维护与重构——避免 context overflow
• 多日 AI Agent 任务——索引一次，后续查询极低 token 消耗
• 代码审查工作流——快速定位函数定义和所有调用方
• 死代码检测与代码健康分析
• 团队代码所有权分析（谁负责哪个模块的调用链）

目标用户：

• Claude Code / Cursor / VS Code 重度用户
• 需要在大型代码库上运行 AI 任务的开发者
• MCP 生态深度用户
• 对 token 成本敏感的个人开发者和小型团队

输入与输出案例

案例 1：定位并理解函数

• Input：Explain what create_access_token does in this codebase, and show me all the places that call it.
• Output：
• 函数签名：def create_access_token(user_id: str, expires_delta: timedelta) -> str
• 功能：基于 JWT 的访问令牌生成，带过期时间管理
• 调用方列表：
  • src/api/auth.py:42 → /login 路由
  • src/middleware/session.py:18 → 会话刷新逻辑
  • tests/test_auth.py:67 → 测试夹具
• Token 消耗：jcodemunch-mcp 本次查询约 890 tokens vs 传统方式约 12,400 tokens（节省 13.9 倍）

案例 2：爆炸半径分析

• Input：If I change the send_email function in src/utils/notification.py, what will break?
• Output：
• 直接调用方（3 个）：
  • src/services/user.py:156
  • src/tasks/worker.py:89
  • tests/test_notifications.py:44
• 间接调用方（1 个）：
  • src/api/webhooks.py:23 → 调用 user.py 间接依赖
• 结论：修改需同步检查 user.py 的调用逻辑，webhooks.py 需回归测试

GitHub: https://github.com/jgravelle/jcodemunch-mcp