ContextCache MCP

Budget-aware context packs for AI coding assistants.
Stop sending entire codebases to your LLM. Send only what matters — within a token budget you control.

ContextCache is a local MCP server that indexes your TypeScript/JavaScript project and returns Context Packs — minimal, dependency-aware file sets optimized for a specific task.

Works with Cursor, Claude Code, Codex CLI, and any MCP-compatible client.

Why use ContextCache?

Example: task "fix login bug" on a 500-file repo → returns AuthService.ts, JwtMiddleware.ts, and their dependencies — not your entire src/ tree.

Related MCP server: agent-workspace-mcp

Features

• Budget-aware selection — set budget_tokens; engine stops before exceeding it

• Dependency graph — BFS expansion from seed files (not flat keyword search)

• AST-based indexing — TypeScript Compiler API extracts classes, functions, imports, exports

• Incremental index — skips unchanged files via content_hash

• Query cache — instant responses for repeated tasks (auto-invalidated on reindex)

• Relevance score — 0.0–1.0 signal strength on every pack

• 100% local — SQLite on disk, no cloud, no API keys, no embeddings required

• Two MCP tools — get_context_pack, get_file_summary

Quick start

Prerequisites

• Node.js 20+

• A TypeScript or JavaScript project to index

1. Clone & build

git clone https://github.com/YOUR_USERNAME/contextcache-mcp.git
cd contextcache-mcp
npm install
npm run build

2. Index your project

# From your project root:
node /path/to/contextcache-mcp/apps/indexer/dist/cli.js init
node /path/to/contextcache-mcp/apps/indexer/dist/cli.js index
node /path/to/contextcache-mcp/apps/indexer/dist/cli.js stats

3. Add MCP server to your AI client

Cursor — create or edit .cursor/mcp.json in your project:

{
  "mcpServers": {
    "contextcache": {
      "command": "node",
      "args": ["/absolute/path/to/contextcache-mcp/apps/server/dist/index.js"],
      "env": {
        "CONTEXTCACHE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Claude Desktop — edit claude_desktop_config.json with the same block.

See mcp-config.example.json for a template.

4. Use it

Ask your assistant to call get_context_pack at the start of a coding task:

{
  "task": "fix authentication bug in login flow",
  "budget_tokens": 4000,
  "mode": "cursor"
}

Sample response:

{
  "relevance_score": 0.84,
  "budget_used": 2300,
  "budget_remaining": 1700,
  "summary": "3 core files, 2 dependencies via graph.",
  "files": [
    {
      "path": "src/auth/AuthService.ts",
      "score": 0.92,
      "summary": "Classes: AuthService. Exports: login, authenticate",
      "token_estimate": 340
    }
  ],
  "dependencies": [
    { "path": "src/repos/UserRepository.ts", "relation": "imported_by", "depth": 1 }
  ],
  "token_metrics": {
    "full_project_tokens": 58000,
    "selected_tokens": 2300,
    "saved_tokens": 55700,
    "reduction_percent": 96.0
  }
}

MCP tools

get_context_pack

Builds a complete context pack for a task.

get_file_summary

Returns structured metadata for a single file.

{ "path": "src/auth/AuthService.ts" }

CLI

npm run contextcache -- <command>

# Human-readable pack
npm run contextcache -- pack "fix login bug" -b 4000 -m text

# JSON pack
npm run contextcache -- pack "fix login bug" -b 4000 -m json

How it works

Your task + budget_tokens
         │
         ▼
   QueryCache ── hit? ──► return cached pack
         │ miss
         ▼
   HeuristicRanker ──► rank files by symbols, paths, imports
         │
         ▼
   DependencyGraph ──► expand related files (BFS, 2 hops)
         │
         ▼
   TokenBudgetManager ──► select files until budget is full
         │
         ▼
   Context Pack + relevance_score + token_metrics

Ranking signals: symbol match · path match · graph proximity · import match

Benchmarks

npm run benchmark
npm run benchmark:report   # saves benchmarks/results/latest.json

Tracks relevance_score, precision, reduction_percent, and generation_time_ms against fixture projects.

Project structure

contextcache-mcp/
├── apps/
│   ├── shared/     # ContextEngine, DependencyGraph, indexer
│   ├── indexer/    # CLI (contextcache)
│   └── server/     # MCP server (stdio)
├── benchmarks/
├── mcp-config.example.json
└── ARCHITECTURE.md

Each indexed project gets a .contextcache/ folder:

your-project/.contextcache/
├── config.json
└── contextcache.db

What it is NOT

• Not a RAG / vector search tool

• Not a cloud service

• Not a flat file finder — it builds coherent packs via dependency graph

• Not dependent on paid embedding APIs (MVP)

Roadmap

• Python & C# parsers (tree-sitter)

• Optional semantic search (local embeddings)

• get_related_files tool

• npm global install (npx contextcache)

Requirements

Contributing

Issues and PRs welcome. See ARCHITECTURE.md for technical details.

1. Fork the repo

2. Create a branch (git checkout -b feature/my-feature)

3. Run npm run build && npm run benchmark

4. Open a PR

License

MIT