context-minimizer-mcp

An MCP (Model Context Protocol) server that optimizes AI context windows through AST-aware code indexing, intelligent compaction, cross-file code intelligence, and semantic search — saving tokens and reducing costs.

Why?

Large language models have limited context windows. Every token counts. This MCP server sits between your AI coding assistant and your codebase, providing tools that deliver precisely the code you need, compacted to minimize token waste.

Instead of dumping entire files into context, the model calls these tools to:

• Fetch exact line ranges instead of whole files
• Get signatures-only skeletons when exploring unfamiliar code
• Strip comments while preserving type annotations (@param, @returns)
• Search raw text across the codebase (route paths, config keys, error strings)
• Navigate import graphs to understand file relationships
• Trace call chains to understand how functions connect
• Find all references of any symbol across the codebase
• Analyze impact before changing shared symbols or dependency-heavy files
• Detect dead code — unreferenced functions and methods
• Track mutations — find where variables are modified
• Search git history — commits, branches, and file changes
• Cache compacted output to avoid redundant processing
• Check server health including version, database, FTS, and Git availability

Features

| Feature | Description | |---------|-------------| | 25 MCP Tools | Full toolkit for code navigation, search, impact analysis, intelligence, health checks, and optimization | | Minimality Pack | Reuse-first checks, minimal context plans, complexity audits, shortcut ledger, and real token ROI | | Languages & Prose | JS/TS, Python, PHP, Go, Ruby, Rust, Shell, C/C++, Java, Kotlin, Dart, Elixir, Scala, Markdown, JSON, YAML, TOML | | AST + Regex Parsing | Babel (JS/TS) + Python AST for accuracy; regex fallback for 11 additional language categories | | FTS5 Search | Full-text search on both symbols and raw file content (now indexes doc/data files) | | Code Intelligence | Find references, impact analysis, call chains (depth=3), dead code, mutation tracking | | Git Integration | Search commits/branches, recent changes, file history — with 5s timeout safety | | 4-Level Compaction | snippet / skeleton / compact / full — choose your compression level (compact mode compresses Markdown prose and minifies JSON/YAML) | | JSDoc Preservation | Strips prose but keeps @param, @returns, @type tags | | Dependency Graph | Tracks imports/requires with reverse lookup ("what imports this?") | | Reference Index | Lazy cross-file symbol tracking with incremental scanning | | Smart Ranking | Results ranked: exact matches first, src/ over test/, vendor demoted | | LRU Cache | Content-hash cache avoids re-compacting unchanged files | | Incremental Indexing | Only re-processes changed files on subsequent runs | | Performance Guardrails | Depth caps, result limits, timeouts — safe on large codebases | | Static Dashboard | HTML dashboard showing token savings, cache hits, and metrics |

Installation

npm install -g context-minimizer-mcp

Or use directly with npx:

npx context-minimizer-mcp

MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Antigravity, etc.):

