jgravelle/jcodemunch-mcp · 上手攻略

仓库：jgravelle/jcodemunch-mcp
链接：https://github.com/jgravelle/jcodemunch-mcp
分类：MCP 工具 / 代码检索 / 成本优化
作者：Tom
更新：2026-07-24

这是什么

jCodeMunch 是一个基于 tree-sitter AST 解析的 MCP 服务器，专门解决 AI Agent 在代码库探索时「读整个文件找一句话」的 token 浪费问题。它对仓库做一次索引，之后每次检索只返回精确的函数、类、方法、常量符号——实测平均减少 95%+ 的 token 消耗（官方 live benchmark 2026-07-23：15 项任务平均 99.6% 压缩率，峰值 99.9%）。支持 Python、TypeScript、Go、Rust、Java、C++ 等 20+ 语言，与 Claude Code、Cursor、Windsurf、VS Code、Codex CLI、Continue 等所有 MCP 兼容客户端无缝配合。

解决什么问题

AI Agent 读代码的默认方式是：打开文件 → 扫几千行无关代码 → 找到要用的那个函数 → 换下一个文件继续扫。这是 token 预算的最大隐形杀手，尤其在大型代码库里。jCodeMunch 把这个过程倒转：索引一次，精确取用。一个 MCP 工具调用只传输 Agent 真正需要的那几行，而不是整个文件。

快速安装

方式一：pip（推荐验证方式）

pip install jcodemunch-mcp
jcodemunch-mcp --help          # 验证安装

方式二：uvx（即时运行，无需预装）

uvx jcodemunch-mcp

⚠️ uvx 是 uv 的即时运行模式，无需 pip install，推荐用于 MCP 客户端配置。若用 uvx 报「command not found」，先安装 uv：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"（Windows）或对应平台的安装脚本，然后完全重启编辑器让 PATH 生效。

从源码安装（版本稳定需求高的 B2B 场景）

pip install git+https://github.com/jgravelle/jcodemunch-mcp.git
# 或
uvx --from git+https://github.com/jgravelle/jcodemunch-mcp.git jcodemunch-mcp

核心用法

1. 三步完成初始化（推荐）

jcodemunch-mcp init

init 会： - 自动检测已安装的 MCP 客户端（Claude Code、Claude Desktop、Cursor、Windsurf、Continue） - 写入各客户端的 MCP 配置文件 - 安装 CLAUDE.md 提示策略（让 Agent 主动使用 jCodeMunch 而非原生文件工具） - 可选：安装 enforcement hooks（--hooks）、索引当前项目（--index）、审计配置（--audit）

非交互式 / CI 场景

jcodemunch-mcp init --yes --claude-md global --hooks --index --audit

预览模式（不写任何文件）

jcodemunch-mcp init --dry-run   # 预览会做什么
jcodemunch-mcp init --demo       # 完整演示流程

2. 手工配置（Claude Code）——一行命令

claude mcp add jcodemunch uvx jcodemunch-mcp
# 重启 Claude Code，用 /mcp 确认 jcodemunch 已连接

手工配置 JSON 格式（Claude Desktop 等）：

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

各 OS 配置路径：

