code-cache-mcp

A persistent, tree-sitter-backed code knowledge cache for AI agents — delivered as an MCP server.

持久化的代码知识缓存 MCP 服务，基于 tree-sitter 语法分析，专为 AI 编码助手设计。

Overview / 概述

English

When an AI agent answers code-related questions, it normally has to read source files repeatedly — burning tokens every time. code-cache-mcp intercepts this pattern: the agent calls the cache first, gets back pre-parsed symbols, inheritance trees, call graphs, and previously AI-located positions, and only falls back to reading raw files on a true cache miss.

Code structure is analyzed once using tree-sitter and stored in a local SQLite database. Only parsed structure is persisted — symbol names, kinds, line ranges, inheritance edges, and call graph. Raw source code is never written to the cache. Subsequent queries return structured results instantly — no re-parsing, no full file reads.

中文

AI 助手回答代码相关问题时，通常需要反复读取源文件，每次都消耗大量 token。code-cache-mcp 改变这一模式：助手优先查询缓存，获取预解析好的符号信息、继承关系、调用图谱以及历史 AI 定位记录，仅在真正的缓存未命中时才回退到读取原始文件。

代码结构通过 tree-sitter 一次性分析后存入本地 SQLite 数据库。缓存仅保存解析后的结构——符号名称、类型、行号范围、继承边、调用图，不存储任何原始源码。后续查询直接返回结构化结果，无需重新解析或读取完整文件。

Related MCP server: github-codemunch-mcp

Features / 功能特性

• Symbol cache — classes, interfaces, enums, methods, functions, fields with line ranges (no raw code stored — structure only)

• Inheritance graph — extends / implements relationships stored as a graph; forward references resolved lazily as more files are cached

• Call graph — method invocation edges (caller → callee) extracted from method bodies

• AI location memory — persist code positions identified by AI sessions so future sessions find the same code instantly

• Auto-invalidation — FileWatcher detects file changes (100 ms debounce), invalidates stale cache entries, and re-parses automatically

• Multi-language — Java, TypeScript / JavaScript, Python (extensible via WASM grammar files)

• Zero infrastructure — single SQLite file, no server process required

• In-memory symbol index — symbol-name substring search runs entirely in JS (Array.filter + String.includes), bypassing SQLite LIKE scans; results fetched via a single indexed WHERE id IN (...) query

• In-memory embedding cache — semantic search embedding vectors are cached in the CodeCacheStore instance; the full DB load only re-runs when new files are indexed (dirty flag)

• Batch relationship queries — parent name, AST nodes, class relationships, callers, and callees are fetched with a single IN (...) query per type, replacing an N+1 per-hit loop

• 符号缓存 — 类、接口、枚举、方法、函数、字段，含行号范围（仅存结构，不存原始代码）

• 继承关系图 — extends / implements 关系以图结构存储，新文件入库时自动补全悬空引用

• 调用图谱 — 从方法体提取调用边（caller → callee）

• AI 定位记忆 — 持久化 AI 会话识别的代码位置，后续会话可直接命中

• 自动失效 — FileWatcher 检测文件变更（100 ms 防抖），自动清除过期缓存并重新解析

• 多语言支持 — Java、TypeScript / JavaScript、Python（通过 WASM 语法文件扩展）

• 零基础设施 — 单个 SQLite 文件，无需额外服务进程

• 内存符号索引 — 符号名称子串搜索完全在 JS 层执行（Array.filter + String.includes），绕过 SQLite LIKE 全表扫描；结果通过单条 WHERE id IN (...) 索引查询取回

• 内存 Embedding 缓存 — 语义搜索向量缓存在 CodeCacheStore 实例中，仅在新文件入库（脏标记）时才重新从 DB 加载

• 批量关系查询 — parent 名称、AST 节点、类关系、调用者、被调用者各用一条 IN (...) 批量查询替代原先的 N+1 循环

MCP Tools / MCP 工具

Semantic Search / 语义相似搜索

query_code_cache supports a semantic_query parameter — a natural language description that finds symbols by meaning rather than by exact name.

