Quickstart - https://github.com/jgravelle/jcodemunch-mcp/blob/main/QUICKSTART.md
Use it to make money, and Uncle J. gets a taste. Fair enough? details
Related MCP server: cctx-mcp
Doc | What it covers |
Zero-to-indexed in three steps | |
Full tool reference, workflows, and best practices | |
Agent hooks and prompt policies | |
JSONC config file reference, migration from env vars | |
Groq Remote MCP integration, deployment, gcm CLI | |
Internal design, storage model, and extension points | |
Supported languages and parsing details | |
dbt, Git, and custom context provider docs | |
Common issues and fixes |
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.
Task | Traditional approach | With jCodeMunch |
Find a function | Open and scan large files | Search symbol → fetch exact implementation |
Understand a module | Read broad file regions | Pull only relevant symbols and imports |
Explore repo structure | Traverse file after file | Query outlines, trees, and targeted bundles |
Index once. Query cheaply. Keep moving. Precision context beats brute-force context.
Artur Skowroński (VirtusLab) — "roughly 80% fewer tokens, or 5× more efficient — index once, query cheaply forever" · GitHub All-Stars #15
Julian Horsey (Geeky Gadgets) — "3,850 tokens reduced to just 700 — a 5.5× improvement" · JCodeMunch AI Token Saver
Sion Williams — "preserving tokens for tasks that actually require reasoning rather than retrieval" · March 2026 AI Workflow Update
Traci Lim (AWS · ASEAN AI Lead) — "structural queries that native tools can't answer: find_importers, get_blast_radius, get_class_hierarchy, find_dead_code" · 5 Repos That Save Token Usage in Claude Code
Eric Grill — "context is the scarce resource. Cut it by 90% and the whole stack gets cheaper and more reliable" · jCodemunch: Context Engine for AI Agents
Commercial licenses
jCodeMunch-MCP is free for non-commercial use.
Commercial use requires a paid license.
jCodeMunch-only licenses
Builder — $79 — 1 developer
Studio — $349 — up to 5 developers
Platform — $1,999 — org-wide internal deployment
Want both code and docs retrieval?
Stop paying your model to read the whole damn file.
jCodeMunch turns repo exploration into structured retrieval.
Instead of forcing an agent to open giant files, wade through imports, boilerplate, comments, helpers, and unrelated code, jCodeMunch lets it navigate by what the code is and retrieve only what matters.
That means:
95%+ lower code-reading token usage in many retrieval-heavy workflows
less irrelevant context polluting the prompt
faster repo exploration
more accurate code lookup
less repeated file-scanning nonsense
It indexes your codebase once using tree-sitter, stores structured symbol metadata plus byte offsets into the original source, and retrieves exact implementations on demand instead of re-reading entire files over and over.
Recent releases have made that retrieval workflow sharper and more useful in real engineering work, with BM25-based symbol search, fuzzy matching, semantic/hybrid search (opt-in, zero mandatory dependencies), query-driven token-budgeted context assembly (get_ranked_context), dead code detection (find_dead_code), untested symbol detection (get_untested_symbols), git-diff-to-symbol mapping (get_changed_symbols), architectural centrality ranking (get_symbol_importance, PageRank), blast-radius depth scoring with source snippets, context bundles with token budgets, AST-derived call graphs and call hierarchy traversal, decorator-aware search and filtering, hotspot detection (complexity x churn), dependency cycles and coupling metrics, session-aware routing (plan_turn, turn budgets, negative evidence), agent config auditing, complexity-based model routing (Agent Selector), enforcement hooks (PreToolUse/PostToolUse/PreCompact), dependency graphs, class hierarchy traversal, multi-symbol bundles, live watch-based reindexing, automatic Claude Code worktree discovery (watch-claude), auto-watch on demand (when watch: true in config, the server automatically indexes and watches any repo a tool is called against — ensuring fresh results from the first call), trusted-folder access controls, and edit-ready refactoring plans (plan_refactoring) for rename, move, extract, and signature change operations.
Measured with tiktoken cl100k_base across three public repos. Workflow: search_symbols (top 5) + get_symbol_source × 3 per query. Baseline: all source files concatenated (minimum cost for an agent that reads everything). Full methodology and harness →
Repository | Files | Symbols | Baseline tokens | jCodeMunch tokens | Reduction |
expressjs/express | 34 | 117 | 73,838 | ~1,300 avg | 98.4% |
fastapi/fastapi | 156 | 1,359 | 214,312 | ~15,600 avg | 92.7% |
gin-gonic/gin | 40 | 805 | 84,892 | ~1,730 avg | 98.0% |
Grand total (15 task-runs) | 1,865,210 | 92,515 | 95.0% |
Per-query results range from 79.7% (dense FastAPI router query) to 99.8% (sparse context-bind query on Express). The 95% figure is the aggregate. Run python benchmarks/harness/run_benchmark.py to reproduce.
Independent 50-iteration A/B test on a real Vue 3 + Firebase production codebase — JCodeMunch vs native tools (Grep/Glob/Read), Claude Sonnet 4.6, fresh session per iteration:
Metric | Native | JCodeMunch |
Success rate | 72% | 80% |
Timeout rate | 40% | 32% |
Mean cost/iteration | $0.783 | $0.738 |
Mean cache creation | 104,135 | 93,178 (−10.5%) |
Tool-layer savings isolated from fixed overhead: 15–25%. One finding category appeared exclusively in the JCodeMunch variant: orphaned file detection via find_importers — a structural query native tools cannot answer without scripting.
Full report: benchmarks/ab-test-naming-audit-2026-03-18.md
Most agents still inspect codebases like tourists trapped in an airport gift shop:
open entire files to find one function
re-read the same code repeatedly
consume imports, boilerplate, and unrelated helpers
burn context window on material they never needed in the first place
jCodeMunch fixes that by giving them a structured way to:
search symbols by name, kind, or language — with fuzzy matching and optional semantic/hybrid search
inspect file and repo outlines before pulling source
retrieve exact symbol implementations only
grab a token-budgeted context bundle or ranked context pack for a task
fall back to text search when structure alone is not enough
detect dead code, trace impact, rank by centrality, and map git diffs to symbols
plan the next turn with plan_turn — confidence-guided routing before the first read
track session state and avoid re-reading files the agent already explored
Agents do not need bigger and bigger context windows.
They need better aim.
Find and fetch functions, classes, methods, constants, and more without opening entire files.
Inspect repository structure and file outlines before asking for source.
Send the model the code it needs, not 1,500 lines of collateral damage.
find_importers tells you what imports a file. get_blast_radius tells you what breaks if you change a symbol, with depth-weighted risk scores and optional source snippets. get_class_hierarchy traverses inheritance chains. get_call_hierarchy traces callers and callees N levels deep using AST-derived call graphs, with optional LSP-enriched dispatch resolution for interface/trait method calls. find_dead_code finds symbols and files unreachable from any entry point. get_untested_symbols finds functions with no evidence of test-file reachability — the intersection of import-graph analysis and test-file detection. get_changed_symbols maps a git diff to the exact symbols that were added, modified, or removed. get_symbol_importance ranks your codebase by architectural centrality using PageRank on the import graph. get_hotspots surfaces the riskiest code by combining complexity with git churn. get_dependency_cycles detects circular imports. get_coupling_metrics measures module coupling and instability. These are not "faster grep" — they are questions grep cannot answer at all.
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."
Useful for onboarding, debugging, refactoring, impact analysis, and exploring unfamiliar repos without brute-force file reading.
plan_refactoring generates exact edit-ready instructions for rename, move, extract, and
signature change operations. Returns {old_text, new_text} blocks compatible with any editor's
find-and-replace, plus import rewrites, collision detection, new file generation, and multi-file coordination.
Indexes are stored locally for fast repeated access.
jCodeMunch indexes local folders or GitHub repos, parses source with tree-sitter, extracts symbols, and stores structured metadata alongside raw file content in a local index. Each symbol includes enough information to be found cheaply and retrieved precisely later.
That includes metadata like:
signature
kind
qualified name
one-line summary
byte offsets into the original file
So when the agent wants a symbol, jCodeMunch can fetch the exact source directly instead of loading and rescanning the full file.
Ubuntu 24.04+ / Debian 12+: System Python is externally managed (PEP 668). Use
pipx install jcodemunch-mcporuv tool install jcodemunch-mcpinstead of barepip install.
pip install jcodemunch-mcp
jcodemunch-mcp initinit 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.
For non-interactive CI or scripting:
jcodemunch-mcp init --yes --claude-md global --hooks --index --auditpip install jcodemunch-mcpWant 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 embeddingsWithout an extra, summaries fall back to signatures (which still works — you just get shorter descriptions). Run
jcodemunch-mcp config --checkto verify your provider is installed and working.
If you’re using Claude Code:
claude mcp add jcodemunch uvx jcodemunch-mcpIf you’re using Paperclip (the multi-agent orchestration platform), add a .mcp.json to your workspace root:
{
"mcpServers": {
"jcodemunch": {
"type": "stdio",
"command": "uvx",
"args": ["jcodemunch-mcp"]
},
"jdocmunch": {
"type": "stdio",
"command": "uvx",
"args": ["jdocmunch-mcp"]
}
}
}Paperclip’s Claude Code agents auto-detect .mcp.json at startup. Add both servers to give your agents symbol search + doc navigation without blowing the token budget.
This matters more than people think.
Installing jCodeMunch makes the tools available. It does not guarantee the agent will stop its bad habit of brute-reading files unless you instruct it to prefer symbol search, outlines, and targeted retrieval. The changelog specifically calls out improved onboarding around this because it is a real source of confusion for first-time users.
A simple instruction like this helps:
Use jcodemunch-mcp for code lookup whenever available. Prefer symbol search, outlines, and targeted retrieval over reading full files.Note:
jcodemunch-mcp inithandles steps 2 and 3 automatically. For a comprehensive guide on enforcing these rules through agent hooks and prompt policies, see AGENT_HOOKS.md.
Pre-built indexes for popular frameworks and libraries. Skip the initial indexing step — install a pack and start querying immediately.
# List available packs
jcodemunch-mcp install-pack --list
# Install a free pack
jcodemunch-mcp install-pack fastapi
# Install a licensed pack
jcodemunch-mcp install-pack express --license YOUR-KEYFree packs require no license. Licensed packs require a jCodeMunch license. Use --force to re-download an already-installed pack.
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 -dSee GROQ.md for the full tutorial: allowed-tools presets, model recommendations, deployment options, and validation scripts.
Get a structured PR review in under 5 seconds:
# .github/workflows/speedreview.yml
- uses: jgravelle/jcodemunch-mcp/speedreview@main
with:
groq_api_key: ${{ secrets.GROQ_API_KEY }}See speedreview/README.md for full setup and configuration.
Ask any question about any codebase. Get an answer in under 3 seconds.
pip install jcodemunch-mcp[groq]
export GROQ_API_KEY=gsk_...
# Ask about a GitHub repo (auto-indexes on first use)
gcm "how does authentication work?" --repo pallets/flask
# Ask about the current directory
gcm "where are the API routes defined?"
# Interactive chat mode
gcm --chat --repo facebook/react
# Use the fast 8B model
gcm "what does parse_file do?" --fastCombines jCodeMunch's token-efficient retrieval (BM25 + PageRank) with Groq's 280+ tok/s inference for near-instant answers. See gcm --help for all options.
Speak a question, hear the answer. Full audio loop: Whisper STT → retrieval → LLM → Orpheus TTS.
pip install jcodemunch-mcp[groq-voice]
# Voice conversation with a codebase
gcm --voice --repo pallets/flask
# Press Enter to start recording, Enter again to stop
# Or type a question directly as text fallbackPush-to-talk via Enter key. Caps answers to ~100 words for natural spoken delivery. Requires a microphone.
Generate a narrated explainer video for any codebase in a single command.
pip install jcodemunch-mcp[groq-explain]
# Generate a 60-second narrated explainer
gcm explain --repo pallets/flask -o flask-explainer.mp4
# With verbose timing
gcm explain --repo facebook/react -vPipeline: repo structure → LLM narration script → Orpheus TTS → Pillow slides → FFmpeg MP4. Requires FFmpeg on PATH.
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.
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.
Layer | Path | Purpose |
Global |
| Server-wide defaults |
Project |
| Per-project overrides |
Project config merges over global config — closest to the work wins.
Config key | What it controls | Typical savings |
|
| ~5-6k tokens (core) |
| Strip rarely-used advanced params from schemas | ~1-2k tokens |
| Remove individual tools from schema entirely | ~100–400 tokens/tool |
| Shrink language enum + gate features | ~2–86 tokens/turn |
| Filter | ~50–150 tokens/call |
| Control description verbosity | ~0–600 tokens/turn |
Recommended for context-conscious setups: "tool_profile": "core", "compact_schemas": true reduces the schema footprint from ~11.5k tokens to ~4k tokens.
See the full template for all available keys. Run jcodemunch-mcp config --init to generate one.
architecture.layers)Place a .jcodemunch.jsonc file at your project root to declare the layers your architecture must respect. get_layer_violations will then enforce that imports only flow in the declared direction.
// .jcodemunch.jsonc — example for a layered Python project
{
"architecture": {
"layers": [
{ "name": "api", "paths": ["src/routes", "src/controllers"] },
{ "name": "service", "paths": ["src/services"] },
{ "name": "repo", "paths": ["src/repositories"] },
{ "name": "db", "paths": ["src/models", "src/migrations"] }
],
"rules": [
{ "layer": "api", "may_not_import": ["db"] },
{ "layer": "service", "may_not_import": ["api"] },
{ "layer": "repo", "may_not_import": ["api", "service"] }
]
}
}Call get_layer_violations(rules=[...]) directly to pass rules inline — the config file is optional and used as a fallback. When no config is present, get_layer_violations infers layers from top-level directory structure.
The following env vars still work but are deprecated. Config file values take priority:
Variable | Config key | Default |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
A common question: does this only help during exploration, or also when the agent is prompted to read a file before editing?
It helps most when editing a specific function. The "read before edit" constraint doesn't require reading the whole file — it requires reading the code. get_symbol_source gives you exactly the function body you're about to touch, nothing else. Instead of reading 700 lines to edit one method, you read those 30 lines.
Scenario | Native tool | jCodemunch | Savings |
Edit one function (700-line file) |
|
| ~95% |
Understand a file's structure |
|
| ~80% |
Find which file to edit |
|
| comparable |
Edit requires whole-file context |
|
| ~0% |
"What breaks if I change X?" | not possible |
| unique capability |
The cases where it doesn't help: edits that genuinely require understanding the entire file (restructuring file-level state, reordering logic that spans hundreds of lines). For those, get_file_content is roughly equivalent to Read. The cases where it helps most are targeted edits — one function, one method, one class — which is the majority of real editing work.
large repositories
unfamiliar codebases
agent-driven code exploration
refactoring and impact analysis
teams trying to cut AI token costs without making agents dumber
developers who are tired of paying premium rates for glorified file scrolling
Start with QUICKSTART.md for the fastest setup path.
Then index a repo, ask your agent what it has indexed, and have it retrieve code by symbol instead of reading entire files. That is where the savings start.
Get all symbols (functions, classes, methods) in a file with signatures and summaries.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository identifier (owner/repo or just repo name) | |
| file_path | Yes | Path to the file within the repository (e.g., 'src/main.py') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions what information is returned (signatures and summaries), it doesn't address important behavioral aspects like whether this is a read-only operation, potential rate limits, authentication requirements, error conditions, or response format details. The description provides basic output information but misses critical operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-constructed sentence that efficiently conveys the core functionality without any wasted words. It's front-loaded with the main purpose and includes essential details about the output format. Every element earns its place in this concise formulation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no annotations and no output schema, the description provides basic purpose and output information but lacks sufficient operational context. It doesn't explain what format the symbols are returned in, how errors are handled, or any limitations of the tool. While concise, it leaves important gaps for a tool that presumably returns complex symbol data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already fully documents both parameters (repo and file_path). The description doesn't add any parameter-specific information beyond what's in the schema, such as format examples for repo beyond 'owner/repo' or edge cases for file_path. The baseline score of 3 reflects adequate but minimal value addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get all symbols'), resource ('in a file'), and scope ('with signatures and summaries'), distinguishing it from siblings like get_file_tree (file structure) or get_symbol (single symbol). It uses precise terminology that helps the agent understand exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for extracting symbol information from a specific file, but doesn't explicitly state when to use this vs. alternatives like get_symbol (single symbol) or search_symbols (search across files). No guidance on prerequisites or exclusions is provided, leaving usage context somewhat ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the file tree of an indexed repository, optionally filtered by path prefix.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository identifier (owner/repo or just repo name) | |
| path_prefix | No | Optional path prefix to filter (e.g., 'src/utils') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the repository must be 'indexed' (a key behavioral constraint) and describes optional filtering. However, it doesn't disclose important behavioral traits like whether this is a read-only operation, what format the file tree returns (e.g., hierarchical structure), potential rate limits, or error conditions (e.g., if repo isn't indexed). For a tool with no annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Get the file tree of an indexed repository') and adds qualifying information ('optionally filtered by path prefix'). Every word earns its place with zero waste, making it easy for an AI agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and filtering but lacks details on return format, error handling, and behavioral constraints. Without annotations or output schema, the agent must infer these from context, leaving room for misinterpretation. A score of 3 reflects this borderline completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('repo' and 'path_prefix') with clear descriptions. The description adds marginal value by reinforcing the optional filtering concept ('optionally filtered by path prefix') but doesn't provide additional semantic context beyond what's in the schema. With high schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'file tree of an indexed repository' with optional filtering. It distinguishes from siblings like 'get_file_outline' (which likely provides different structural information) and 'get_symbol' (which focuses on specific symbols rather than file structure). However, it doesn't explicitly differentiate from 'list_repos' which lists repositories rather than their file trees.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning 'indexed repository' (suggesting the repo must be indexed first) and 'optionally filtered by path prefix' (suggesting when filtering is appropriate). However, it doesn't provide explicit guidance on when to use this versus alternatives like 'get_file_outline' or 'search_symbols', nor does it specify prerequisites beyond the repository being indexed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full source code of a specific symbol. Use after identifying relevant symbols via get_file_outline or search_symbols.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository identifier (owner/repo or just repo name) | |
| symbol_id | Yes | Symbol ID from get_file_outline or search_symbols |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the tool retrieves 'full source code,' which implies a read-only operation, but doesn't disclose behavioral traits like error handling, performance limits, or response format. While it adds some context about usage timing, it lacks details on what happens if the symbol_id is invalid or if the repo is inaccessible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by usage guidance. Every sentence earns its place by providing essential information without waste, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 required parameters, no output schema, no annotations), the description is adequate but has gaps. It covers purpose and usage well, but without annotations or output schema, it lacks details on behavioral aspects like what the returned source code includes (e.g., formatting, metadata) or potential errors. It's minimally viable but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (repo and symbol_id) with descriptions. The description adds no additional meaning beyond implying symbol_id comes from specific sibling tools, but this is covered in usage guidelines rather than parameter semantics. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get the full source code') and resource ('a specific symbol'), distinguishing it from siblings like get_file_outline (which provides outlines) and search_symbols (which searches for symbols). It precisely defines the tool's function without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Use after identifying relevant symbols via get_file_outline or search_symbols'), providing clear guidance on prerequisites and distinguishing it from alternatives. This helps the agent understand the workflow and avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full source code of multiple symbols in one call. Efficient for loading related symbols.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository identifier (owner/repo or just repo name) | |
| symbol_ids | Yes | List of symbol IDs to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions efficiency ('Efficient for loading related symbols'), which is a useful trait, but lacks critical details: it doesn't specify if this is a read-only operation, potential rate limits, error handling (e.g., for invalid symbol IDs), or what happens if some symbols aren't found. For a tool with 2 required parameters and no annotations, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, and the second adds efficiency context. Both sentences earn their place with no wasted words, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 required parameters, no output schema, no annotations), the description is minimally complete. It covers the purpose and efficiency but lacks details on behavior, error handling, or output format. Without annotations or output schema, more context would be helpful, but it's not entirely inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for both parameters ('repo' and 'symbol_ids'). The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline is 3, as the description doesn't compensate but also doesn't detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get full source code of multiple symbols in one call.' It specifies the verb ('Get'), resource ('full source code of multiple symbols'), and scope ('in one call'). However, it doesn't explicitly differentiate from sibling tools like 'get_symbol' (singular) or 'search_symbols', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance: 'Efficient for loading related symbols' suggests this tool is optimal for batch retrieval when symbols are related. It doesn't explicitly state when to use this vs. alternatives like 'get_symbol' (for single symbols) or 'search_symbols' (for finding symbols), nor does it mention exclusions, so it falls short of a 4 or 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index a GitHub repository's source code. Fetches files, parses ASTs, extracts symbols, and saves to local storage.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | GitHub repository URL or owner/repo string | |
| use_ai_summaries | No | Use AI to generate symbol summaries (requires ANTHROPIC_API_KEY). When false, uses docstrings or signature fallback. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the multi-step process (fetching, parsing, extracting, saving) and mentions local storage persistence, which adds useful context. However, it lacks details on permissions, rate limits, error handling, or what happens if the repository is already indexed, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the tool's purpose and key steps without unnecessary details. It is front-loaded with the main action ('Index a GitHub repository's source code') and every clause adds value, making it highly concise and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (indexing with AI options) and lack of annotations or output schema, the description is moderately complete. It outlines the process and storage outcome but omits details on performance, side effects, or return values. For a mutation tool with no output schema, more behavioral context would improve completeness, but it meets minimum viability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description does not add specific parameter semantics beyond what the schema provides, but since there are only 2 parameters and the schema is comprehensive, a baseline of 3 is appropriate. The description's mention of AI summarization aligns with the use_ai_summaries parameter, slightly enhancing understanding, warranting a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('index', 'fetches', 'parses', 'extracts', 'saves') and resources ('GitHub repository's source code', 'files', 'ASTs', 'symbols', 'local storage'). It distinguishes from siblings like get_file_outline or search_symbols by emphasizing the comprehensive indexing process rather than retrieval or search operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for initial indexing of a repository, but does not explicitly state when to use this tool versus alternatives like list_repos or get_file_tree. It mentions AI summarization as an option, which provides some context, but lacks clear guidance on prerequisites or exclusions compared to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all indexed repositories.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only operation by using 'List', but doesn't specify details such as pagination, rate limits, authentication needs, or what 'indexed' entails (e.g., recently updated vs. all-time). This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It is front-loaded and appropriately sized for a simple tool with no parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate but lacks depth. It doesn't explain what 'indexed' means, the format of the returned list, or how this differs from sibling tools. For a list operation, more context on scope and output would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter details, but it could have mentioned implicit constraints (e.g., no filtering options). A baseline of 4 is appropriate as it avoids redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('indexed repositories') with the scope 'all', making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'get_file_tree' or 'search_symbols', which might also involve repository listings, so it misses the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_file_tree' or 'search_symbols', nor does it mention any prerequisites or context for usage. It simply states what the tool does without indicating appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for symbols matching a query across the entire indexed repository. Returns matches with signatures and summaries.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository identifier (owner/repo or just repo name) | |
| query | Yes | Search query (matches symbol names, signatures, summaries, docstrings) | |
| kind | No | Optional filter by symbol kind | |
| file_pattern | No | Optional glob pattern to filter files (e.g., 'src/**/*.py') | |
| max_results | No | Maximum number of results to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the search scope ('across the entire indexed repository') and return content ('matches with signatures and summaries'), but lacks details on permissions, rate limits, pagination, or error handling. For a search tool with no annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, consisting of two clear sentences that efficiently convey the core functionality and return value. There is no wasted language, and every sentence earns its place by adding essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and return content, but lacks usage guidelines, behavioral details, and output specifics. Without annotations or an output schema, more context on behavior and results would be beneficial for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by implying the query matches 'symbol names, signatures, summaries, docstrings' (which is covered in the schema's query description) and mentioning 'returns matches,' but does not provide additional syntax or format details. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for symbols matching a query across the entire indexed repository.' It specifies the verb ('Search'), resource ('symbols'), and scope ('across the entire indexed repository'), but does not explicitly differentiate it from sibling tools like 'get_symbol' or 'get_symbols', which appear related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions returning 'matches with signatures and summaries,' but does not indicate when this search is preferred over sibling tools such as 'get_symbol' (likely for a specific symbol) or 'get_symbols' (possibly for all symbols). No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_file_outlineget_file_treeget_symbolget_symbolsindex_repolist_repossearch_symbolsMost tools have distinct purposes, but get_symbol and get_symbols could be confused as they both retrieve symbol source code, differing only in single vs. multiple symbols. The descriptions clarify this, but the naming similarity creates minor ambiguity. Other tools like get_file_outline, get_file_tree, and search_symbols are clearly differentiated.
All tool names follow a consistent verb_noun pattern with snake_case, such as get_file_outline, index_repo, and search_symbols. There are no deviations in naming conventions, making the set predictable and easy to parse for agents.
With 7 tools, the count is well-scoped for the server's purpose of indexing and querying GitHub repository code. Each tool serves a specific function in the workflow, from indexing and listing repos to retrieving file structures and symbols, without unnecessary redundancy.
The toolset covers core workflows for code indexing and symbol retrieval, including repository management, file exploration, and symbol search. A minor gap exists in update or delete operations for indexed repos, but agents can work around this, and the surface is largely complete for the stated domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that gives your AI access to the source code and docs of all public github repos
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jgravelle/jcodemunch-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
