DOCSEARCHbyAlgolia
Submit Docs

jCodeMunch MCP

repository·main·Indexed 22 days ago

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

A token-efficient MCP server for source code exploration using tree-sitter AST parsing. It provides AI agents with precise, symbol-level code retrieval to reduce token consumption compared to file-based exploration. Features include an MCP interface for AI agents, a CLI for scripts and CI, a TypeScript decoder, and HTTP live-ingest endpoints for OTel spans, SQL logs, and application stack traces.

Tokens
81K
Snippets
143
Records
408
Agent score
84%

What's inside jcodemunch-mcp

  1. Overview of jCodeMunch-MCP

    main

    jCodeMunch-MCP is a local-first structured retrieval layer designed for AI agents and MCP-compatible clients. It pre-indexes repository source code using tree-sitter AST parsing to build a structured catalog of symbols (functions, classes, methods, constants, and types).

    Instead of repeatedly loading large files into model context, the system allows for:

    1. Indexing: Processing a repository or local folder into a symbol index.
    2. Inspection: Navigating repository structure via outlines or trees.
    3. Search: Finding relevant symbols or text.
    4. Targeted Retrieval: Fetching precise source segments using byte-offset access to minimize token usage.
    5. Analysis: Verifying index freshness or computing relationships and impact.

  2. Understand jCodeMunch token efficiency benchmarks

    main

    jCodeMunch is designed to significantly reduce the number of tokens an AI agent must consume when reading code. Instead of concatenating all source files (the baseline), jCodeMunch uses a workflow of search_symbols (retrieving the top 5 results) followed by get_symbol (fetching specific symbol details) to provide precise context.

    Benchmark Methodology

    • Tokenizer: cl100k_base (tiktoken)
    • Workflow: search_symbols (top 5) + get_symbol x 3
    • Baseline: All indexed source files concatenated.

    Performance Summary

    Across tested repositories (expressjs/express, fastapi/fastapi, and gin-gonic/gin), jCodeMunch achieved an average token reduction of 99.6%, providing a 225.5x efficiency ratio compared to the baseline.

  3. License and Commercial Usage

    main

    jCodeMunch MCP is free for non-commercial use.

    Commercial use requires a paid license.

    Available license tiers include:

    • Builder: $79 (1 developer)
    • Studio: $349 (up to 5 developers)
    • Platform: $1,999 (org-wide internal deployment)

    Full jMunch suites (including code, docs, and data) are also available as bundles (Builder, Studio, and Platform).

  4. Review Performance and Operational characteristics

    main

    jCodeMunch is designed for high-performance, local-first code intelligence:

    • Local-first persistence: Indexes and raw file caches are stored locally to avoid redundant remote fetches and speed up repeat searches.
    • Sidecars and metadata shortcuts: Uses metadata sidecars to allow repo-listing operations without loading full index payloads.
    • Cache behavior: Employs LRU-like caching and mtime invalidation to minimize disk I/O and parsing costs.
    • File locking: Implements cross-process locking to prevent index corruption during concurrent access.
    • Memory hash cache: Uses a memory hash cache to avoid loading the full SQLite index on every debounce tick, saving approximately 57ms per operation.

  5. Understand the Evidence Arc development phases

    main

    The project follows an 'evidence arc' design to ensure the tool answers confidently and avoids the 'expensive failure' of treating missing files and non-existent files as identical.

    Current Roadmap Status:

    • Phase 1 (Claim-scoped evidence): Shipped. Uses claims and evidence_refs per claim.
    • Phase 2 (Exact immutable evidence receipts): P1/P2 Shipped. P3 (expiry taxonomy and session identity) is in progress.
    • Phase 3 (Absence evidence + subject state): Shipped.
    • Phase 4 (Requirement matching): Planned. Focuses on reporting coverage against declared requirements using the five-state vocabulary.
    • Phase 5 (Corpus and source-universe identity): Planned. Focuses on identifying the 'universe' (the scope of inputs and producer capabilities) a receipt is complete with respect to.
    • Phase 6 (Path-first program understanding): Planned. Focuses on understanding programs via typed flow witnesses.

  6. System Overview of jCodeMunch-MCP

    main

    jCodeMunch-MCP is a local-first structured code retrieval system designed for AI agents. Instead of forcing agents to read entire files linearly, it indexes source code once using tree-sitter to extract symbols (functions, classes, methods, etc.).

    Key capabilities include:

    • Symbol-based exploration: Navigate repositories via outlines and structures.
    • Precise retrieval: Access specific code spans using byte offsets to minimize token usage.
    • Local-first architecture: Indexes and raw-file caches are stored locally (defaulting to ~/.code-index/) for speed and privacy.
    • Structured context: Provides context bundles and relationship metadata (like import graphs) rather than brute-force file reading.

  7. Understand the jCodeMunch-MCP Dual-Use License

    main

    jCodeMunch-MCP is released under the jCodeMunch-MCP Dual-Use License.

    • Non-commercial use: Free.
    • Commercial use: Requires a paid license.

    Usage Conditions:

    1. You must retain the copyright notice and permission notice in all copies or substantial portions of the software.
    2. Any modifications must clearly indicate they are derived from the original work, and the original author's name (J. Gravelle) must remain intact.
    3. Redistributions in source code form must include a prominent notice describing any modifications made to the original version.

    Restrictions:

    • The software may not be renamed, rebranded, or published to any public package registry.
    • The software is provided "AS IS" without warranty of any kind.

  8. How jCodeMunch achieves token savings

    main

    jCodeMunch reduces token consumption through two independent mechanisms:

    1. Retrieval Savings: Instead of reading entire files, agents use symbol-based retrieval to fetch only the exact code needed (e.g., a specific function or class). This typically results in 95%+ savings on code-reading tasks.
    2. Encoding Savings (MUNCH): Responses sent to the agent use a compact wire format instead of verbose JSON. This acts as a multiplier on the remaining traffic.

    These two axes compose: every byte saved via encoding reduces the number of tokens the agent must process.

  9. Understanding the jCodeMunch vs. Odysseus rag_server benchmark

    main

    This benchmark compares the token efficiency and retrieval quality of the jCodeMunch retrieval layer against the built-in Odysseus rag_server.

    Key Comparison Metrics:

    • Tokens/Query: The number of tokens injected into the model's context. While a lower token count might seem better, it can be a 'trap' if the fragments are incomplete.
    • Complete/5: How many of the top 5 retrieved chunks are complete symbols (e.g., a whole function or class).
    • Split/5: How many of the top 5 retrieved chunks are split/truncated fragments.
    • Terms-hit/5: How many of the top 5 chunks contain the search terms.

    Core Difference in Retrieval Strategy:

    • Odysseus rag_server: Uses fixed ~1000-character fragments. This often results in lower token counts but frequently cuts symbols mid-definition (high Split/5 count), which reduces reasoning quality.
    • jCodeMunch: Returns complete symbols by construction. This ensures the model receives the full context of a symbol, even if the token count per query is higher than a truncated fragment.

  10. Compare jCodeMunch vs. RAG performance

    main

    jCodeMunch is designed to be more token-efficient and faster than traditional RAG (Retrieval-Augmented Generation) approaches for code retrieval.

    Key Advantages of jCodeMunch:

    • Token Efficiency: jCodeMunch typically uses significantly fewer tokens per query. For example, in the fastapi repository, jCodeMunch averaged 1,834 tokens/query compared to RAG-512's 2,850 tokens/query.
    • Chunk Integrity: Unlike RAG, which uses fixed-size chunks that often split mid-function (e.g., 53% split rate in fastapi for RAG-512), jCodeMunch uses AST-based retrieval via get_symbol_source. This ensures every result is a complete AST node (a full function, class, or method) with balanced braces.
    • Lower Infrastructure Overhead: jCodeMunch avoids heavy embedding models and large runtime dependencies (like torch or FAISS). It uses tree-sitter for indexing and an in-process BM25 search, resulting in faster index builds and lower query latency (<5ms).
    • Scalability: jCodeMunch maintains its efficiency even in large repositories (e.g., 951 files in fastapi), whereas RAG's embedding step becomes a dominant cost in terms of CPU time and index size.

  11. Configure the jCodeMunch Edit Guard

    main

    The Edit Guard (jcodemunch_edit_guard.ps1) is a PreToolUse hook that intercepts Edit, Write, and MultiEdit calls. It acts as a nudge to ensure the agent has sufficient context before modifying source code.

    Modes of Operation:

    • Soft Gate (Default): Prints a warning to stderr suggesting jCodeMunch tools (like get_symbol_source or get_blast_radius) but exits with 0, allowing the edit to proceed.
    • Hard Block: If the environment variable JCODEMUNCH_HARD_BLOCK=1 is set, the hook exits with code 2, preventing the edit until the agent uses jCodeMunch tools.

    Suppression: To bypass the warning in soft-gate mode, set the environment variable JCODEMUNCH_ALLOW_RAW_WRITE=1.

  12. Distinguish between benchmark token counting and runtime `_meta.tokens_saved`

    main

    It is important to distinguish how tokens are counted in benchmarks versus how they are reported at runtime:

    FeatureBenchmark CountingRuntime _meta.tokens_saved
    MethodUses tiktoken (cl100k_base)Uses byte approximation (raw_bytes / 4)
    AccuracyHigh (deterministic/reproducible)Fast (zero-dependency), ~20% variance
    ContextCounts serialized JSON response stringsBased on raw bytes

    When using the runtime field, the _meta envelope includes "estimate_method": "byte_approx" to indicate the approximation method used.