query_code_cache 支持 semantic_query 参数，通过语义相似度而非名称精确匹配来查找符号。

How it works / 工作原理

1. When a file is cached via store_code_context, each symbol is embedded using [Xenova/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) (384-dim, quantized, runs entirely locally via @xenova/transformers). Embedding generation runs asynchronously — it never delays cache writes. 文件入库后，每个符号通过本地量化模型（384 维）生成嵌入向量，异步执行不阻塞写入。

2. At query time, semantic_query is embedded with the same model, then compared against stored vectors using cosine similarity. Embedding vectors are cached in memory after the first load; the cache is invalidated only when new files are indexed, so repeated semantic queries pay no DB round-trip cost. Top-K results (score ≥ 0.3) are returned and merged with any lexical matches. 查询时，模型对 semantic_query 生成向量，与存储向量做余弦相似度计算。Embedding 向量首次加载后缓存于内存，仅在新文件入库时失效，重复语义查询无需再访问 DB。得分 ≥ 0.3 的 top-K 结果与词法匹配结果合并返回。

3. Results include a semantic_score field (0–1) when returned via semantic search. Results are sorted by score descending. 语义搜索命中的结果包含 semantic_score 字段（0–1），结果按得分降序排列。

Usage example / 使用示例

{
  "tool": "query_code_cache",
  "arguments": {
    "semantic_query": "user authentication and JWT token validation"
  }
}

Can be combined with lexical search for hybrid retrieval:
可与词法搜索组合实现混合检索：

{
  "tool": "query_code_cache",
  "arguments": {
    "symbol": "Auth",
    "semantic_query": "handle login and session expiry",
    "kinds": ["method", "class"]
  }
}

Embedding status / 嵌入向量状态

The cache_stats tool shows Embeddings stored — this count grows as symbols are embedded in the background.
cache_stats 工具显示 Embeddings stored，该数值随后台嵌入生成逐步增加。

Model downloads (~23 MB) are cached in .model-cache/ on first use.
模型文件（约 23 MB）首次使用时自动下载并缓存到 .model-cache/ 目录。

Supported Languages / 支持语言

Architecture / 架构

code-cache-mcp/
├── packages/
│   ├── sdk/                  # Core library (no MCP dependency)
│   │   └── src/
│   │       ├── types.ts      # Shared interfaces
│   │       ├── db.ts         # SQLite schema + typed query helpers
│   │       ├── code-cache.ts # CodeCacheStore — main orchestrator
│   │       ├── parser-java.ts
│   │       ├── parser-typescript.ts
│   │       ├── parser-python.ts
│   │       ├── parser-registry.ts  # Language dispatcher
│   │       ├── embedder.ts   # Semantic embeddings (all-MiniLM-L6-v2 via @xenova/transformers)
│   │       └── watcher.ts    # FileWatcher (debounced fs.watch)
│   ├── server/               # MCP server entry point
│   │   └── src/
│   │       ├── index.ts      # CLI entry
│   │       ├── mcp.ts        # Tool registrations
│   │       ├── report.ts     # npm run report — token savings CLI (timestamps: UTC+8)
│   │       └── claude-log-reader.ts  # reads ~/.claude/ session logs for per-turn stats
│   └── wasm/                 # tree-sitter WASM grammar binaries
│       ├── tree-sitter-java.wasm
│       ├── tree-sitter-typescript.wasm
│       ├── tree-sitter-python.wasm
│       └── tree-sitter.wasm

Database schema / 数据库结构

Setup / 安装配置

Prerequisites / 前提条件

• Node.js ≥ 18

• npm ≥ 7

Install / 安装

cd /path/to/code-cache-mcp
npm install

Register with Claude Code / 注册到 Claude Code

claude mcp add code-cache-mcp npx tsx /path/to/code-cache-mcp/packages/server/src/index.ts

Or add manually to ~/.claude.json under mcpServers / 或手动添加到 ~/.claude.json 的 mcpServers 字段：

"code-cache-mcp": {
  "type": "stdio",
  "command": "npx",
  "args": ["tsx", "/path/to/code-cache-mcp/packages/server/src/index.ts"]
}

