ContextCache

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.

Node MCP License: MIT TypeScript

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?

Without ContextCache	With ContextCache
AI reads 200–500 files blindly	AI receives 5–15 ranked files
50k+ tokens per request	2k–8k tokens within your budget
Misses UserRepository.ts behind AuthService.ts	Dependency graph expands related files
No visibility into context cost	token_metrics + relevance_score on every pack

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

---

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.

Parameter	Type	Default	Description
task	string	required	What you want to accomplish
budget_tokens	number	8000	Maximum tokens for the pack
mode	"json" | "text" | "cursor"	"json"	text/cursor returns markdown
use_snapshot	boolean	false	Compare against manual snapshot baseline
skip_cache	boolean	false	Bypass query cache

get_file_summary

Returns structured metadata for a single file.

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

---

CLI

npm run contextcache -- <command>

Command	Description
init [path]	Create .contextcache/ in a project
index [paths...]	Index TS/JS files (incremental)
stats	Index stats, token totals, relevance averages
snapshot	Save a manual baseline snapshot
pack <task>	Generate a context pack from terminal

# 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

Requirement	Version
Node.js	20+
Languages (MVP)	TypeScript, JavaScript

---

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