code-cache-mcp

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

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

Overview / 概述

AI agents repeatedly read source files to answer code questions — burning tokens every time. code-cache-mcp changes this: the agent queries the cache first, gets symbol positions + inheritance + call graph, and only reads the specific line range on a true miss.

Code structure is parsed once using tree-sitter and stored in SQLite. Only structure is persisted — symbol names, kinds, line ranges, inheritance edges, call graph. No raw source code is ever stored.

AI 助手反复读源文件查符号，每次都烧 token。code-cache-mcp 先查缓存：返回符号位置 + 继承关系 + 调用图，仅在 miss 时才按行范围精确读取。代码结构用 tree-sitter 一次解析存入 SQLite，仅存结构不存源码。

Related MCP server: code-analyze-mcp

Features / 功能特性

• Symbol cache — classes, interfaces, enums, methods, functions, fields with line ranges

• Inheritance graph — extends / implements relationships, resolved lazily

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

• AI location memory — auto-persisted when query hits, instant retrieval in future sessions

• Auto-invalidation — FileWatcher detects file changes, re-parses automatically

• Cold-start auto-index — indexes cwd in background when cache is empty

• Multi-language — Java, TypeScript/JavaScript, Python, Go, Rust

• Zero infrastructure — single SQLite file, no server process

• Lightweight — 66MB node_modules (vs 389MB in v0.1), lazy WASM loading

MCP Tools / MCP 工具

v0.2 provides 3 tools (v0.1 had 8):

query_code_cache auto-indexes on miss and retries — no manual setup needed. Cache hits automatically persist as AI locations for future sessions.

query_code_cache 在 miss 时自动索引并重试——无需手动 setup。命中自动存储为 AI location，供后续会话直接命中。

Supported Languages / 支持语言

Setup / 安装配置

Prerequisites / 前提条件

• Node.js ≥ 18

Install / 安装

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

Register with Claude Code / 注册到 Claude Code

claude mcp add code-cache-mcp npx tsx "$(pwd)/packages/server/src/index.ts"

Or add manually to ~/.claude.json under mcpServers:

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

Environment Variables / 环境变量

Architecture / 架构

code-cache-mcp/
├── packages/
│   ├── sdk/                  # Core library (no MCP dependency)
│   │   └── src/
│   │       ├── types.ts      # Shared interfaces
│   │       ├── db.ts         # SQLite schema + queries
│   │       ├── code-cache.ts # CodeCacheStore — orchestrator
│   │       ├── parser-*.ts   # Language-specific parsers
│   │       ├── parser-registry.ts  # Lazy language dispatcher
│   │       └── watcher.ts    # FileWatcher (debounced fs.watch)
│   ├── server/               # MCP server entry point
│   │   └── src/
│   │       ├── index.ts      # CLI entry
│   │       └── mcp.ts        # 3 tool registrations
│   └── wasm/                 # tree-sitter WASM grammar binaries

Database schema / 数据库结构

v0.2 Changes from v0.1 / v0.2 相比 v0.1 的变化

Removed in v0.2

• Semantic search (@xenova/transformers, 45MB + 23MB model cache)

• TokenTracker (@anthropic-ai/sdk)

• PostgreSQL metrics (pg dual-write)

• Cross-session query history (SHA-256 hashing, diff computation)

• Code snippet similarity (Jaccard token matching, unified diff)

• Session dedup cache and session stats table

• AST nodes table and include_ast parameter

• 5 MCP tools: cache_hotness, invalidate_cache, store_ai_location, get_ai_locations, cache_clear

• report.ts and claude-log-reader.ts

Tech Stack / 技术栈

Guiding AI to Use the Cache / 引导 AI 使用缓存

AI agents default to Read / grep / LSP because they're familiar. To increase adoption:

1. SessionStart hook — Add to ~/.claude/settings.json:

"SessionStart": [{ "hooks": [{ "type": "command", "command": "cat ~/.claude/code-cache-hint.txt" }] }]

Create ~/.claude/code-cache-hint.txt:

When navigating code, prefer query_code_cache over Read/grep for symbol lookups. It returns file:line positions, inheritance, and call graph — faster than reading whole files. After reading a source file, call store_code_context to cache it.

2. Cold-start auto-index — Built-in. When cache is empty, indexes cwd in background automatically.

3. Teaching tip — Built-in. Cache hits include: "tip": "3 symbols found via cache. Use Read with offset/limit for the specific line ranges above."

4. CLAUDE.md — Add to project root:

## Code Navigation
- Use `query_code_cache` BEFORE `Read` to find symbols. Returns file:line + hierarchy + call graph.
- After `Read` on a source file, call `store_code_context` to build cache.

License / 许可证

MIT