jcodemunch-mcp MCP工具

Option B: Manual setup

1. Install it

pip install jcodemunch-mcp

Want semantic search? Install the local embedding extra for zero-config semantic search — no API keys, no internet after first download:

> pip install "jcodemunch-mcp[local-embed]"  # bundled ONNX encoder (recommended)
> jcodemunch-mcp download-model              # fetch model (~23 MB, one-time)
> 

Want AI-generated summaries? Install the extra for your provider:

> pip install "jcodemunch-mcp[anthropic]"   # Claude
> pip install "jcodemunch-mcp[gemini]"      # Gemini
> pip install "jcodemunch-mcp[openai]"      # OpenAI-compatible
> pip install "jcodemunch-mcp[all]"         # all providers + local embeddings
> 

Without an extra, summaries fall back to signatures (which still works — you just get shorter descriptions). Run jcodemunch-mcp config --check to verify your provider is installed and working.

<details> <summary><strong>Extras matrix — system surfaces each extra pulls in</strong></summary>

Most extras are pure-Python and self-contained. A few pull libraries that touch system surfaces worth noting for managed-endpoint and SOC 2 / HIPAA-adjacent deployments. For the base package alone, none of these surfaces are introduced.

For managed-endpoint deployments where microphone access on developer machines is policy-restricted (HIPAA, SOC 2, finance), pin to the base package or to the specific provider extras you need. The voice and explain paths are opt-in features, not part of the core MCP server functionality, and [all] is the only extra that bundles them together.

</details>

2. Add it to your MCP client

If you’re using Claude Code, pick whichever matches what you installed in step 1.

Pip install (simplest, what most people do):

claude mcp add -s user jcodemunch jcodemunch-mcp

The -s user flag registers it at user scope so it's available in every project. Without it, the registration is project-local and you'll see it missing the next time you cd elsewhere. If jcodemunch-mcp isn't found on PATH (common on Windows where pip install --user installs to AppData\Roaming\Python\PythonXYZ\Scripts\), use the absolute path:

```bash

Install a free pack

jcodemunch-mcp install-pack fastapi

Install a licensed pack

jcodemunch-mcp install-pack express --license YOUR-KEY ```

Free packs require no license. Licensed packs require a jCodeMunch license. Use --force to re-download an already-installed pack.

---

Quick setup

jcodemunch-mcp config --init       # create ~/.code-index/config.jsonc from template
jcodemunch-mcp config              # show effective configuration
jcodemunch-mcp config --check      # validate config + verify prerequisites

--check validates that your config file is well-formed, your AI provider package is installed, your index storage path is writable, and HTTP transport packages are present. Exits non-zero on any failure — useful for CI/CD or first-run scripts.

Cut code-reading token usage by **95% or more** with precise symbol retrieval

Most AI agents explore repositories the expensive way:

open entire files → skim thousands of irrelevant lines → repeat.

That is not “a little inefficient.” That is a token incinerator.

jCodeMunch indexes a codebase once and lets agents retrieve only the exact code they need: functions, classes, methods, constants, outlines, and tightly scoped context bundles, with byte-level precision.

In retrieval-heavy workflows, that routinely cuts code-reading token usage by 95%+ because the agent stops brute-reading giant files just to find one useful implementation.

Index once. Query cheaply. Keep moving. Precision context beats brute-force context.

---

Agent config hygiene

audit_agent_config scans your CLAUDE.md, .cursorrules, copilot-instructions.md, and other agent config files for token waste: per-file token cost, stale symbol references (cross-referenced against the index — catches renamed or deleted functions), dead file paths, redundancy between global and project configs, bloat, and scope leaks. No other tool can tell you "line 15 references a function that was renamed three weeks ago."

Option A: One command (recommended)

pip install jcodemunch-mcp
jcodemunch-mcp init

init auto-detects your MCP clients (Claude Code, Claude Desktop, Cursor, Windsurf, Continue), writes their config entries, installs the CLAUDE.md prompt policy so your agent actually uses jCodeMunch, optionally installs enforcement hooks (PreToolUse read guard + PostToolUse auto-reindex + PreCompact session snapshot), optionally indexes your project, and audits your agent config files for token waste. Run jcodemunch-mcp init --help for all flags.

