@czap/mcp-server 0.1.0

package/dist/jsonrpc.js

@@ -0,0 +1,169 @@
+/**
+ * JsonRpcServer — framework-free JSON-RPC 2.0 kernel.
+ *
+ * Parses incoming wire bytes, classifies them as Request | Notification |
+ * Batch | InvalidRequest | ParseError, and produces responses (or null
+ * for notifications, which MUST NOT receive a response per §4.1).
+ *
+ * Exposed as a `pureTransform` arm capsule `mcp.jsonrpc-server` so it
+ * appears in the manifest and can be reused by future JSON-RPC surfaces
+ * beyond MCP.
+ *
+ * Conformance: JSON-RPC 2.0 specification (https://www.jsonrpc.org/specification).
+ *   §3 — `jsonrpc: "2.0"` required.
+ *   §4 — Request vs Notification distinguished by presence of `id`.
+ *   §4.1 — A Notification MUST NOT receive a Response.
+ *   §4.2 — Parse errors MUST emit a Response with code -32700, id null.
+ *   §5 — Response is `result` XOR `error`.
+ *   §5.1 — Standard error codes.
+ *   §6 — Batch: array of requests/notifications. Empty array → -32600.
+ *
+ * @module
+ */
+import { Schema } from 'effect';
+import { defineCapsule } from '@czap/core';
+// ---------- Standard error codes (§5.1) ----------
+export const ParseError = -32700;
+export const InvalidRequest = -32600;
+export const MethodNotFound = -32601;
+export const InvalidParams = -32602;
+export const InternalError = -32603;
+/**
+ * Parse a single JSON-RPC line. Distinguishes:
+ * - parse failure → `parse-error` (§4.2)
+ * - empty array → `invalid-request` per §6
+ * - non-object scalar → `invalid-request`
+ * - object with bad `jsonrpc`/`method` → `invalid-request`
+ * - object with `id` present → `request`
+ * - object without `id` → `notification`
+ * - non-empty array → `batch` with per-element outcomes
+ *
+ * Note (§4 id-vs-notification): `"id": null` is a Request with id null,
+ * not a notification. Only an absent id field marks a notification.
+ */
+function _parse(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        const parseFailure = { kind: 'parse-error' };
+        return parseFailure;
+    }
+    if (Array.isArray(raw)) {
+        if (raw.length === 0)
+            return { kind: 'invalid-request', id: null };
+        return { kind: 'batch', outcomes: raw.map(_classify) };
+    }
+    return _classify(raw);
+}
+function _classify(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return { kind: 'invalid-request', id: null };
+    }
+    const obj = raw;
+    if (obj.jsonrpc !== '2.0' || typeof obj.method !== 'string') {
+        const id = typeof obj.id === 'string' || typeof obj.id === 'number' || obj.id === null
+            ? obj.id
+            : null;
+        return { kind: 'invalid-request', id };
+    }
+    if (!('id' in obj) || obj.id === undefined) {
+        return { kind: 'notification', message: obj };
+    }
+    return { kind: 'request', message: obj };
+}
+/** Construct a -32700 / -32600 / -32601 / -32602 / -32603 error response. */
+function _errorResponse(id, code, message, data) {
+    return data !== undefined
+        ? { jsonrpc: '2.0', id, error: { code, message, data } }
+        : { jsonrpc: '2.0', id, error: { code, message } };
+}
+/** Construct a success response (§5). */
+function _successResponse(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+// Re-export pure functions for direct import sites.
+export const parse = _parse;
+export const errorResponse = _errorResponse;
+export const successResponse = _successResponse;
+// ---------- Capsule declaration (pureTransform arm) ----------
+//
+// Schemas are deliberately structural: the harness uses them to drive
+// `Schema.decodeUnknownEffect` against `fc.anything()` inputs, so we
+// only need to express enough shape for it to filter the property test.
+const JsonRpcInputSchema = Schema.String;
+const ParseOutcomeKindSchema = Schema.Union([
+    Schema.Literal('request'),
+    Schema.Literal('notification'),
+    Schema.Literal('batch'),
+    Schema.Literal('parse-error'),
+    Schema.Literal('invalid-request'),
+]);
+const ParseOutcomeSchema = Schema.Struct({ kind: ParseOutcomeKindSchema });
+/**
+ * Capsule definition for the kernel — placed in the catalog under the
+ * `pureTransform` arm so the factory compiler emits a generated test +
+ * bench pair and the manifest tracks the kernel's content address.
+ */
+export const jsonRpcServerCapsule = defineCapsule({
+    _kind: 'pureTransform',
+    name: 'mcp.jsonrpc-server',
+    site: ['node', 'browser'],
+    capabilities: { reads: [], writes: [] },
+    input: JsonRpcInputSchema,
+    output: ParseOutcomeSchema,
+    budgets: { p95Ms: 1, allocClass: 'bounded' },
+    invariants: [
+        {
+            name: 'malformed-json-yields-parse-error',
+            check: (input, _output) => {
+                // Behavioral invariant: an input that is NOT valid JSON MUST be
+                // classified as parse-error. The TS union proves syntactic
+                // shape; this proves the parser actually rejects bad input.
+                try {
+                    JSON.parse(input);
+                    return true; // valid JSON — not the negative case we're testing
+                }
+                catch {
+                    return _parse(input).kind === 'parse-error';
+                }
+            },
+            message: 'inputs that JSON.parse rejects must yield kind: parse-error',
+        },
+        {
+            name: 'absent-id-classifies-as-notification',
+            check: (input, _output) => {
+                // Behavioral invariant: a well-formed object with jsonrpc:'2.0'
+                // and method:string but NO id field MUST be a notification, not
+                // a request. This is the §4.1 distinction the strike force flagged.
+                let obj;
+                try {
+                    obj = JSON.parse(input);
+                }
+                catch {
+                    const skipAbsentIdCase = true;
+                    return skipAbsentIdCase;
+                }
+                if (typeof obj !== 'object' || obj === null || Array.isArray(obj))
+                    return true;
+                const o = obj;
+                if (o.jsonrpc !== '2.0' || typeof o.method !== 'string')
+                    return true;
+                if ('id' in o && o.id !== undefined)
+                    return true; // request, not the test case
+                return _parse(input).kind === 'notification';
+            },
+            message: 'well-formed messages without an id field must classify as notifications (§4.1)',
+        },
+    ],
+    run: (input) => _parse(input),
+});
+// ---------- Namespace surface (ADR-0001) ----------
+/** Namespaced public surface of the kernel. */
+export const JsonRpcServer = {
+    parse: _parse,
+    errorResponse: _errorResponse,
+    successResponse: _successResponse,
+};
+//# sourceMappingURL=jsonrpc.js.map

package/dist/jsonrpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.js","sourceRoot":"","sources":["../src/jsonrpc.ts"],"names":[],"mappings":"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"}

package/dist/start.d.ts

@@ -0,0 +1,13 @@
+/**
+ * start — pick an MCP transport. Default is stdio; pass `{ http: ':3838' }`
+ * to bind HTTP instead.
+ *
+ * @module
+ */
+/** Options for `start`. */
+export interface StartOpts {
+    readonly http?: string;
+}
+/** Start the MCP server on the requested transport. */
+export declare function start(opts?: StartOpts): Promise<void>;
+//# sourceMappingURL=start.d.ts.map

package/dist/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,2BAA2B;AAC3B,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,uDAAuD;AACvD,wBAAsB,KAAK,CAAC,IAAI,GAAE,SAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/D"}

package/dist/start.js

@@ -0,0 +1,17 @@
+/**
+ * start — pick an MCP transport. Default is stdio; pass `{ http: ':3838' }`
+ * to bind HTTP instead.
+ *
+ * @module
+ */
+import { runStdio } from './stdio.js';
+/** Start the MCP server on the requested transport. */
+export async function start(opts = {}) {
+    if (opts.http !== undefined) {
+        const { runHttp } = await import('./http.js');
+        await runHttp(opts.http);
+        return;
+    }
+    await runStdio();
+}
+//# sourceMappingURL=start.js.map

package/dist/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAOtC,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAAkB,EAAE;IAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QAC9C,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,EAAE,CAAC;AACnB,CAAC"}

package/dist/stdio-server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP stdio server bootstrap. Provides the tsx direct-invoke entrypoint
+ * for `tests/integration/mcp/stdio-spawn.test.ts`. Excluded from
+ * coverage because the only way to exercise this guard is by spawning
+ * the script as the entrypoint of a Node process — which is what the
+ * integration test does. The pure read-line-write loop lives in
+ * `stdio.ts` (`runStdio` / `processLine`) and is fully unit-tested.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=stdio-server.d.ts.map

package/dist/stdio-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-server.d.ts","sourceRoot":"","sources":["../src/stdio-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/stdio-server.js

@@ -0,0 +1,18 @@
+/**
+ * MCP stdio server bootstrap. Provides the tsx direct-invoke entrypoint
+ * for `tests/integration/mcp/stdio-spawn.test.ts`. Excluded from
+ * coverage because the only way to exercise this guard is by spawning
+ * the script as the entrypoint of a Node process — which is what the
+ * integration test does. The pure read-line-write loop lives in
+ * `stdio.ts` (`runStdio` / `processLine`) and is fully unit-tested.
+ *
+ * @module
+ */
+import { runStdio } from './stdio.js';
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('stdio-server.ts') || process.argv[1]?.endsWith('stdio.ts')) {
+    runStdio().catch((err) => {
+        process.stderr.write(JSON.stringify({ error: String(err) }) + '\n');
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=stdio-server.js.map

package/dist/stdio-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-server.js","sourceRoot":"","sources":["../src/stdio-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,iBAAiB,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;IAC7I,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/stdio.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP stdio server — reads JSON-RPC 2.0 framed messages line-by-line from
+ * stdin, writes responses to stdout. Routes every line through
+ * `JsonRpcServer.parse` so parse errors emit -32700 (was silently dropped)
+ * and notifications produce no response (§4.1).
+ *
+ * @module
+ */
+import type { Readable, Writable } from 'node:stream';
+/**
+ * Process a single JSON-RPC stdio line and return the wire payload (a
+ * JSON-encoded string) or `null` when no response should be emitted
+ * (notification or pure-notification batch). Empty/whitespace-only lines
+ * are also `null` so the stdio loop can skip them silently.
+ *
+ * Exported so unit tests cover the exact line-handling logic without
+ * spinning up a child process and pumping stdin.
+ */
+export declare function processLine(line: string): Promise<string | null>;
+/**
+ * Run the MCP stdio loop until the input stream closes. Defaults to
+ * `process.stdin` / `process.stdout` so the production CLI bootstrap
+ * stays a one-liner (`runStdio()`); tests inject a pre-populated
+ * Readable + a sink Writable to exercise the full read-line-write loop
+ * without spawning a child process.
+ */
+export declare function runStdio(input?: Readable, output?: Writable): Promise<void>;
+import './stdio-server.js';
+//# sourceMappingURL=stdio.d.ts.map

package/dist/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGtD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKtE;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,GAAE,QAAwB,EAC/B,MAAM,GAAE,QAAyB,GAChC,OAAO,CAAC,IAAI,CAAC,CAQf;AAMD,OAAO,mBAAmB,CAAC"}

package/dist/stdio.js

@@ -0,0 +1,49 @@
+/**
+ * MCP stdio server — reads JSON-RPC 2.0 framed messages line-by-line from
+ * stdin, writes responses to stdout. Routes every line through
+ * `JsonRpcServer.parse` so parse errors emit -32700 (was silently dropped)
+ * and notifications produce no response (§4.1).
+ *
+ * @module
+ */
+import { createInterface } from 'node:readline/promises';
+import { handleRequest } from './http.js';
+/**
+ * Process a single JSON-RPC stdio line and return the wire payload (a
+ * JSON-encoded string) or `null` when no response should be emitted
+ * (notification or pure-notification batch). Empty/whitespace-only lines
+ * are also `null` so the stdio loop can skip them silently.
+ *
+ * Exported so unit tests cover the exact line-handling logic without
+ * spinning up a child process and pumping stdin.
+ */
+export async function processLine(line) {
+    if (!line.trim())
+        return null;
+    const response = await handleRequest(line);
+    if (response === null)
+        return null;
+    return JSON.stringify(response);
+}
+/**
+ * Run the MCP stdio loop until the input stream closes. Defaults to
+ * `process.stdin` / `process.stdout` so the production CLI bootstrap
+ * stays a one-liner (`runStdio()`); tests inject a pre-populated
+ * Readable + a sink Writable to exercise the full read-line-write loop
+ * without spawning a child process.
+ */
+export async function runStdio(input = process.stdin, output = process.stdout) {
+    const rl = createInterface({ input });
+    for await (const line of rl) {
+        const wire = await processLine(line);
+        if (wire !== null) {
+            output.write(wire + '\n');
+        }
+    }
+}
+// Side-effect import installs the tsx direct-invoke guard so the integration
+// spawn (`tsx packages/mcp-server/src/stdio.ts`) keeps working. Bootstrap
+// lives in `./stdio-server.ts` because Windows-spawn coverage can't be
+// merged back through c8 ignore (source-mapped TS line numbers don't match).
+import './stdio-server.js';
+//# sourceMappingURL=stdio.js.map

package/dist/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAkB,OAAO,CAAC,KAAK,EAC/B,SAAmB,OAAO,CAAC,MAAM;IAEjC,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACtC,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,0EAA0E;AAC1E,uEAAuE;AACvE,6EAA6E;AAC7E,OAAO,mBAAmB,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@czap/mcp-server",
+  "version": "0.1.0",
+  "description": "Thin MCP server over czap's capsule factory dispatch",
+  "license": "MIT",
+  "author": "Eassa Ayoub <eassa@heyoub.dev>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heyoub/LiteShip",
+    "directory": "packages/mcp-server"
+  },
+  "bugs": "https://github.com/heyoub/LiteShip/issues",
+  "homepage": "https://github.com/heyoub/LiteShip#readme",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "czap",
+    "mcp",
+    "model-context-protocol",
+    "ai-tooling",
+    "capsule-factory",
+    "typescript"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "development": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@czap/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "effect": ">=4.0.0-beta.32 <5",
+    "@czap/cli": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/czap-cli-shim.d.ts

@@ -0,0 +1,3 @@
+declare module '@czap/cli' {
+  export function run(argv: readonly string[]): Promise<number>;
+}

package/src/dispatch.ts

@@ -0,0 +1,177 @@
+/**
+ * MCP tool dispatch — maps tools/call params to czap CLI command
+ * executions. Captures CLI stdout and returns it as MCP text content.
+ *
+ * Entry point `dispatch` accepts a typed JSON-RPC `Request | Notification`
+ * (post-`JsonRpcServer.parse` classification) and produces a
+ * `JsonRpcResponse | null`. `null` is returned for notifications: per
+ * JSON-RPC 2.0 §4.1 the server MUST NOT send a response for them.
+ *
+ * `dispatchToolCall` remains exported for tests that exercise the CLI
+ * dispatch path directly without going through the JSON-RPC envelope.
+ *
+ * @module
+ */
+
+import {
+  type JsonRpcNotification,
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+  errorResponse,
+  successResponse,
+  MethodNotFound,
+  InvalidParams,
+  InternalError,
+} from './jsonrpc.js';
+
+/**
+ * Sentinel for invalid-params throws inside method invocations. Caught
+ * by `dispatch` and mapped to JSON-RPC 2.0 §5.1 code -32602 (the spec
+ * code for malformed parameters). Generic `Error`s remain -32603
+ * (Internal error).
+ */
+class InvalidParamsError extends Error {
+  constructor(message: string, readonly detail?: unknown) {
+    super(message);
+    this.name = 'InvalidParamsError';
+  }
+}
+
+type RunFn = (argv: readonly string[]) => Promise<number>;
+
+let cachedRun: RunFn | undefined;
+
+/** Lazy-load `@czap/cli` so `@czap/mcp-server` does not declare a package dependency cycle. */
+async function getRun(): Promise<RunFn> {
+  if (!cachedRun) {
+    const mod = await import('@czap/cli');
+    cachedRun = mod.run;
+  }
+  return cachedRun;
+}
+
+/** Shape of an MCP tools/call parameter object. */
+export interface McpToolCall {
+  readonly name: string;
+  readonly arguments: Record<string, unknown>;
+}
+
+/** MCP tools/call result envelope. */
+export interface McpToolResult {
+  readonly content: ReadonlyArray<{ type: 'text'; text: string }>;
+  readonly isError: boolean;
+}
+
+/**
+ * Route a parsed JSON-RPC message to its method handler.
+ *
+ * Returns `null` for notifications (§4.1: notifications MUST NOT receive
+ * a response). For requests, returns either a success or an error
+ * response. Internal handler exceptions are caught and surfaced as
+ * `-32603 Internal error` per §5.1.
+ */
+export async function dispatch(
+  msg: JsonRpcRequest | JsonRpcNotification,
+): Promise<JsonRpcResponse | null> {
+  const isNotification = !('id' in msg);
+  const id = isNotification ? null : (msg as JsonRpcRequest).id;
+
+  try {
+    const result = await invoke(msg);
+    if (isNotification) return null;
+    if (result.kind === 'method-not-found') {
+      return errorResponse(id, MethodNotFound, 'method not found', { method: msg.method });
+    }
+    return successResponse(id, result.value);
+  } catch (err) {
+    if (isNotification) {
+      const notificationAck: null = null;
+      return notificationAck;
+    }
+    if (err instanceof InvalidParamsError) {
+      return errorResponse(id, InvalidParams, err.message, err.detail);
+    }
+    return errorResponse(id, InternalError, 'Internal error', { detail: String(err) });
+  }
+}
+
+/** Internal: dispatch result shape. */
+type InvokeResult =
+  | { readonly kind: 'ok'; readonly value: unknown }
+  | { readonly kind: 'method-not-found' };
+
+function ok(value: unknown): InvokeResult {
+  return { kind: 'ok', value };
+}
+
+async function invoke(msg: JsonRpcRequest | JsonRpcNotification): Promise<InvokeResult> {
+  switch (msg.method) {
+    case 'tools/list':
+      return ok({ tools: listTools() });
+    case 'tools/call': {
+      const params = msg.params as { name: string; arguments: Record<string, unknown> } | undefined;
+      if (!params || typeof params.name !== 'string') {
+        // Per §5.1, malformed params → -32602. InvalidParamsError sentinel
+        // is mapped to InvalidParams in dispatch's catch block.
+        throw new InvalidParamsError(
+          'tools/call requires { name: string, arguments: object }',
+          { received: params },
+        );
+      }
+      const result = await dispatchToolCall(params);
+      return ok(result);
+    }
+    default:
+      return { kind: 'method-not-found' };
+  }
+}
+
+/** Translate a tools/call into argv, run the CLI, capture stdout. */
+export async function dispatchToolCall(call: McpToolCall): Promise<McpToolResult> {
+  const args = buildArgv(call);
+  const originalWrite = process.stdout.write.bind(process.stdout);
+  let captured = '';
+  (process.stdout as unknown as { write: unknown }).write = ((chunk: string | Uint8Array) => {
+    captured += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString();
+    return true;
+  });
+  try {
+    const run = await getRun();
+    const code = await run(args);
+    return {
+      content: [{ type: 'text', text: captured.trim() }],
+      isError: code !== 0,
+    };
+  } finally {
+    (process.stdout as unknown as { write: typeof originalWrite }).write = originalWrite;
+  }
+}
+
+function buildArgv(call: McpToolCall): string[] {
+  const segments = call.name.split('.');
+  const args: string[] = [];
+  for (const [k, v] of Object.entries(call.arguments)) {
+    if (typeof v === 'boolean') {
+      if (v) args.push(`--${k}`);
+    } else {
+      args.push(`--${k}=${String(v)}`);
+    }
+  }
+  return [...segments, ...args];
+}
+
+/** Static list of MCP tools produced by czap's CLI. */
+export function listTools(): ReadonlyArray<{ name: string; description: string; inputSchema: object }> {
+  return [
+    { name: 'describe', description: 'Dump capsule catalog schema', inputSchema: { type: 'object', properties: { format: { type: 'string', enum: ['json', 'mcp'] } } } },
+    { name: 'scene.compile', description: 'Compile a scene capsule', inputSchema: { type: 'object', required: ['scene'], properties: { scene: { type: 'string' } } } },
+    { name: 'scene.render', description: 'Render scene to mp4', inputSchema: { type: 'object', required: ['scene', 'output'], properties: { scene: { type: 'string' }, output: { type: 'string' } } } },
+    { name: 'scene.verify', description: 'Run scene generated tests', inputSchema: { type: 'object', required: ['scene'], properties: { scene: { type: 'string' } } } },
+    { name: 'asset.analyze', description: 'Run cachedProjection on asset', inputSchema: { type: 'object', required: ['asset', 'projection'], properties: { asset: { type: 'string' }, projection: { type: 'string', enum: ['beat', 'onset', 'waveform'] } } } },
+    { name: 'asset.verify', description: 'Verify asset capsule', inputSchema: { type: 'object', required: ['asset'], properties: { asset: { type: 'string' } } } },
+    { name: 'capsule.inspect', description: 'Inspect a capsule manifest entry', inputSchema: { type: 'object', required: ['id'], properties: { id: { type: 'string' } } } },
+    { name: 'capsule.verify', description: 'Verify capsule generated tests', inputSchema: { type: 'object', required: ['id'], properties: { id: { type: 'string' } } } },
+    { name: 'capsule.list', description: 'List capsules filtered by kind', inputSchema: { type: 'object', properties: { kind: { type: 'string' } } } },
+    { name: 'gauntlet', description: 'Run the full gauntlet', inputSchema: { type: 'object', properties: { 'dry-run': { type: 'boolean' } } } },
+  ];
+}

package/src/http-server.ts

@@ -0,0 +1,69 @@
+/**
+ * MCP HTTP server bootstrap. The pure handler logic lives in `http.ts`
+ * (exported as `handleRequest` / `respond`). This module owns the
+ * Node http server lifecycle (createServer + listen + SIGINT-await) and
+ * is excluded from coverage because the bootstrap path can only be
+ * exercised by the integration spawn at tests/integration/mcp/http.test.ts —
+ * Windows can't deliver SIGINT to spawned subprocesses cleanly, so a
+ * unit test would hang.
+ *
+ * Splitting this out lets the rest of the transport stay in coverage with
+ * no `c8 ignore` annotations.
+ *
+ * @module
+ */
+
+import { createServer } from 'node:http';
+import { handleRequest } from './http.js';
+
+/** Run the MCP HTTP server bound to `bind` (e.g. ":3838" or "127.0.0.1:8080"). */
+export async function runHttp(bind: string): Promise<void> {
+  const m = bind.match(/^(?:([^:]+))?:(\d+)$/);
+  const host = m?.[1] ?? '127.0.0.1';
+  const port = Number(m?.[2] ?? bind);
+
+  const server = createServer(async (req, res) => {
+    if (req.method !== 'POST') { res.statusCode = 405; res.end(); return; }
+    let body = '';
+    for await (const chunk of req) body += String(chunk);
+
+    const response = await handleRequest(body);
+
+    res.setHeader('content-type', 'application/json');
+    if (response === null) {
+      // §4.1: notifications produce no body. Use 204 No Content.
+      res.statusCode = 204;
+      res.end();
+      return;
+    }
+    res.end(JSON.stringify(response));
+  });
+
+  await new Promise<void>((resolve) => server.listen(port, host, () => resolve()));
+  // Resolve the actual bound port — when callers pass :0 they want the
+  // ephemeral port the OS chose, not the literal 0 they requested.
+  const addr = server.address();
+  const boundPort = typeof addr === 'object' && addr ? addr.port : port;
+  process.stdout.write(
+    JSON.stringify({
+      status: 'ok', command: 'mcp',
+      transport: 'http',
+      url: `http://${host}:${boundPort}/`,
+    }) + '\n',
+  );
+
+  await new Promise<void>((resolve) => {
+    process.on('SIGINT', () => {
+      server.close();
+      resolve();
+    });
+  });
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('http-server.ts') || process.argv[1]?.endsWith('http.ts')) {
+  const bind = process.argv[2] ?? ':0';
+  runHttp(bind).catch((err: unknown) => {
+    process.stderr.write(JSON.stringify({ error: String(err) }) + '\n');
+    process.exit(1);
+  });
+}