RepoContext's MCP server gives AI coding agents token-efficient, AST-aware access to a codebase for cheaper, more relevant context.
get_codebase_map — Generate a compressed AST symbol outline map (classes, functions, interfaces) of a repository, optionally from a specified rootDir.
extract_relevant_context — Given a task query (e.g. "Fix JWT auth token expiry"), rank and package only the most relevant files, pruning the rest; supports a maxTokens budget (default 40,000).
read_file_outline — Read a single file's semantic AST skeleton (signatures + docstrings, implementations omitted) by filePath.
Underlying benefits: ~70–85% token reduction, task-focused pruning, automated secret redaction, and compatibility with Claude Desktop, Cursor, Windsurf, and Antigravity.
The Next-Generation AST Codebase Map, Token Compression, and Context Packaging Engine for AI Coding Agents and IDEs.
When feeding codebases into modern AI coding assistants (Claude Code, Cursor, Windsurf, OpenAI Codex, Antigravity, Cline), developers face three critical bottlenecks:
💥 Token Explosion & High API Costs: Raw code dumps quickly exceed context limits or cost tens of dollars per query.
📉 Low Signal-to-Noise Ratio: 80% of lines are routine implementation details. LLMs only need the semantic API surface (signatures, types, interfaces, docstrings).
🔓 Security Leaks: Accidental exposure of .env credentials, API keys, and database URIs in prompts.
RepoContext solves all three with intelligent AST outline pruning, task-focused semantic file ranking, automated credential redaction, and native Model Context Protocol (MCP) integration.
Related MCP server: AtlasMemory
⚡ AST Codebase Map & Skeletonizer: Compresses source files by 70%~85% while retaining 100% of interfaces, types, functions, and JSDoc/docstrings.
🎯 Task-Oriented Relevance Pruning: Pass your prompt query (e.g. repocontext pack -q "Fix JWT auth token expiry") to automatically rank and pack only the most critical files.
🛡️ Automated Secret Scanner & Redaction: Built-in entropy and regex scanner detects and masks OpenAI keys, GitHub tokens, AWS keys, JWTs, and database URIs.
🔌 Native Model Context Protocol (MCP) Server: Directly integrates with Claude Desktop, Cursor, Windsurf, and Antigravity via standard MCP tools.
📑 Multi-Format Export: Generates clean Markdown with directory trees, Claude-optimized XML (<documents>), or structured JSON.
📊 Multi-Model Token & Cost Analytics: Real-time token counter with cost estimates for GPT-4o, GPT-5, Claude 3.5 Sonnet, and Gemini 1.5 Pro.
npx# Pack entire repository into an optimized Markdown prompt
npx repocontext pack
# Pack only files relevant to a specific task prompt
npx repocontext pack -q "Implement Stripe payment webhook handler" -o prompt.md
# Generate lightweight AST skeleton map (75%+ token reduction)
npx repocontext map -o codebase-map.mdnpm install -g repocontext# 1. Pack with direct clipboard copy (ready to paste into ChatGPT/Claude)
repocontext pack -c
# 2. Pack relevant files only based on task query
repocontext pack -q "Fix JWT auth expiration" -o prompt.md
# 3. Generate AST symbol map
repocontext map -c
# 4. Analyze token distribution without writing a file
repocontext analyze .pack:Option | Description | Default |
| Packing mode: |
|
| Filter and rank files relevant to coding prompt | None |
| Output format: |
|
| Output file path |
|
| Maximum token budget |
|
| Copy output directly to system clipboard |
|
| Disable automated secret redaction |
|
RepoContext comes with built-in MCP server support. Add it to your claude_desktop_config.json or Cursor/Windsurf MCP settings:
{
"mcpServers": {
"repocontext": {
"command": "npx",
"args": ["-y", "repocontext", "mcp"]
}
}
}get_codebase_map: Returns AST symbol outline map of the repository.
extract_relevant_context: Prunes codebase and returns only files needed for a prompt.
read_file_outline: Reads compressed AST skeleton for a single file.
Feature | Raw Concatenation | Repomix | RepoContext |
AST Skeleton Pruning | ❌ No | ❌ No | ✅ Yes (80% Token Savings) |
Task Relevance Ranker | ❌ No | ❌ No | ✅ Yes (Query-guided Pruning) |
Secret Auto-Redaction | ❌ No | ⚠️ Basic | ✅ Yes (10+ Security Rules) |
Native MCP Server | ❌ No | ❌ No | ✅ Yes (Claude / Cursor / Windsurf) |
Multi-Model Cost Est. | ❌ No | ❌ No | ✅ Yes (GPT-4o/5, Claude, Gemini) |
Contributions, issues and feature requests are welcome! Feel free to check issues page.
This project is MIT licensed.
Extracts and packages only the code files most relevant to a specific user coding task, pruning irrelevant files to save tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Task description or coding prompt (e.g., "Fix JWT authentication token expiration error") | |
| rootDir | No | Path to repository root directory | |
| maxTokens | No | Token budget ceiling (default: 40000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral transparency burden. It does disclose the key behavior of pruning irrelevant files and packaging only relevant code, which is useful. However, it does not clarify whether the operation is read-only, whether files are modified or written anywhere, or what the packaged result looks like.
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 clear sentence with no filler and it front-loads the core action and resource. The slight redundancy between 'only...most relevant' and 'pruning irrelevant files' keeps it from being a perfect 5.
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?
The description is enough to understand the tool's main job, but with no output schema and no annotations, it leaves ambiguity about the returned package format, side effects, and behavior when maxTokens or rootDir are provided. Given the moderate complexity and complete parameter schema, this is adequate but not fully 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 all three parameters. The tool description adds no parameter-specific meaning beyond the schema, such as how maxTokens influences pruning or how rootDir is resolved, so the 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 states a specific verb ('Extracts and packages'), a clear resource ('code files'), and a clear selection criterion ('most relevant to a specific user coding task'). It also signals what makes it distinct from generic mapping or outlining tools: pruning irrelevant files to save tokens.
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 the tool should be used when a user has a concrete coding task and wants only relevant source files, but it does not explicitly mention sibling alternatives or state when not to use it. The usage context is present but largely inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extracts a token-efficient AST symbol outline map (classes, functions, interfaces) of the repository.
| Name | Required | Description | Default |
|---|---|---|---|
| rootDir | No | Path to repository root directory (default: current working directory) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that this is an extraction/read-like operation producing a token-efficient outline, which is helpful context. It does not mention return format, traversal limits, or side-effect guarantees, so transparency is partial.
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 sentence that front-loads the key value ('token-efficient') and clearly states the output type and scope. Every phrase contributes useful information with no redundancy or filler.
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?
The tool is simple with one optional parameter fully documented in the schema. The description conveys what the result is (AST symbol outline map of classes, functions, interfaces) even though there is no output schema. Minor gaps are the absence of explicit sibling routing and output formatting details, but these are not critical for such a simple tool.
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 coverage is 100% and the sole parameter (rootDir) is already described in the input schema, including its default behavior. The description adds no additional parameter-level meaning, so the baseline of 3 applies.
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 uses a specific verb ('Extracts') and a concrete resource ('AST symbol outline map'), lists the symbol types included (classes, functions, interfaces), and states the scope ('of the repository'). This clearly distinguishes it from the file-scoped sibling read_file_outline and from the broader extract_relevant_context.
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 does not explicitly state when to use this tool versus alternatives or mention sibling tools. However, 'token-efficient' and 'of the repository' imply it is intended for obtaining a repository-wide symbol overview with low token cost, which is useful but only implied guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the semantic AST skeleton outline of a single file, omitting internal implementations while preserving signatures and docstrings.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Relative or absolute path to the file |
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 transparently states what is omitted (internal implementations) and what is preserved (signatures and docstrings), giving agents a clear expectation of the result. It does not discuss error behavior or output format, but the read-only nature is clear from the verb.
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 one tightly written sentence with no filler. The main action and resource are front-loaded, and the qualifiers about what is omitted and preserved add meaningful detail without bloat.
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 simple single-parameter tool, the description is largely complete: it says what the tool does, what the output includes, and what it excludes. It lacks explicit guidance on when to prefer it over sibling tools, but the tool's scope is narrow enough that an agent can invoke it correctly with the provided information.
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 fully documents the single filePath parameter. The description adds no new parameter-level meaning beyond confirming the tool operates on a single file, which is already implied by the schema.
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 a specific verb ('Reads') and a specific resource: the semantic AST skeleton outline of a single file. It further distinguishes itself from codebase-wide or context-extraction siblings by emphasizing 'single file' and the outline nature of the result.
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 when to use this tool—when you want signatures and docstrings without implementation detail—but never explicitly states alternatives or exclusion criteria. An agent has to infer the use case from the wording rather than being told when to choose this over extract_relevant_context or get_codebase_map.
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.
v0.1.0extract_relevant_contextget_codebase_mapread_file_outlineScored across 3 tools
The tools are mostly distinct: read_file_outline focuses on a single file's AST skeleton, get_codebase_map provides a repository-wide symbol map, and extract_relevant_context selects relevant files. However, extract_relevant_context and get_codebase_map both involve repository-level analysis, creating some potential overlap in purpose.
All tool names follow a consistent verb_noun pattern with snake_case: extract_relevant_context, read_file_outline, get_codebase_map. The naming is clear, predictable, and uniform.
Three tools is well-scoped for a code context extraction server. Each tool addresses a distinct granularity level (whole repository map, single file outline, relevant file selection) without unnecessary bloat.
The toolset covers the core workflow of navigating and extracting code context: mapping symbols, outlining files, and selecting relevant files. It could potentially benefit from a raw file-content reading tool, but the provided tools are sufficient for the stated purpose.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