Prefer a one-line CLAUDE.md? From v1.71.0 the server exposes a jcodemunch_guide tool that returns the same policy snippet `claude-md --generate` prints — with the running version embedded. Keep this single line in your CLAUDE.md / AGENT.md and the guide always matches the installed server:

> Call the jcodemunch_guide tool and strictly follow its instructions.
> 

The tool is force-included, so it can't be hidden by disabled_tools or tier filtering.

For non-interactive CI or scripting:

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

Configuration

Settings are controlled by a JSONC config file (config.jsonc) with env var fallbacks for backward compatibility. Defaults are chosen so that a fresh install works without any configuration.

Config file locations

Project config merges over global config — closest to the work wins.

Deprecated env vars (v2.0 will remove)

The following env vars still work but are deprecated. Config file values take priority:

AI provider keys (ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_BASE, MINIMAX_API_KEY, ZHIPUAI_API_KEY, etc.), JCODEMUNCH_SUMMARIZER_PROVIDER, and CODE_INDEX_PATH are always read from env vars — they are never placed in config files.

AI provider priority in auto-detect mode: Anthropic → Gemini → OpenAI-compatible (OPENAI_API_BASE) → MiniMax → GLM-5 → signature fallback. Set JCODEMUNCH_SUMMARIZER_PROVIDER to force anthropic, gemini, openai, minimax, glm, or none. jcodemunch-mcp config shows which provider is active.

allow_remote_summarizer only affects OpenAI-compatible HTTP endpoints. When false, jcodemunch accepts only localhost-style endpoints such as Ollama or LM Studio on 127.0.0.1 and rejects remote hosts like api.minimax.io. When a remote endpoint is rejected, AI summarization falls back to docstrings or signatures instead of sending source code to that provider. Set allow_remote_summarizer: true in config.jsonc if you intentionally want to use a hosted OpenAI-compatible provider such as MiniMax or GLM-5.

openai_extra_body (config key, or JCODEMUNCH_OPENAI_EXTRA_BODY env var as a JSON object) is merged into every OpenAI-compatible /chat/completions and /responses summarizer request. Use it for provider knobs the standard payload doesn't expose — most commonly to turn off a local thinking model's reasoning so the output budget isn't spent on reasoning tokens (which silently degrades summaries to generic signatures). For llama.cpp / Qwen: JCODEMUNCH_OPENAI_EXTRA_BODY='{"chat_template_kwargs":{"enable_thinking":false}}'. When a summarization run produces mostly generic fallbacks despite successful responses, jcodemunch now logs a degradation warning pointing at this setting (issue #323).

---

~/.codex/config.toml

[mcp_servers.jcodemunch] command = "/absolute/path/to/.venv/bin/jcodemunch-mcp"

~/.hermes/config.yaml

mcp_servers: jcodemunch: command: "uvx" args: ["jcodemunch-mcp"]

</details>

<details>
<summary>Odysseus config (self-hosted AI workspace)</summary>

