jcodemunch-mcp is a Model Context Protocol (MCP) server that intelligently indexes, parses, and serves code context to AI agents. Rather than feeding an entire repository's raw source to an LLM — which can consume tens of thousands of tokens — jcodemunch builds a structured symbol index and serves only the relevant slices of code in response to semantic queries. The system is organized around a pipeline that flows from source parsing through symbol storage to tool-based retrieval, all orchestrated through the MCP protocol and a companion CLI.
The src/jcodemunch_mcp package is the heart of the project and is decomposed into several clear sub-modules. The parser sub-package handles all source code analysis: it uses tree-sitter grammars (configured via LanguageSpec) to extract Symbol objects from source files, builds hierarchical SymbolNode trees, and optionally preprocesses SQL/Jinja templates through DbtDirective extraction. A dedicated context layer (ContextProvider, FileContext, DbtContextProvider, GitBlameProvider) enriches each file with ecosystem-specific metadata — dbt model schemas, git blame information — so that AI summaries can incorporate business context rather than just raw syntax. The storage layer, centered on IndexStore and _State (the token tracker), persists the parsed index to disk and tracks token consumption across operations. Finally, the tools layer (search_symbols, get_symbol) exposes MCP-compatible tool endpoints that query the index and return focused, token-efficient results.
A typical request flows through three stages. First, a repository is parsed: source files are read, tree-sitter extracts symbols with their signatures and byte ranges, context providers optionally attach metadata, and everything is persisted into an IndexStore. Second, when a query arrives (either via the MCP protocol or the CLI), the search_symbols tool performs a semantic search over the symbol index, returning up to SEARCH_MAX_RESULTS matches. Third, the caller can drill into any match with get_symbol, which retrieves the full definition, imports, and surrounding context for that specific symbol. This two-step search-then-fetch pattern is what enables dramatic token reduction compared to dumping entire files — the benchmark harness quantifies this by comparing measure_baseline (all raw tokens) against measure_jmunch (only searched + fetched tokens).
The project provides multiple entry points for different use cases. The cli/cli.py module exposes a command-line interface through which users can invoke tools directly — its out() helper standardizes result formatting for terminal output. The hook_event.py module integrates with Claude Code's hook system: when a worktree is created or destroyed, handle_hook_event() reads a JSON payload from stdin and appends it to a JSONL manifest at ~/.claude/jcodemunch-worktrees.jsonl, while read_manifest() reconstitutes the set of active worktrees from that log. This allows jcodemunch to automatically track which repositories are currently active in a developer's workspace.
The benchmarks/ directory contains a self-contained harness (run_benchmark.py) that evaluates jcodemunch's token efficiency against real-world repositories. It loads a task corpus from tasks.json, parses each repository into an index, and then measures both the baseline token count (all source files) and the jcodemunch token count (search + fetch for each query). The harness uses the cl100k_base tokenizer for consistent counting and produces a formatted markdown report via render_markdown(). This infrastructure ensures that changes to the parser, index, or search logic can be evaluated against concrete efficiency metrics before release.
The codebase follows a clear separation of concerns: parsing is decoupled from storage, which is decoupled from tool exposure. The ContextProvider ABC pattern makes it straightforward to plug in new ecosystem integrations beyond dbt and git blame. The symbol model (Symbol, SymbolNode) is language-agnostic — LanguageSpec encapsulates all language-specific tree-sitter queries — so adding support for new languages requires only a new spec, not changes to the core pipeline. This extensible, layered architecture makes jcodemunch-mcp a robust foundation for token-efficient code intelligence.