OS	路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Linux	`~/.config/claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

3. 手工配置（OpenClaw）

openclaw mcp set jcodemunch '{"command":"uvx","args":["jcodemunch-mcp"]}'

或在 ~/.openclaw/openclaw.json 的 mcpServers 下添加：

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

然后 openclaw gateway restart 并用 openclaw mcp list 验证。

4. 让 Agent 真正使用它（这一步最容易被忽略）

安装好服务器不等于 Agent 会自动用它——Agent 默认用内置的 Read/Grep/Glob 工具。必须在 ~/.claude/CLAUDE.md（全局）或项目根目录的 CLAUDE.md 中写入提示策略：

## Code Exploration Policy
Always use jCodemunch-MCP tools — never fall back to Read, Grep, Glob, or Bash for code exploration.
- Before reading a file: use get_file_outline or get_file_content
- Before searching: use search_symbols or search_text
- Before exploring structure: use get_file_tree or get_repo_outline
- Call resolve_repo with the current directory first; if not indexed, call index_folder.

jcodemunch-mcp init --claude-md global 可以自动完成这一步。

5. 核心工具速查

工具	用途
`index_folder`	对当前目录建立 tree-sitter 索引
`get_file_outline`	列出文件的符号结构（函数/类/方法）
`get_file_content`	按符号精确获取代码（只读需要的部分）
`search_symbols`	按名称搜索符号
`search_text`	全文搜索
`get_file_tree`	获取目录树
`get_repo_outline`	仓库级结构概览
`find_references`	查找符号引用（支持 `format=compact` 压缩输出）

压缩格式：find_references(identifier="get_user", format="auto")，格式包括 auto（自动）、compact（强制）、json（关闭压缩），压缩后 median 减少 45.5% 字节，峰值 55.4%。

支持的语言

Python、TypeScript、TSX、JavaScript、Go、Rust、Java、PHP、Dart、C#、C、C++、Swift、Elixir、Ruby、Perl、Kotlin、Gleam、Bash、GDScript、Scala、Lua、Erlang、Fortran、Kotlin 等 20+ 语言。详见 LANGUAGE_SUPPORT.md。

环境变量

变量	作用
`GITHUB_TOKEN`	访问私有仓库 + 提高 GitHub API 限额
`ANTHROPIC_API_KEY`	启用 Claude 生成的摘要
`MINIMAX_API_KEY`	启用 MiniMax 摘要（默认模型 minimax-m2.7）
`GOOGLE_API_KEY`	启用 Gemini 摘要
`JCODEMUNCH_SUMMARIZER_PROVIDER`	强制指定摘要提供者：`anthropic` / `gemini` / `openai` / `minimax` / `glm` / `none`
`allow_remote_summarizer`	设为 `true` 允许向非 localhost 的 OpenAI-compatible 端点发送代码（默认 false）

典型适用场景

大型代码库探索：数十个文件、深度嵌套的项目，Agent 需要精准定位而非暴力扫描
Claude Code / Cursor 日常开发：配合 IDE 内 MCP，减少每次代码审查的 token 消耗
CI/CD 中的 AI 工具链：按 token 计费的 AI 编程工具在流水线中高频运行，省一分是一分
代码审计 / 安全分析：精确提取函数/类级别的代码片段，避免整文件读取泄露过多上下文
多语言混合项目：同一 MCP 服务器覆盖 TypeScript + Python + Go，无需切换工具

坑与注意

安装 ≠ 自动生效：Agent 默认不用 jCodeMunch，必须写 CLAUDE.md 提示策略（详见上文的「让 Agent 真正使用它」）。这是最常见的「装了但没效果」原因。
Windows + uvx 路径问题：uvx 在 Windows 环境需完整重启编辑器才能识别 PATH，Cursor / Claude Desktop 尤甚。
Python < 3.8 兼容：pip 安装需 Python 3.8+，低版本 Python 考虑 uvx 方式绕过。
匿名箭头函数不索引（JavaScript）：没有具名的箭头函数无法被 tree-sitter 提取symbol，Agent 搜索时注意。
私有仓库必须配 GITHUB_TOKEN：否则只能索引 public 仓库，且 API 速率受限。
压缩格式有阈值：format=auto 只在节省 >= 15% 时才输出压缩格式，否则回退 JSON；format=compact 强制压缩，需确认下游解析方支持。
索引是一次性开销：首次 index_folder 对大仓库有显著 CPU 消耗，但后续查询几乎零成本。

与同类对比

特性	jCodeMunch	MCP Filesystem 工具	Sourcegraph (Cody)
精度	符号级（tree-sitter AST）	文件级	符号级
token 节省	95%+	0%（全文件）	中等
索引方式	本地 tree-sitter	无需索引	云端索引
支持语言	20+	任意文件	10+
MCP 协议	✅ 原生	✅ 原生	需要 Gateway
成本	免费（含商业许可）	免费	付费

核心差异：jCodeMunch 是本地 tree-sitter 索引，精度高于文件系统工具；对比 Sourcegraph Cody 则无需云端依赖，完全离线可用。

一句话推荐结论

jCodeMunch 是每个高频使用 AI 编程工具的开发者必备的 MCP 服务器——安装一次、配置 CLAUDE.md 策略，之后每次代码探索自动节省 95%+ token，7 月最新基准已达 99.6% 平均压缩率，省下的都是真金白银。