copperhead 0.9.0 → 0.11.0

package/src/mcp/server.ts

@@ -0,0 +1,560 @@
+/**
+ * `copperhead mcp` — a stdio MCP server exposing the gated pipeline to MCP
+ * hosts as five opaque, outcome-level tools (design D1).
+ *
+ * The security boundary is tool granularity, not prompt wording. Hosts get
+ * `check`, `do`, `sync` and `init` as whole-pipeline invocations, plus the
+ * read-only `doctor` probe, and nothing finer: no file-edit tool, no raw KiCad
+ * tool, no way to drive one step of the loop. There is therefore no sequence of MCP calls that skips the spec gate or
+ * the verification gate, because every mutating path runs the same loop the CLI
+ * runs. Safety rails are inherited rather than restated — this module is a
+ * transport adapter over the existing command entry points, and deliberately
+ * owns no policy of its own.
+ *
+ * Two rails are enforced here because they are properties of the transport
+ * rather than of the pipeline: stdout carries only the JSON-RPC stream (every
+ * human-readable byte goes to stderr, or the protocol corrupts), and mutating
+ * calls are serialized per repo *within this server process*. That lock is
+ * in-memory, so it does not interlock two separately spawned servers or a
+ * concurrent CLI run — those are held apart by the loop's own dirty-tree
+ * preflight, not by this.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+import { loadConfig, resolveModel, type ModelSource } from '../config.js';
+import { runCheck } from '../commands/check.js';
+import { syncVerify, syncResolve, formatSyncReport } from '../commands/sync.js';
+import { runInit, InitError } from '../memory/scaffold.js';
+import { SandboxError } from '../util/paths.js';
+import { runDoctor } from '../commands/doctor.js';
+import { runAgentLoop, type RunResult } from '../agent/loop.js';
+import { kicadCliVersion } from '../kicad/cli.js';
+import { seal, type ToolResult, type ToolErrorKind } from '../agent/envelope.js';
+import { plainRenderer, type ProgressRenderer } from '../agent/render.js';
+
+/** The copperhead package version, for run self-description (AC-8.1). This is
+ *  deliberately not MCP_PROTOCOL_VERSION: run metadata records which copperhead
+ *  produced a commit, and the transport's own version would be a false answer. */
+const { version: COPPERHEAD_VERSION } = createRequire(import.meta.url)('../../package.json') as { version: string };
+
+/**
+ * Unstable by declaration (design D7). The `0.` major is load-bearing: it is
+ * the signal to hosts that tool names, input schemas and result shapes may
+ * change in any release, and it is what defers a registry listing until the
+ * stabilization criteria in the proposal are met. A test asserts the `0.`, so
+ * removing the experimental status is a deliberate edit rather than a drift.
+ */
+export const MCP_PROTOCOL_VERSION = '0.1.0';
+
+/** The entire surface. Anything not on this list is not reachable over MCP. */
+export const PIPELINE_TOOL_NAMES = [
+  'copperhead_check',
+  'copperhead_do',
+  'copperhead_sync',
+  'copperhead_init',
+  'copperhead_doctor',
+] as const;
+
+export type PipelineToolName = (typeof PIPELINE_TOOL_NAMES)[number];
+
+/**
+ * Per-tool input schema versions, bumped when a tool's inputs change shape.
+ * Separate from MCP_PROTOCOL_VERSION so one tool changing does not imply the
+ * whole surface did.
+ */
+export const TOOL_SCHEMA_VERSIONS: Record<PipelineToolName, number> = {
+  copperhead_check: 1,
+  copperhead_do: 1,
+  copperhead_sync: 1,
+  copperhead_init: 1,
+  copperhead_doctor: 1,
+};
+
+/** Human-readable output goes to stderr; stdout belongs to JSON-RPC alone. */
+const note = (line: string): void => {
+  process.stderr.write(`${line}\n`);
+};
+
+/** A sealed failure envelope. `seal` redacts, so a key can never ride out. */
+export function failure(kind: ToolErrorKind, message: string): ToolResult {
+  return seal({ ok: false, summary: message, error: { kind, message } });
+}
+
+/**
+ * Resolve the model for an LLM-backed tool, converting the two ways model
+ * resolution can fail into typed errors a host agent can act on: no credential
+ * at all, and two credentials with nothing to choose between them. Neither is
+ * an exception — a host that cannot run `do` should be told why in a result.
+ */
+async function resolveModelOrFail(
+  repoRoot: string,
+): Promise<{ model: string; source: ModelSource } | { error: ToolResult }> {
+  try {
+    const config = await loadConfig(repoRoot);
+    const { model, source } = resolveModel(undefined, config);
+    return { model, source };
+  } catch (err) {
+    // `unavailable` rather than `validation`: the call was well-formed, the
+    // environment just cannot serve it.
+    return { error: failure('unavailable', (err as Error).message) };
+  }
+}
+
+/** kicad-cli is a hard precondition for every tool, exactly as in the CLI. */
+async function requireKicad(): Promise<{ version: string } | { error: ToolResult }> {
+  try {
+    return { version: await kicadCliVersion() };
+  } catch (err) {
+    return {
+      error: failure(
+        'unavailable',
+        `kicad-cli is not available: ${(err as Error).message}. Install KiCad 9+ and ensure kicad-cli is on PATH.`,
+      ),
+    };
+  }
+}
+
+/**
+ * Mutating tools are serialized per repo. Rejecting rather than queueing is
+ * deliberate: a `do` run can take minutes, and a host blocked on an invisible
+ * queue looks hung, while a typed busy error is something an agent can relay
+ * and retry. Concurrent `check` calls are unrestricted — they mutate nothing.
+ */
+export class RepoLocks {
+  private readonly busy = new Set<string>();
+
+  tryAcquire(repoRoot: string): boolean {
+    if (this.busy.has(repoRoot)) return false;
+    this.busy.add(repoRoot);
+    return true;
+  }
+
+  release(repoRoot: string): void {
+    this.busy.delete(repoRoot);
+  }
+
+  isBusy(repoRoot: string): boolean {
+    return this.busy.has(repoRoot);
+  }
+}
+
+/** Progress sink: what the server needs from a host to report a long run. */
+export interface ProgressSink {
+  (update: { message: string; progress: number }): void;
+}
+
+/**
+ * A ProgressRenderer that mirrors loop progress onto MCP progress
+ * notifications. `progress` is a monotonically rising count of observed events
+ * rather than a percentage: the loop cannot know how many turns a run will take,
+ * and inventing a denominator would be a worse lie than an open-ended counter.
+ */
+export function mcpRenderer(sink: ProgressSink): ProgressRenderer {
+  let ticks = 0;
+  const emit = (message: string): void => {
+    ticks += 1;
+    sink({ message, progress: ticks });
+  };
+  const base = plainRenderer((line) => {
+    note(line);
+  });
+  return {
+    log: (line) => {
+      base.log(line);
+    },
+    turnStart: (turn, maxTurns, tokensIn, tokensOut) => {
+      base.turnStart(turn, maxTurns, tokensIn, tokensOut);
+      emit(`turn ${turn}/${maxTurns}`);
+    },
+    toolResult: (name, firstLine, ok, viewHint) => {
+      base.toolResult(name, firstLine, ok, viewHint);
+      emit(`${name}: ${firstLine}`);
+    },
+    status: (text) => {
+      base.status(text);
+    },
+    heartbeat: (info) => {
+      base.heartbeat(info);
+      emit('working');
+    },
+    finish: (line) => {
+      base.finish(line);
+      emit(line);
+    },
+  };
+}
+
+/**
+ * Map a finished run onto the status vocabulary hosts see. `rolled_back` is the
+ * honest default for every non-success exit path that is not a refusal: the
+ * loop restores its git snapshot on the way out, so "the run failed" and "the
+ * tree is back where it started" are the same fact.
+ */
+export function runStatus(res: RunResult, dryRun: boolean): 'committed' | 'rolled_back' | 'refused' | 'dry_run' {
+  if (res.outcome === 'refused') return 'refused';
+  if (res.outcome === 'success') return dryRun ? 'dry_run' : 'committed';
+  return 'rolled_back';
+}
+
+export interface ServerOptions {
+  repoRoot: string;
+}
+
+/**
+ * Build the server and register the tools. Exported separately from
+ * `startMcpServer` so tests can drive the tool surface without a transport.
+ */
+export function createMcpServer(opts: ServerOptions): McpServer {
+  const { repoRoot } = opts;
+  const locks = new RepoLocks();
+
+  const server = new McpServer(
+    { name: 'copperhead', version: MCP_PROTOCOL_VERSION },
+    {
+      instructions:
+        'EXPERIMENTAL, UNSTABLE SURFACE: tool names, inputs and result shapes may change in any release. ' +
+        'Use these tools to change or verify a KiCad project instead of editing .kicad_sch / .kicad_pcb files ' +
+        'directly. Every mutation runs a spec-gated, verified, rollback-on-failure pipeline; editing the files ' +
+        'yourself bypasses all of it.',
+    },
+  );
+
+  const toMcp = (result: ToolResult): { content: { type: 'text'; text: string }[]; isError?: boolean } => ({
+    content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+    ...(result.ok ? {} : { isError: true }),
+  });
+
+  server.registerTool(
+    'copperhead_check',
+    {
+      title: 'Verify the KiCad project',
+      description:
+        'Run ERC, DRC, doc-drift and spec validation on the project. Makes no model call and no network call, ' +
+        'and changes nothing. Safe to call at any time, including concurrently.',
+      inputSchema: {},
+      _meta: { schemaVersion: TOOL_SCHEMA_VERSIONS.copperhead_check },
+    },
+    async () => {
+      const kicad = await requireKicad();
+      if ('error' in kicad) return toMcp(kicad.error);
+      try {
+        const res = await runCheck(repoRoot, (s) => {
+          note(s);
+        });
+        return toMcp(
+          seal({
+            ok: res.ok,
+            summary: res.ok ? 'check passed' : 'check found violations',
+            viewHint: 'diagnostic',
+            data: res,
+          }),
+        );
+      } catch (err) {
+        return toMcp(failure('exception', (err as Error).message));
+      }
+    },
+  );
+
+  server.registerTool(
+    'copperhead_doctor',
+    {
+      title: 'Check that this host can run copperhead',
+      description:
+        'Probe the environment copperhead needs: node, kicad-cli, git, openspec, and whether a model credential ' +
+        'resolves. Makes no model call and no network call, and changes nothing. Call this first when another ' +
+        'tool reports that something is unavailable.',
+      inputSchema: {},
+      _meta: { schemaVersion: TOOL_SCHEMA_VERSIONS.copperhead_doctor },
+    },
+    async () => {
+      // Deliberately no requireKicad() preflight. A missing kicad-cli is the
+      // single most likely thing a host needs told about, and gating this tool
+      // on it would make the diagnostic fail in exactly the case it exists for;
+      // runDoctor probes kicad-cli and reports it as a failed check instead.
+      try {
+        const report = await runDoctor({ repoRoot });
+        const failed = report.checks.filter((c) => c.status === 'fail');
+        return toMcp(
+          seal({
+            ok: report.ok,
+            summary: report.ok
+              ? 'environment is ready'
+              : `${failed.length} check(s) failed: ${failed.map((c) => c.name).join(', ')}`,
+            viewHint: 'diagnostic',
+            data: report,
+          }),
+        );
+      } catch (err) {
+        return toMcp(failure('exception', (err as Error).message));
+      }
+    },
+  );
+
+  server.registerTool(
+    'copperhead_init',
+    {
+      title: 'Scaffold design docs from the schematic',
+      description:
+        'Generate the docs/ memory scaffold from an existing schematic. Also installs a git pre-commit hook ' +
+        'that runs copperhead check before each commit. Idempotent, and refuses rather than overwriting docs ' +
+        'a human has hand-edited.',
+      inputSchema: {
+        path: z.string().optional().describe('where to look for KiCad files, relative to the repo root'),
+      },
+      _meta: { schemaVersion: TOOL_SCHEMA_VERSIONS.copperhead_init },
+    },
+    async ({ path: searchPath }) => {
+      const kicad = await requireKicad();
+      if ('error' in kicad) return toMcp(kicad.error);
+      if (!locks.tryAcquire(repoRoot)) {
+        return toMcp(failure('unavailable', 'another copperhead run is in progress for this repo; retry shortly'));
+      }
+      try {
+        const res = await runInit({
+          repoRoot,
+          ...(searchPath ? { searchPath } : {}),
+          force: false,
+          installHooks: true,
+        });
+        const refused = res.refused.length > 0;
+        return toMcp(
+          seal({
+            ok: !refused,
+            summary: refused
+              ? `init refused ${res.refused.length} hand-edited doc(s)`
+              : `init wrote ${res.created.length} file(s)`,
+            viewHint: 'mutation',
+            data: res,
+          }),
+        );
+      } catch (err) {
+        // A missing schematic is the user's situation, not a crash: report it
+        // as a validation failure so the host can ask for a path.
+        // A missing schematic and a path that escapes the repo are both the
+        // caller's situation, not a crash: report them as validation failures
+        // so the host can correct the input rather than retrying blindly.
+        const kind: ToolErrorKind =
+          err instanceof InitError || err instanceof SandboxError ? 'validation' : 'exception';
+        return toMcp(failure(kind, (err as Error).message));
+      } finally {
+        locks.release(repoRoot);
+      }
+    },
+  );
+
+  server.registerTool(
+    'copperhead_do',
+    {
+      title: 'Make a verified change to the project',
+      description:
+        'Run the full gated pipeline for a change request: propose, spec-gate, edit, verify with ERC/DRC, repair, ' +
+        'and commit — or roll back to the pre-run state if verification cannot be satisfied. This is the only way ' +
+        'to change the project. Long-running; progress is streamed. Requires an API key in the environment.',
+      inputSchema: {
+        request: z.string().min(1).describe('the change request, in natural language'),
+        dry_run: z.boolean().optional().describe('propose the change and write nothing'),
+      },
+      _meta: { schemaVersion: TOOL_SCHEMA_VERSIONS.copperhead_do },
+    },
+    async ({ request, dry_run: dryRun }, extra) => {
+      const kicad = await requireKicad();
+      if ('error' in kicad) return toMcp(kicad.error);
+      const resolved = await resolveModelOrFail(repoRoot);
+      if ('error' in resolved) return toMcp(resolved.error);
+      if (!locks.tryAcquire(repoRoot)) {
+        return toMcp(failure('unavailable', 'another copperhead run is in progress for this repo; retry shortly'));
+      }
+      const progressToken = extra?._meta?.progressToken;
+      const sink: ProgressSink = (update): void => {
+        if (progressToken === undefined) return;
+        void extra
+          ?.sendNotification({
+            method: 'notifications/progress',
+            params: { progressToken, progress: update.progress, message: update.message },
+          })
+          .catch(() => {
+            // A host that stopped listening must not fail the run.
+          });
+      };
+      try {
+        const res = await runAgentLoop({
+          repoRoot,
+          request,
+          model: resolved.model,
+          // allowDirty is deliberately not exposed: it is a safety rail, and a
+          // tool input that switches a rail off is a rail a host can bypass.
+          allowDirty: false,
+          dryRun: dryRun ?? false,
+          // No confirm callback and no budget-extension prompt: there is no
+          // human on this transport, so the loop must fail rather than block.
+          interactive: false,
+          renderer: mcpRenderer(sink),
+          meta: {
+            command: 'do',
+            modelSource: resolved.source,
+            version: COPPERHEAD_VERSION,
+            kicadCliVersion: kicad.version,
+          },
+        });
+        const status = runStatus(res, dryRun ?? false);
+        return toMcp(
+          seal({
+            // A rollback is a successful tool call whose result says the run
+            // did not land (design D6). Only `refused` is reported as not-ok,
+            // because that is the pipeline declining rather than failing.
+            ok: status !== 'refused',
+            summary: `${status}: ${res.summary}`,
+            viewHint: 'mutation',
+            data: {
+              status,
+              commit: res.commit,
+              filesTouched: res.filesTouched,
+              transcriptDir: res.transcriptDir,
+              exitPath: res.exitPath,
+              stats: res.stats,
+            },
+          }),
+        );
+      } catch (err) {
+        return toMcp(failure('exception', (err as Error).message));
+      } finally {
+        locks.release(repoRoot);
+      }
+    },
+  );
+
+  server.registerTool(
+    'copperhead_sync',
+    {
+      title: 'Verify design-state consistency, and optionally resolve drift',
+      description:
+        'Run the deterministic consistency check across docs, constraints and the KiCad files. With resolve=true, ' +
+        'additionally run the gated loop to fix the drift it found. Requirement violations are always reported and ' +
+        'never auto-resolved — those are for a human. resolve=true requires an API key in the environment.',
+      inputSchema: {
+        resolve: z.boolean().optional().describe('run the LLM resolve phase for resolvable drift'),
+      },
+      _meta: { schemaVersion: TOOL_SCHEMA_VERSIONS.copperhead_sync },
+    },
+    async ({ resolve }, extra) => {
+      const kicad = await requireKicad();
+      if ('error' in kicad) return toMcp(kicad.error);
+      let report;
+      try {
+        report = await syncVerify(repoRoot);
+      } catch (err) {
+        return toMcp(failure('exception', (err as Error).message));
+      }
+      const verdict = (summary: string, ok = true): ToolResult =>
+        seal({ ok, summary, viewHint: resolve ? 'mutation' : 'diagnostic', data: report });
+
+      if (!resolve) return toMcp(verdict(formatSyncReport(report)));
+
+      // Truth precedence (design D14): a requirement violation is never
+      // silently resolved, so the resolve phase does not start when one exists.
+      if (report.violations.length) {
+        return toMcp(
+          verdict(
+            `${report.violations.length} requirement violation(s) found; these are never auto-resolved. ` +
+              `Resolve them by hand or change the requirement.\n\n${formatSyncReport(report)}`,
+            false,
+          ),
+        );
+      }
+      if (!report.resolvable.length) return toMcp(verdict('design state is consistent; nothing to resolve'));
+
+      const resolved = await resolveModelOrFail(repoRoot);
+      if ('error' in resolved) return toMcp(resolved.error);
+      if (!locks.tryAcquire(repoRoot)) {
+        return toMcp(failure('unavailable', 'another copperhead run is in progress for this repo; retry shortly'));
+      }
+      // The report above was computed before the lock was held, so another run
+      // may have rewritten the tree in between. Re-verify now that nothing else
+      // can move, rather than asking the loop to fix drift that is already gone.
+      const fresh = await syncVerify(repoRoot);
+      if (fresh.violations.length || !fresh.resolvable.length) {
+        locks.release(repoRoot);
+        return toMcp(
+          seal({
+            ok: !fresh.violations.length,
+            summary: fresh.violations.length
+              ? `${fresh.violations.length} requirement violation(s) found; these are never auto-resolved.`
+              : 'design state is consistent; nothing to resolve',
+            viewHint: 'diagnostic',
+            data: fresh,
+          }),
+        );
+      }
+      const progressToken = extra?._meta?.progressToken;
+      const sink: ProgressSink = (update): void => {
+        if (progressToken === undefined) return;
+        void extra
+          ?.sendNotification({
+            method: 'notifications/progress',
+            params: { progressToken, progress: update.progress, message: update.message },
+          })
+          .catch(() => {
+            // A host that stopped listening must not fail the run.
+          });
+      };
+      try {
+        const res = await syncResolve(
+          repoRoot,
+          fresh,
+          resolved.model,
+          (s) => {
+            note(s);
+          },
+          {
+            renderer: mcpRenderer(sink),
+            meta: {
+              command: 'sync',
+              modelSource: resolved.source,
+              version: COPPERHEAD_VERSION,
+              kicadCliVersion: kicad.version,
+            },
+          },
+        );
+        return toMcp(
+          seal({
+            ok: res.ok,
+            summary: res.ok ? 'drift resolved and verified' : `resolve did not land: ${res.run.summary}`,
+            viewHint: 'mutation',
+            data: {
+              resolved: res.ok,
+              report: fresh,
+              commit: res.run.commit,
+              filesTouched: res.run.filesTouched,
+              transcriptDir: res.run.transcriptDir,
+              exitPath: res.run.exitPath,
+            },
+          }),
+        );
+      } catch (err) {
+        return toMcp(failure('exception', (err as Error).message));
+      } finally {
+        locks.release(repoRoot);
+      }
+    },
+  );
+
+  return server;
+}
+
+/** Start the server on stdio and serve until the host closes the transport. */
+export async function startMcpServer(opts: ServerOptions): Promise<void> {
+  if (!existsSync(opts.repoRoot)) {
+    throw new Error(`repo not found: ${opts.repoRoot}`);
+  }
+  const server = createMcpServer(opts);
+  note(
+    `copperhead mcp ${MCP_PROTOCOL_VERSION} (EXPERIMENTAL — unstable surface: tool names, inputs and results may ` +
+      `change in any release)`,
+  );
+  note(`repo: ${opts.repoRoot}`);
+  await server.connect(new StdioServerTransport());
+}