mcp-compression-proxy: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code and other coding agents working in this repository.

What this is

An MCP server that aggregates tools from several backend MCP servers behind one connection, and compresses their descriptions to cut context use.

Two binaries ship:

• mcp-compression-proxy (src/index.ts) — the MCP server itself
• mcp-cli (src/cli/) — progressive tool discovery backed by a daemon that holds warm connections to the backends

The MCP server's handlers live in src/proxy/session.ts (ProxySession), built from one client's view (src/proxy/client-view.ts: its config, backends and tool catalog) and shared services; src/index.ts only wires a session to stdio, or attaches to the daemon with backendMode: "daemon". The daemon (src/cli/daemon.ts) hosts one session per attached proxy (src/daemon/session-host.ts) and answers mcp-cli from the view of the shell each request came from (src/daemon/cli-requests.ts). Backend connections are pooled in src/mcp/backend-pool.ts, keyed by what a backend runs rather than its name, over src/mcp/client-manager.ts; the shared, exclusion-filtered tool list is src/mcp/tool-catalog.ts; compression state, output shaping (--want/--where), call suggestions and the compression audit in src/services/; ranked search and usage learning in src/search/; the optional local model (Cactus Needle 3 through python/needle_bridge.py) in src/models/; the native proxy's discovery tools in src/native/; config loading and ${VAR} expansion in src/config/.

Commands

npm run build          # tsc
npm test               # full suite (builds first via pretest)
npm run test:unit      # unit only
npm run test:coverage  # global coverage floors
npm run test:coverage:patch -- --base origin/main --head HEAD # exact committed patch gate
npm run lint           # eslint, must be 0 problems
npm run typecheck      # tsc --noEmit
npm run sync-version   # align src/version.ts with package.json

pretest builds before testing on purpose: three integration suites spawn dist/index.js and dist/cli/index.js as real subprocesses, so a stale or missing build fails them with MODULE_NOT_FOUND.