codeweave-mcp: Instructions file for Claude Code

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