pure-context: Instructions file for Claude Code

If you ever need to run python scripts, use python, not python 3.

PureContext MCP — Project Instructions

What This Project Is

PureContext MCP is a Node.js/TypeScript MCP (Model Context Protocol) code-intelligence server for AI agents. It indexes codebases using tree-sitter AST parsing, stores structured symbol metadata in SQLite, and serves two layers: token-efficient retrieval (let agents pull the exact symbols they need instead of reading whole files — the original, benchmarked foundation) and change intelligence (blast radius, temporal co-change, composite per-symbol risk, and refactor-safety checks so an agent can assess the impact and risk of an edit before making it). Retrieval is the foundation; safe autonomous change is the differentiation.

The full product requirements are in docs/PureContext_MCP_PRD_v1.0.docx. Read it before making architectural decisions.

---

Architecture Rules

Three-Layer Architecture (never violate)

1. Core (src/core/) — File discovery, content hashing, tree-sitter dispatch, SQLite storage, MCP transport, file watcher. Knows nothing about specific languages or frameworks.
2. Language Handlers (src/handlers/) — Map file extensions to tree-sitter grammars, define which AST node types are symbols, extract signatures and imports. Each handler is a self-contained module implementing LanguageHandler.
3. Framework Adapters (src/adapters/) — Domain-specific symbol extraction on top of language handlers. Auto-detected from project config files. Each adapter implements FrameworkAdapter. Optional and composable.

The dependency direction is strictly downward: Adapters → Handlers → Core. Never the reverse.

Key Interfaces

// src/core/types.ts

interface SymbolRecord {
  id: string;                    // Deterministic hash: SHA-256(filePath:name:kind).slice(0,16)
  name: string;
  kind: SymbolKind;
  filePath: string;              // Relative to repo root
  startByte: number;
  endByte: number;
  signature: string;             // One-line signature
  summary: string;               // One-line description
  frameworkMeta?: Record<string, unknown>;
}

type SymbolKind =
  | 'function' | 'class' | 'method' | 'const' | 'type'
  | 'interface' | 'enum' | 'component' | 'composable'
  | 'hook' | 'route' | 'decorator' | 'middleware' | 'property';

interface LanguageHandler {
  extensions(): string[];
  grammarPath(): string;         // Path to .wasm file (null for regex-only handlers)
  extractSymbols(tree: Tree, source: Buffer): SymbolRecord[];
  extractImports(tree: Tree, source: Buffer): ImportRecord[];
  extractDocstring(node: SyntaxNode): string | null;
}

interface FrameworkAdapter {
  name: string;
  detect(projectRoot: string): Promise<boolean>;
  fileFilter(filePath: string): boolean;
  preProcess?(source: Buffer, filePath: string): ProcessedBlock[];
  extractFrameworkSymbols(tree: Tree, source: Buffer, filePath: string): SymbolRecord[];
  enrichMetadata?(symbol: SymbolRecord): SymbolRecord;
}