@czap/mcp-server 0.1.0

package/src/http.ts

@@ -0,0 +1,78 @@
+/**
+ * MCP HTTP transport — POST /, body is a JSON-RPC 2.0 request.
+ * Pure JSON-RPC handler logic lives here. The Node `createServer` +
+ * `listen` + `SIGINT`-await bootstrap lives in `./http-server.ts`,
+ * excluded from coverage because Windows can't deliver SIGINT to
+ * spawned subprocesses cleanly.
+ *
+ * Routes incoming bodies through `JsonRpcServer.parse` for the same
+ * conformance properties as the stdio transport: parse errors → -32700,
+ * notifications produce no body, batches handled per §6.
+ *
+ * @module
+ */
+
+import { dispatch } from './dispatch.js';
+import {
+  JsonRpcServer,
+  type JsonRpcResponse,
+  type ParseOutcome,
+  errorResponse,
+  ParseError,
+  InvalidRequest,
+} from './jsonrpc.js';
+
+/**
+ * Resolve a parse outcome to its wire response, or `null` if the spec
+ * requires no response (notification, or pure-notification batch).
+ *
+ * Exported so unit tests can exercise every branch without spinning up a
+ * real HTTP server (Windows can't deliver SIGINT to subprocess for the
+ * full integration path).
+ */
+export async function respond(
+  outcome: ParseOutcome,
+): Promise<JsonRpcResponse | readonly JsonRpcResponse[] | null> {
+  switch (outcome.kind) {
+    case 'parse-error':
+      return errorResponse(null, ParseError, 'Parse error');
+    case 'invalid-request':
+      return errorResponse(outcome.id, InvalidRequest, 'Invalid Request');
+    case 'notification':
+      await dispatch(outcome.message);
+      return null;
+    case 'request':
+      return dispatch(outcome.message);
+    case 'batch': {
+      const responses: JsonRpcResponse[] = [];
+      for (const sub of outcome.outcomes) {
+        const r = await respond(sub);
+        if (r === null) continue;
+        if (Array.isArray(r)) responses.push(...r);
+        else responses.push(r as JsonRpcResponse);
+      }
+      return responses.length > 0 ? responses : null;
+    }
+  }
+}
+
+/**
+ * Pure wire handler — accepts a JSON-RPC body string, returns the response
+ * envelope (or null for notification-only batches). Drives the HTTP server's
+ * request path; extracted so unit tests cover every parse-outcome branch
+ * without spawning a server process.
+ */
+export async function handleRequest(
+  body: string,
+): Promise<JsonRpcResponse | readonly JsonRpcResponse[] | null> {
+  const outcome = JsonRpcServer.parse(body);
+  return respond(outcome);
+}
+
+// Re-export the bootstrap so callers (start.ts) can keep using `import { runHttp } from './http.js'`.
+// The bootstrap module also installs a top-level direct-invoke guard for
+// the integration spawn entrypoint (`tsx packages/mcp-server/src/http.ts ...`).
+// We import that module for its side effect so the spawn keeps working.
+import './http-server.js';
+
+export { runHttp } from './http-server.js';

package/src/index.ts

@@ -0,0 +1,31 @@
+/** `@czap/mcp-server` — MCP bridge for **LiteShip**; forwards tools to the `czap` CLI + capsule factory. */
+
+export { start } from './start.js';
+export type { StartOpts } from './start.js';
+export { listTools, dispatchToolCall, dispatch } from './dispatch.js';
+export type { McpToolCall, McpToolResult } from './dispatch.js';
+export { runStdio } from './stdio.js';
+export { runHttp } from './http.js';
+
+// JSON-RPC 2.0 kernel — reusable beyond MCP.
+export {
+  JsonRpcServer,
+  jsonRpcServerCapsule,
+  parse,
+  errorResponse,
+  successResponse,
+  ParseError,
+  InvalidRequest,
+  MethodNotFound,
+  InvalidParams,
+  InternalError,
+} from './jsonrpc.js';
+export type {
+  JsonRpcId,
+  JsonRpcRequest,
+  JsonRpcNotification,
+  JsonRpcResponse,
+  JsonRpcSuccess,
+  JsonRpcErrorResponse,
+  ParseOutcome,
+} from './jsonrpc.js';

package/src/jsonrpc.ts