Environment Variables / 环境变量

Usage Pattern / 使用模式

Typical agent workflow / 典型 Agent 工作流：

User asks about code
  → Agent calls query_code_cache({ symbol: "PaymentService" })
      CACHE HIT  → returns symbol structure + inheritance + call graph (tokens saved)
      CACHE MISS → Agent calls store_code_context({ file_path: "PaymentService.java" })
                     → tree-sitter parses file
                     → symbols/relationships/call edges stored in SQLite
                   → Agent calls query_code_cache again → HIT
  → Agent calls store_ai_location({ file_path, start_line: 42, reason: "entry point for payment flow" })
  → Agent answers user (no full file reads needed)

File changes on disk:
  FileWatcher → onFileChanged() → invalidate → re-parse → DB updated

Tech Stack / 技术栈

Performance / 性能设计

Query latency / 查询延迟

Indexing throughput / 索引吞吐

Design Decisions / 设计说明

Why SQLite over PostgreSQL / ClickHouse?
ClickHouse is OLAP — wrong fit for row-level cache invalidation. PostgreSQL requires a daemon. SQLite via libSQL gives zero operational overhead, built-in JSON1 extension for AST storage, recursive CTEs for graph traversal, and the same driver already proven in cachebro.

为何选择 SQLite 而非 PostgreSQL / ClickHouse？
ClickHouse 为 OLAP 设计，不适合行级缓存失效操作；PostgreSQL 需要常驻守护进程。libSQL 版 SQLite 零运维开销，内置 JSON1 扩展可存储 AST，支持递归 CTE 进行图遍历，且与 cachebro 使用同一驱动。

Why separate class_relationships table instead of parent_id on symbols?
A class can implement multiple interfaces — this is a graph, not a tree. The parent_id column on symbols handles containment (method inside class); class_relationships handles inheritance (class extends/implements N parents).

为何单独建 class_relationships 表而非在 symbols 上加 parent_id？
一个类可以实现多个接口，这是图结构而非树结构。symbols.parent_id 处理包含关系（方法属于某类），class_relationships 处理继承关系（类继承/实现 N 个父类/接口）。

References / 参考项目

• cachebro — file cache MCP for AI agents (pattern source for FileWatcher, session stats, SQLite setup)

• tree-sitter — incremental parsing system

• web-tree-sitter — WASM bindings for tree-sitter

Monitoring Token Savings / 监控 Token 节省效果

Implementation status / 实现状态

Approach 1 — JSONL metrics ✅ Always active / 方案一：JSONL 指标（默认启用）

Every MCP tool call is automatically appended to $CODE_CACHE_DIR/metrics.jsonl by MetricsMonitor in packages/sdk/src/monitor.ts. No configuration required.
每次 MCP 工具调用由 monitor.ts 中的 MetricsMonitor 自动追加写入 $CODE_CACHE_DIR/metrics.jsonl，无需任何配置。

npm run report          # hit rate, per-file rank, per-session summary, per-turn Claude API usage
jq 'select(.cache_hit)' .code-cache/metrics.jsonl | jq -s 'map(.tokens_saved)|add'

Each record:

{"ts":1780814175819,"session_id":"...","tool":"query_code_cache",
 "cache_hit":true,"tokens_saved":1200,"tokens_used":300,
 "symbol":"UserService","hits_count":3,"duration_ms":12}

Estimation method / 估算方式：

• tokens_saved — (end_line - start_line + 1) × 30 per matched symbol. The constant 30 approximates an average of ~40 chars/line × 0.75 tokens/char. Real lines vary widely (a closing } is ~1 token; a dense expression can be 60+), so treat this as a rough 2× overestimate relative to actual saved tokens. Useful for relative comparison across sessions, not as an absolute figure.
  每个命中符号按 行数 × 30 估算，约等于平均每行 40 字符 × 0.75 token/字符。实际每行 token 数差异较大，总体偏高约 2 倍，适合会话间横向对比，不宜作为精确绝对值。

