cursor-mcp-bridge: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP server (stdio) that lets any MCP host delegate to headless coding-agent CLIs: Codex, Grok, Claude Code, and an opt-in Cursor fallback. The fleet handles implementation, project mapping, surgical reads, filtered command output, and web lookups without putting the worker's full raw context into the caller. The design goal of every tool is context economy: format() in src/index.ts logs the char count returned to context, because that char count is the real cost being optimized.

Commands

npm run build      # tsc → dist/ (the published/registered artifact is dist/index.js)
npm run dev        # run the server from source via tsx (no build step)
npm test           # vitest run — all unit tests
npx vitest run test/cli.test.ts   # single test file
npx vitest run -t "resolveModel"  # single test by name

There is no linter configured. npm run build (tsc, strict: true) is the type-check gate. prepublishOnly runs the build; only dist/ is published (see files in package.json).

Architecture

Five small modules under src/, with pure logic covered by test/*.test.ts. The split exists so the pure logic is testable without spawning a worker process:

• index.ts — MCP server + tool registrations (twelve tools: delegate, fast_delegate, explore, read_slice, run_filtered, web_lookup, plan, build, fan_out, generate_image, follow_up, bridge_stats). Owns tool descriptions and the shared routing params (cwd/model/effort). The second arg to new McpServer(...) is an instructions string that states the routing boundary (read/locate/web/grunt-work → bridge tools; native Read only when about to edit). These load at startup and are visible to the host even while tool schemas are deferred — that is why they matter for adoption. The five core tools (delegate, explore, read_slice, run_filtered, web_lookup) register with _meta: { "anthropic/alwaysLoad": true } so Claude Code (≥2.1.121) eagerly loads their schemas; secondary tools (fast_delegate, plan, build, fan_out, generate_image, follow_up, bridge_stats) stay deferred. format() appends the session_id footer and logs usage; follow_up feeds that id back as RunOpts.resume so a prior worker session continues without resending its context — the footer and follow_up are two ends of the same loop. follow_up takes an optional mode — without it, a resumed session regains full tool access, so continuing a read-only session (explore/read_slice/web_lookup) must pass mode:'ask' to stay read-only. The default (no mode) is for continuing a delegate.
• cli.ts — the only module that touches the child process. runCursor() spawns the engine's CLI; buildCursorArgs()/buildGrokArgs()/buildCodexArgs()/buildClaudeArgs() (+ buildArgs dispatcher), resolveModel(), parseCliJson()/parseCodexJsonl() (+ parseOutput dispatcher), resolveTier(), resolveFastTier(), hasEngine(), binExists(), budgetNote() are pure and unit-tested. Keep the spawn boundary here — do not spawn from elsewhere.
• agents.ts — resolves an optional delegate/fast_delegate/build persona on the host. A name such as pit:issue-investigator searches project/home .claude/agents and ~/.claude/plugins; plugin collisions pick the newest match by mtime. An inline {prompt} skips lookup. Only the markdown body crosses into the worker, and names containing / or .. are rejected.