CLAUDE.md

This file contains only what an agent cannot easily derive from code: architectural decisions and their reasons, non-obvious conventions, and cross-cutting rules. Before changing anything, ask: "Can the agent figure this out easily by reading the code?" If yes, don't add it.

If you discover something non-obvious that a future agent couldn't derive from code alone, propose a CLAUDE.md update to the user.

What this project is

MCP server that gives AI agents cheap, precise code understanding. Instead of dumping entire files into context, the agent queries local indexes (AST, call graph, type graph, vector search) and gets back only what it needs. All indexing is local and live — file watcher keeps everything current as code changes.

Primary goal: AI agents should do higher-quality work on code, at lower cost. Less token waste, more relevant context, better decisions. Every feature and improvement must serve this — if it doesn't help the agent work better or cheaper, it doesn't belong here.

Build & Run

npm run build          # TypeScript → dist/
npm run dev            # Run with tsx (dev mode)
npm test               # vitest

Architecture

Single-process Node.js MCP server. stdout is reserved for MCP protocol — never console.log(), use logger from utils/logger.ts (writes to .code-context/server.log).

Layers

index.ts             → MCP shell: registerTool × 3, transport, shutdown
services.ts          → Composition root: ALL concrete instantiation here
tools/               → 3 tool handlers (thin orchestrators, interface-only deps)
core/                → Business logic behind interfaces
parsers/             → 7 language parsers (tree-sitter wrappers)
utils/               → Config, file I/O, git, logging, SQL escape
scripts/             → CLI tools (init, reindex, setup)
types/index.ts       → Data types (FunctionRecord, VectorRow, CallGraphEntry, etc.)
types/interfaces.ts  → All interfaces

Key design decisions

• MCP connects after indexing — initializeWorkspaces() runs first so tools are ready on first agent call. Embedding runs in the background after connect via backgroundEmbed(). Cached init takes <2s, well within MCP client timeout.
• ready flag — tools return NOT_READY error until init completes (tool-utils.ts:checkReady()).
• ReindexOrchestrator (core/reindex-orchestrator.ts) — single place for all reindex workflows (full, incremental, file-level, watcher). Tool handler and watcher both delegate to it.
• Graph persistence — call graph and type graph cached as JSON in .code-context/. Validated via index fingerprint (SHA-256 of file hashes). Mismatch → full rebuild.
• Workspace isolation — monorepo workspaces get separate AST index, call graph, type graph, LanceDB table. No cross-workspace relationships.

Composition root (services.ts)

All concrete class instantiation is in createServices(). Tool handlers never import concrete classes — they receive AppContext which exposes only interfaces. To swap a component (e.g., LanceDB → Qdrant): change 1 line in services.ts.

Rules

SOLID

Follow SOLID principles in all changes. Concrete example: all language-specific knowledge (test markers, noise targets, builtin methods) lives in parser configs — never in tool handlers or core modules. Adding a language must not require modifying existing files beyond registry.ts.

Language & project agnosticism

All heuristics must be structural (body size, param count, call graph centrality), never based on naming conventions (get/set prefix) or framework-specific paths (/entity/, /controllers/). Every change must work across all 7 supported languages and any project structure.

Tool handlers

• Never import from core/ or utils/ — depend only on AppContext and WorkspaceServices interfaces
• Keep thin — orchestration logic belongs in services (e.g., ReindexOrchestrator), not handlers
• Always use textResponse() for responses
• Follow the pattern:

export async function handleToolName(args: { ... }, ctx: AppContext) {
  const resolved = resolveWorkspaceOrError(ctx, args.workspace);
  if ("error" in resolved) return resolved.error;
  const ws = resolved.ws;
  // ... use ws.index, ws.callGraph, ctx.reindex, ctx.git, etc.
  return textResponse(result);
}

Path conventions

• FunctionRecord.id: "filePath::functionName" (workspace-relative). call-graph.ts:removeByFile relies on this prefix format — don't change without updating graph cleanup.
• FunctionRecord.filePath: workspace-relative (e.g., "src/core/search.ts")
• Module path: directory part of filePath, sourceRoot stripped (e.g., "core" not "src/core")
• Boundary rule: FunctionIndex stores relative, globSourceFiles returns absolute, FileWatcher receives absolute. Convert at boundaries.

Adding things

New language parser

1. Create src/parsers/{language}.ts — implement 5 extract functions (extractFunctions, extractCalls, extractImports, extractTypeRelationships, extractDocstring) + metadata fields (testDecorators, testImportPrefixes, noiseTargets, builtinMethods, noisePatterns)
2. Export a TreeSitterLanguageConfig
3. Add to PARSER_CONFIGS in src/parsers/registry.ts
4. Add extensions to default config in src/utils/config.ts
5. Add tree-sitter-{language} dependency + override in package.json

New tool

1. Add Zod schema in src/tools/schemas.ts — every param needs .describe() with examples
2. Create handler in src/tools/{name}.ts following the handler pattern
3. Register in src/index.ts — description must say WHEN and WHY to use the tool
4. Business logic goes in a service, not the handler

New service

1. Define interface in src/types/interfaces.ts
2. Create implementation in src/core/{name}.ts
3. Add to AppContext or WorkspaceServices in interfaces.ts
4. Wire concrete class in src/services.ts

Testing

TestHarness (src/test-harness.ts) — test MCP tools against any project. Three modes: testAll() runs built-in generic tests, run([...]) executes agent-defined cases in bulk, call() for single manual calls. close() releases memory (clear all index/graph maps).

initializeWorkspaces() in services.ts — shared init logic between MCP server and test harness. Returns WorkspaceEmbedPlan per workspace; MCP server passes this to backgroundEmbed(), test harness ignores it.

Gotchas

• tree-sitter CJS in ESM — use createRequire(import.meta.url), never dynamic import() for tree-sitter
• LanceDB FTS — Index.fts() may throw in some versions. Always try/catch.
• LanceDB tag filtering — delimiter format ",tag1,tag2," with LIKE '%,tag1,%' for exact match. Without leading/trailing commas, LIKE '%pay%' false-matches payment.
• LanceDB vectors — Float32Array must be converted to regular arrays before storage.
• Embedding failures — failed batches are skipped (not zero-filled). Unembedded functions get retried on next reindex.
• LanceDB query API — use table.query().where(filter) not table.filter(filter) (removed in newer versions). Always try/catch.
• Setup path resolution — never use which/resolveCommand to find package scripts (codeweave-server, codeweave-init). When setup runs via npx, which returns npx's temp cache path (~/.npm/_npx/<hash>/...) which breaks after cache cleanup. Use process.execPath for node and npm root -g for package scripts.

CRITICAL: This project uses CodeWeave MCP

Always prefer codeweave tools over generic alternatives — they are faster, cheaper, and more accurate.

When you add or modify a function, you MUST add a docstring. Start with a one-line summary, then add annotations:

• @deps: functionA, ClassB.method — functions it calls (always include)
• @tags: auth, payments, api — domain/concern labels (always include)
• @side_effects: database_write, external_api_call — if the function has observable effects

These annotations power semantic search — without them, retrieval quality degrades significantly.

When writing code, if you notice a docstring that is incorrect, misleading, or missing — fix it, even if it's not part of your current task. This keeps the index accurate over time.