• tokens_used — accurate token count via Anthropic count_tokens API when ANTHROPIC_API_KEY is set; falls back to JSON.stringify(response).length / 4 otherwise. Measures the actual MCP response size the agent had to consume.
  设置 ANTHROPIC_API_KEY 时通过 Anthropic API 精确计数；否则退回 响应字节数 ÷ 4 估算。反映本次调用实际消耗的 token 量。

npm run report also reads ~/.claude/projects/ session logs and shows per-turn Claude API token usage. Timestamps displayed in Beijing time (UTC+8).
npm run report 同时读取 ~/.claude/projects/ 会话日志，展示逐轮 Claude API token 用量，时间戳显示为北京时间（UTC+8）。

Approach 2 — PostgreSQL dual-write ✅ Implemented / 方案二：PostgreSQL 双写（已实现）

When METRICS_DB_URL is set, MetricsMonitor writes each record to both JSONL and a PostgreSQL mcp_calls table. The pg package is installed as an optional dependency — no extra setup needed.
设置 METRICS_DB_URL 后，MetricsMonitor 同时写入 JSONL 和 PostgreSQL mcp_calls 表。pg 已作为 optional dependency 安装，无需额外配置。

Setup / 启用步骤：

# 1. Start a PostgreSQL instance (example with Docker) / 启动 PG（Docker 示例）
docker run -d --name pg-metrics -e POSTGRES_PASSWORD=pw -p 5432:5432 postgres:16-alpine

# 2. Start MCP server with the connection string / 设置连接串启动 MCP
METRICS_DB_URL=postgres://postgres:pw@localhost:5432/postgres npm start

The mcp_calls table and indexes are created automatically on first connection.
首次连接时自动建表和索引，无需手动执行 DDL。

-- mcp_calls schema (auto-created)
CREATE TABLE mcp_calls (
  id           BIGSERIAL PRIMARY KEY,
  ts           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  session_id   TEXT NOT NULL,
  tool         TEXT NOT NULL,
  cache_hit    BOOLEAN NOT NULL,
  tokens_saved INTEGER NOT NULL DEFAULT 0,
  tokens_used  INTEGER NOT NULL DEFAULT 0,
  file_path    TEXT,
  symbol       TEXT,
  hits_count   INTEGER,
  duration_ms  INTEGER
);

Useful queries / 常用分析查询：

-- Hit rate and savings per session / 每会话命中率与节省量
SELECT session_id, COUNT(*) calls, ROUND(AVG(cache_hit::int)::numeric, 2) hit_rate,
       SUM(tokens_saved) saved
FROM mcp_calls GROUP BY session_id ORDER BY MIN(ts) DESC LIMIT 20;

-- Hourly token savings trend / 每小时节省趋势
SELECT DATE_TRUNC('hour', ts) h, SUM(tokens_saved) saved, SUM(tokens_used) used
FROM mcp_calls GROUP BY h ORDER BY h;

-- Top symbols by savings / 节省最多的符号
SELECT symbol, COUNT(*) hits, SUM(tokens_saved) saved
FROM mcp_calls WHERE cache_hit AND symbol IS NOT NULL
GROUP BY symbol ORDER BY saved DESC LIMIT 20;

If PG is unavailable or METRICS_DB_URL is unset, MetricsMonitor silently falls back to JSONL-only — the MCP server never crashes on PG failure.
若 PG 不可用或未设置环境变量，MetricsMonitor 静默降级为 JSONL 单写，MCP 服务不会因 PG 故障崩溃。

Approach 3 — TokenTracker ⬜ External tool / 方案三：TokenTracker（外部工具）

TokenTracker reads Claude Code session logs (~/.claude/) and shows macro token totals per session. Useful for A/B comparison (cache on vs off) but cannot break down cache hit/miss or per-file savings.
TokenTracker 读取 Claude Code 会话日志，展示每会话宏观 token 总量。适合 A/B 对比，但无法区分缓存命中/未命中或单文件节省。

pip install tokentracker
tokentracker serve   # dashboard at http://localhost:7680

No code integration required — this project has no dependency on TokenTracker.
无代码集成，本项目不依赖 TokenTracker。

Comparison / 方案对比

License / 许可证

MIT