{
  "mcpServers": {
    "context-minimizer": {
      "command": "npx",
      "args": ["-y", "context-minimizer-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "context-minimizer": {
      "command": "context-minimizer-mcp"
    }
  }
}

Tools

Code Navigation

| Tool | Description | |------|-------------| | index_workspace | Scan and index workspace files, symbols, and dependencies | | get_codebase_map | Structural overview of all files, classes, and functions | | get_file_outline | Symbols list for a specific file | | get_file_dependencies | Import graph — what a file imports and what imports it |

Code Retrieval

| Tool | Description | |------|-------------| | get_code_snippet | Fetch exact line range with optional compaction | | get_symbol_definition | Get a function/class by name with scope filters | | get_optimized_file | Full file with tiered compaction |

Search

| Tool | Description | |------|-------------| | search_code | FTS5 search across symbol names and signatures | | search_text | Raw content grep — find string literals, routes, config keys | | get_optimized_context | Combined code + memory search with compaction |

Code Intelligence ✨ New in v3

| Tool | Description | |------|-------------| | find_references | Find all usages of a symbol across the codebase (depth up to 3) | | impact_analysis | Analyze likely impact for a symbol or file: references, call chains, dependencies, likely tests, snippets, and optional git context | | call_chain | Trace upstream (who calls this?) or downstream (what does this call?) call graphs | | find_writes | Locate mutation sites — assignments, .push(), file writes, shell redirects | | dead_code | Detect functions/methods with zero references in the indexed codebase |

Git Tools ✨ New in v3

| Tool | Description | |------|-------------| | git_context | Search commits and branches by keyword, get file history | | recent_changes | List changed files + affected symbols in last N days |

Minimality Pack 🧘 New in v3.3

| Tool | Description | |------|-------------| | reuse_first | Check local code, installed dependencies, stdlib/native hints, Git, and SuperBrain before building new helpers | | minimal_context_plan | Plan the cheapest useful retrieval sequence for a task: snippets, outlines, skeletons, compact files, then full files only when needed | | complexity_audit | Repo-wide or path-scoped over-engineering audit with ranked delete/reuse/simplify findings | | simplicity_review | Diff or file-scoped review focused only on removable complexity | | shortcut_ledger | Collect context-minimizer: and minimize: simplification markers and flag missing upgrade triggers | | token_roi | Report real optimizer savings from logs: bytes saved, estimated tokens saved, compaction ratio, and cache hit rate |

Stats

| Tool | Description | |------|-------------| | get_optimizer_stats | Token savings, cache hit rate, reference index size, and file metrics | | server_info | Show package version, database path, indexed counts, FTS availability, and Git availability |

Supported Languages

| Language | Parser | Symbol Types | |----------|--------|-------------| | JavaScript/TypeScript | Babel AST | classes, functions, methods, imports | | Python | AST (subprocess) | classes, functions, methods, imports | | PHP | Regex | classes, functions, interfaces, traits | | Go | Regex | functions, structs, interfaces | | Ruby | Regex | classes, modules, methods | | Rust | Regex | functions, structs, enums, traits, impls | | Shell/Bash | Regex | functions | | C/C++ | Regex | functions, structs, enums | | Java | Regex | classes, interfaces, enums, methods | | Kotlin | Regex | classes, objects, functions | | Dart | Regex | classes, functions | | Elixir | Regex | modules, functions | | Scala | Regex | classes, objects, traits, functions |

Compaction Levels

Every retrieval tool accepts a level parameter:

| Level | What's Preserved | Tokens | Use Case | |-------|------------------|--------|----------| | snippet | Match line ± 1 line of context | ~15 per result | Orientation / scanning | | skeleton | Signatures + imports only, no function bodies | ~40% of original | Codebase exploration | | compact | Full code minus comments/whitespace (default) | ~70% of original | Normal coding | | full | Everything including comments | 100% | Reading author intent |

JSDoc Type Preservation

Unlike naive comment strippers, compact mode preserves type-carrying JSDoc tags:

// Input:
/**
 * Finds a user in the database.
 * This is a very important function.
 * @param {string} userId - The user's unique identifier
 * @returns {Promise<User|null>}
 */
function findUser(userId) { ... }

// Compact output (keeps types, strips prose):
/**
 * @param {string} userId - The user's unique identifier
 * @returns {Promise<User|null>}
 */
function findUser(userId) { ... }

Code Intelligence

Impact Analysis

impact_analysis({ symbol: "compactCode", depth: 2, includeSnippets: true, maxResults: 30 })
-> Definitions for compactCode
-> Direct references and upstream/downstream callers
-> Likely tests and compact snippets
-> Git context when available

Find References

find_references({ symbol: "saveFile", depth: 2 })
→ Direct: tools.js:L187 [call], database.js:L210 [call]
→ Indirect (depth 2): index.js:L45 via registerTools

Call Chain

call_chain({ symbol: "compactCode", direction: "upstream", depth: 3 })
→ compactCode
  ← cachedCompact  [tools.js:L113]
    ← registerTools  [tools.js:L404]
    ← formatSymbolResults  [tools.js:L465]

Dead Code Detection

dead_code()
→ getSupportedLanguages (function) in regex-parsers.js:L226
→ gitFileDiff (function) in git.js:L133

Mutation Tracking

find_writes({ target: "db" })
→ database.js:L20: db = new Database(DB_PATH)
→ database.js:L184: db = null

Performance Guardrails

| Guard | Limit | Why | |-------|-------|-----| | Reference depth | max 3 | Prevents exponential BFS fan-out | | Results per tool | max 50 | Keeps responses bounded | | Git commands | 5s timeout | Prevents hanging on large repos | | Reference build | 10s timeout | Lazy indexing won't block tools | | BFS visited set | max 200 nodes | Memory safety for call chain traversal | | find_writes | max 20 results | Focused mutation tracking |

Reference indexing is lazy — only triggered on first use of find_references, call_chain, or dead_code. The index_workspace tool remains fast.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CONTEXT_MINIMIZER_DIR | ~/.context_minimizer | Database storage directory | | SUPERBRAIN_DB_PATH | ~/.superbrain/brain.db | SuperBrain memory database path |

Dashboard

The server writes a stats.js file to a dashboard/ directory on every operation. Open dashboard/dashboard.html in your browser to see:

• Total tokens saved
• Cache hit rate
• Files indexed by language
• Cross-references tracked
• Recent compaction history

No web server needed — it's a static HTML file that reads the auto-generated data.

How It Works

┌─────────────┐     stdio      ┌──────────────────────┐
│  AI Model   │ ◄────────────► │  MCP Server          │
│  (Claude,   │   MCP tools    │                      │
│   Gemini)   │                │  ┌────────────────┐  │
└─────────────┘                │  │ Babel AST      │  │
                               │  │ Python AST     │  │
                               │  │ Regex Parsers  │  │
                               │  └───────┬────────┘  │
                               │          │           │
                               │  ┌───────▼────────┐  │
                               │  │ SQLite DB      │  │
                               │  │ FTS5 Index     │  │
                               │  │ Reference Index│  │
                               │  └───────┬────────┘  │
                               │          │           │
                               │  ┌───────▼────────┐  │
                               │  │ Compactor      │  │
                               │  │ + LRU Cache    │  │
                               │  │ + Git Utils    │  │
                               │  └────────────────┘  │
                               └──────────────────────┘

1. Index — index_workspace scans files, parses AST/regex symbols, extracts imports, stores in SQLite with FTS5
2. Search — search_code / search_text queries the FTS5 index for symbols or raw content
3. Retrieve — get_code_snippet / get_symbol_definition / get_optimized_file fetch code with configurable compaction
4. Analyze — find_references / call_chain / dead_code / find_writes provide cross-file code intelligence
5. Git — git_context / recent_changes search version history and cross-reference with indexed symbols
6. Cache — LRU cache keyed by content hash + compaction level avoids redundant work
7. Track — Every compaction logs bytes saved, tokens saved, and updates the dashboard

Minimality Pack Usage Examples

Reuse Before Build

Check if local symbols, dependencies, or stdlib hints can cover your intent:

reuse_first({ intent: "add config parser", filePath: "src/tools.js" })
-> Verdict: reuse
-> Returns ranked local symbols, dependency hints, and Node stdlib APIs

Minimal Context Planning

Propose the cheapest retrieval sequence for a task:

minimal_context_plan({ task: "change shared cache helper", symbols: ["cachedCompact"], risk: "high" })
-> Proposes: search_code first, impact_analysis, get_optimized_file(level="compact")

Token ROI

Check real savings from the optimizer:

token_roi({ days: 30, groupBy: "file", limit: 10 })
-> Reports: runs, raw/compacted bytes, cache hit rate, and savings per file

Testing

npm test

Runs 14 test suites covering AST parsing, compaction, FTS5 search, dependency graph, caching, and more.

License

MIT