[Odysseus](https://github.com/pewdiepie-archdaemon/odysseus) runs in Docker and
indexes nothing itself; jCodeMunch indexes your code on the **host**. Run
jCodeMunch as an **SSE** server on the host and register its URL in Odysseus.
Its SSE client connects by URL only (no auth header), so leave the token unset
and secure the endpoint by network binding instead.

**1. Start jCodeMunch on the host (no token):**

Leave JCODEMUNCH_HTTP_TOKEN unset — Odysseus's SSE client sends no Authorization header, so a token returns 401 on connect.

2. In Odysseus → Settings → MCP Registry → Add server:

- Transport: SSE - URL: http://host.docker.internal:8848/sse (Linux: add extra_hosts: ["host.docker.internal:host-gateway"] to the Odysseus service in docker-compose.yml)

3. Secure by network, not token. Because the SSE path is unauthenticated, bind jCodeMunch so only the Odysseus container can reach it (host-gateway interface / firewall), not a public interface. JCODEMUNCH_RATE_LIMIT adds a throttle.

4. Restart Odysseus. All jCodeMunch tools appear in chat + agents. Keep the index fresh with jcodemunch-mcp watch .; use Odysseus's per-server disabled_tools to trim the surface.

jCodeMunch is read-only by charter, and its get_* / search_* / find_* / check_* tool naming satisfies Odysseus's plan-mode read-only gate, so the suite stays usable in plan mode.

Community-tested: the MCP protocol round-trip (SSE connect + tool discovery) is verified; the container-to-host network dial depends on your Docker setup.

</details>

Better engineering workflows

Useful for onboarding, debugging, refactoring, impact analysis, and exploring unfamiliar repos without brute-force file reading.

Groq Integration

Use jCodeMunch as a remote MCP tool with Groq's ultra-fast inference — answer codebase questions in seconds with zero local setup.

from openai import OpenAI

client = OpenAI(api_key="YOUR_GROQ_KEY", base_url="https://api.groq.com/openai/v1")

response = client.responses.create(
    model="llama-3.3-70b-versatile",
    input="What does parse_file do in jgravelle/jcodemunch-mcp?",
    tools=[{
        "type": "mcp",
        "server_label": "jcodemunch",
        "server_url": "https://YOUR_JCODEMUNCH_URL",
        "headers": {"Authorization": "Bearer YOUR_TOKEN"},
        "server_description": "Code intelligence via tree-sitter AST parsing.",
        "require_approval": "never",
    }],
)

Groq handles MCP tool discovery and execution server-side — one API call, no orchestration needed.

Self-host with Docker + Caddy for auto-TLS:

DOMAIN=mcp.example.com JCODEMUNCH_HTTP_TOKEN=secret docker compose up -d

See GROQ.md for the full tutorial: allowed-tools presets, model recommendations, deployment options, and validation scripts.

.github/workflows/speedreview.yml

- uses: jgravelle/jcodemunch-mcp/speedreview@v1.108.52 with: groq_api_key: ${{ secrets.GROQ_API_KEY }} ```

For stricter supply-chain hygiene, pin to the tag's commit SHA instead of the tag itself (git ls-remote https://github.com/jgravelle/jcodemunch-mcp refs/tags/v1.108.52). The action installs pinned package versions by default and exposes jcodemunch_version / openai_version inputs for override.

See speedreview/README.md for full setup and configuration.

gcm — Codebase Q&A CLI

Ask any question about any codebase. Get an answer in under 3 seconds.

```bash pip install jcodemunch-mcp[groq] export GROQ_API_KEY=gsk_...

Or type a question directly as text fallback

```

Push-to-talk via Enter key. Caps answers to ~100 words for natural spoken delivery. Requires a microphone.

FAQ

How much can I save on Claude / Opus tokens? In retrieval-heavy workflows, code-reading tokens typically drop 95%+ because the agent fetches exact symbols instead of brute-reading whole files — benchmarked at a 95% average reduction across 15 tasks / 3 repositories, with peaks of 99.8% on large repos. Compact MUNCH encoding then trims another ~45% off the wire. Full methodology and harness: TOKEN_SAVINGS.md and benchmarks/.

Does it work with large monorepos? Yes. It indexes incrementally, detects workspace members (pnpm / yarn / npm / Turborepo / Cargo / Go workspaces), and scopes queries to subpaths, so retrieval stays cheap as the repo grows. A file watcher keeps the index fresh.

What languages are supported? 70+ languages, including Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, C#, PHP, Ruby, Swift, and Kotlin via tree-sitter AST parsing. Full matrix: LANGUAGE_SUPPORT.md.

Which agents and IDEs does it work with? Any MCP client — Claude Code, Cursor, VS Code, Codex CLI, Continue, Windsurf, and more. One-click and CLI installs are at the top of this README and in the Works With section.

Is it free for personal use? Yes — free for personal use; commercial use needs a license. See Commercial Licenses. The guarantee: if jCodeMunch doesn't pay for itself, you don't pay for it.

How is this different from RAG or grep-based tools? jCodeMunch retrieves at the symbol level with byte-level precision — functions, classes, importers, blast radius, cla