@@ -0,0 +1,243 @@
+/**
+ * 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';
+
+// ---------- JSON-RPC 2.0 types (wire-shape) ----------
+
+/** Per §4: `id` is string, number, or null. Absent = notification. */
+export type JsonRpcId = string | number | null;
+
+/** A JSON-RPC 2.0 request (has `id`). */
+export interface JsonRpcRequest {
+  readonly jsonrpc: '2.0';
+  readonly id: JsonRpcId;
+  readonly method: string;
+  readonly params?: readonly unknown[] | Record<string, unknown>;
+}
+
+/** A JSON-RPC 2.0 notification (no `id`). Per §4.1 MUST NOT be responded to. */
+export interface JsonRpcNotification {
+  readonly jsonrpc: '2.0';
+  readonly method: string;
+  readonly params?: readonly unknown[] | Record<string, unknown>;
+}
+
+/** Successful response per §5. */
+export interface JsonRpcSuccess {
+  readonly jsonrpc: '2.0';
+  readonly id: JsonRpcId;
+  readonly result: unknown;
+}
+
+/** Error response per §5 + §5.1. */
+export interface JsonRpcErrorResponse {
+  readonly jsonrpc: '2.0';
+  readonly id: JsonRpcId;
+  readonly error: { readonly code: number; readonly message: string; readonly data?: unknown };
+}
+
+/** Either a success or error response. */
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcErrorResponse;
+
+// ---------- Standard error codes (§5.1) ----------
+
+export const ParseError = -32700 as const;
+export const InvalidRequest = -32600 as const;
+export const MethodNotFound = -32601 as const;
+export const InvalidParams = -32602 as const;
+export const InternalError = -32603 as const;
+
+// ---------- Parser output classification ----------
+
+/** Discriminated union of every parse outcome the kernel produces. */
+export type ParseOutcome =
+  | { readonly kind: 'request'; readonly message: JsonRpcRequest }
+  | { readonly kind: 'notification'; readonly message: JsonRpcNotification }
+  | { readonly kind: 'batch'; readonly outcomes: readonly ParseOutcome[] }
+  | { readonly kind: 'parse-error' }
+  | { readonly kind: 'invalid-request'; readonly id: JsonRpcId };
+
+/**
+ * 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: string): ParseOutcome {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(line);
+  } catch {
+    const parseFailure: ParseOutcome = { 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: unknown): ParseOutcome {
+  if (typeof raw !== 'object' || raw === null) {
+    return { kind: 'invalid-request', id: null };
+  }
+  const obj = raw as Record<string, unknown>;
+  if (obj.jsonrpc !== '2.0' || typeof obj.method !== 'string') {
+    const id =
+      typeof obj.id === 'string' || typeof obj.id === 'number' || obj.id === null
+        ? (obj.id as JsonRpcId)
+        : null;
+    return { kind: 'invalid-request', id };
+  }
+  if (!('id' in obj) || obj.id === undefined) {
+    return { kind: 'notification', message: obj as unknown as JsonRpcNotification };
+  }
+  return { kind: 'request', message: obj as unknown as JsonRpcRequest };
+}
+
+/** Construct a -32700 / -32600 / -32601 / -32602 / -32603 error response. */
+function _errorResponse(
+  id: JsonRpcId,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcErrorResponse {
+  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: JsonRpcId, result: unknown): JsonRpcSuccess {
+  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: string, _output): boolean => {
+        // 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: string, _output): boolean => {
+        // 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: unknown;
+        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 as Record<string, unknown>;
+        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: string): { kind: string } => _parse(input),
+});
+
+// ---------- Namespace surface (ADR-0001) ----------
+
+/** Namespaced public surface of the kernel. */
+export const JsonRpcServer = {
+  parse: _parse,
+  errorResponse: _errorResponse,
+  successResponse: _successResponse,
+} as const;
+
+export declare namespace JsonRpcServer {
+  /** Discriminated parse outcome. */
+  export type Outcome = ParseOutcome;
+  /** Wire-shape request (§4). */
+  export type Request = JsonRpcRequest;
+  /** Wire-shape notification (§4.1). */
+  export type Notification = JsonRpcNotification;
+  /** Wire-shape response (§5). */
+  export type Response = JsonRpcResponse;
+  /** Wire-shape success response. */
+  export type Success = JsonRpcSuccess;
+  /** Wire-shape error response. */
+  export type Error = JsonRpcErrorResponse;
+  /** Id type per §4. */
+  export type Id = JsonRpcId;
+}

package/src/start.ts

@@ -0,0 +1,23 @@
+/**
+ * start — pick an MCP transport. Default is stdio; pass `{ http: ':3838' }`
+ * to bind HTTP instead.
+ *
+ * @module
+ */
+
+import { runStdio } from './stdio.js';
+
+/** Options for `start`. */
+export interface StartOpts {
+  readonly http?: string;
+}
+
+/** Start the MCP server on the requested transport. */
+export async function start(opts: StartOpts = {}): Promise<void> {
+  if (opts.http !== undefined) {
+    const { runHttp } = await import('./http.js');
+    await runHttp(opts.http);
+    return;
+  }
+  await runStdio();
+}

package/src/stdio-server.ts

@@ -0,0 +1,19 @@
+/**
+ * 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: unknown) => {
+    process.stderr.write(JSON.stringify({ error: String(err) }) + '\n');
+    process.exit(1);
+  });
+}

package/src/stdio.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 type { Readable, Writable } from 'node:stream';
+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: string): Promise<string | null> {
+  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: Readable = process.stdin,
+  output: Writable = process.stdout,
+): Promise<void> {
+  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';