@crediolabs/policy-builder-mcp 0.1.0

package/src/index.ts

@@ -0,0 +1,21 @@
+// apps/policy-builder-mcp/src/index.ts - public re-exports for the MCP server package.
+
+export {
+  RecordTransactionInputSchema,
+  RecordTransactionToolShape,
+  SynthesizePolicyInputSchema,
+  SynthesizePolicyMandateInputSchema,
+  SynthesizePolicyRecordingInputSchema,
+  SynthesizePolicyToolShape,
+} from './schemas.ts'
+export { createMcpServer, registerTools } from './server.ts'
+export type { McpToolError, McpToolResult } from './tools/result.ts'
+export { mcpErrorFromCore, mcpResultFromCore } from './tools/result.ts'
+export {
+  type RunRecordTransactionInput,
+  type RunSynthesizePolicyInput,
+  runRecordTransaction,
+  runSynthesizePolicy,
+} from './tools/run.ts'
+export { startHttpServer } from './transports/http.ts'
+export { startStdioServer } from './transports/stdio.ts'

package/src/schemas.ts

@@ -0,0 +1,249 @@
+// apps/policy-builder-mcp/src/schemas.ts
+//
+// Zod schemas mirroring the policy-synth core domain types. These are the
+// public input / output shapes exposed over MCP and the CLI. They are kept
+// hand-written (rather than derived) because the MCP SDK needs a runtime
+// Zod object at the transport boundary; a drift test asserts they stay in
+// step with the TS source of truth.
+//
+// i128 amounts and other large integers are carried as base-10 decimal strings
+// end-to-end (no JS number coercion). Networks are pinned to the same closed
+// set the core defines. The discriminated union on `source` exposes BOTH
+// synthesize_policy front-ends through a single tool input.
+
+import { z } from 'zod'
+
+/** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
+ *  installed on-chain, so reject it at the boundary (fail-closed). */
+const U32_MAX = 4294967295
+/** Upper bound on top-level invocations in a recorded transaction. A real
+ *  Stellar tx caps operations well below this; the bound stops a hand-crafted
+ *  payload from turning one request into an unbounded synthesis (DoS). */
+const MAX_INVOCATIONS = 512
+
+export const NetworkSchema = z.enum(['mainnet', 'testnet'])
+export type Network = z.infer<typeof NetworkSchema>
+
+/** ScVal subset - normalised subset the synth consumes. Mirrors
+ *  `ScVal` in packages/policy-synth/src/types.ts. */
+export const ScValSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.object({ type: z.literal('address'), value: z.string() }),
+    // i128 is SIGNED: real events carry negatives (e.g. a fee-adjustment/refund),
+    // so the recorder's own output must round-trip through this schema. u64/u32
+    // are unsigned and stay non-negative.
+    z.object({ type: z.literal('i128'), value: z.string().regex(/^-?[0-9]+$/) }),
+    z.object({ type: z.literal('u64'), value: z.string().regex(/^[0-9]+$/) }),
+    z.object({ type: z.literal('u32'), value: z.string().regex(/^[0-9]+$/) }),
+    z.object({ type: z.literal('symbol'), value: z.string() }),
+    z.object({ type: z.literal('vec'), value: z.array(ScValSchema) }),
+    z.object({ type: z.literal('bytes'), value: z.string() }),
+    z.object({ type: z.literal('other'), value: z.string() }),
+  ])
+)
+
+/** ContractInvocation mirrors the core. Annotated with an explicit
+ *  `z.ZodType<unknown>` (like ScValSchema above) so the self-referential
+ *  `subInvocations` field does not trip TS's circular type inference. */
+export const ContractInvocationSchema: z.ZodType<unknown> = z.object({
+  contract: z.string(),
+  fn: z.string(),
+  args: z.array(ScValSchema),
+  subInvocations: z.array(z.lazy(() => ContractInvocationSchema)),
+})
+
+export const TokenMovementSchema = z.object({
+  token: z.string(),
+  from: z.string(),
+  to: z.string(),
+  // The recorder reads the amount straight from the signed i128 event value
+  // (record/movements.ts readAmount), so a non-standard token that emits a
+  // negative transfer/mint/burn amount round-trips as a negative string. Mirror
+  // that here; the synth gate, not the wire schema, decides what to do with it.
+  amount: z.string().regex(/^-?[0-9]+$/),
+})
+
+export const OnChainEventSchema = z.object({
+  contract: z.string(),
+  topics: z.array(z.string()),
+  data: ScValSchema,
+})
+
+export const ParseConfidenceSchema = z.object({
+  overall: z.number().min(0).max(1),
+  knownContracts: z.array(z.string()),
+  unknownContracts: z.array(
+    z.object({
+      contract: z.string(),
+      reason: z.enum(['no-abi', 'version-mismatch', 'opaque-result']),
+    })
+  ),
+  opaqueScVals: z.array(z.object({ path: z.string(), type: z.string() })),
+  thresholdUsed: z.number().min(0).max(1),
+})
+
+/** RecordedTransaction mirrors the core RecordedTransaction. The output shape
+ *  is referenced by name in the tool result structured content; we deliberately
+ *  type it loosely (`z.unknown()`) on the success path so the core remains the
+ *  single source of truth for the wire payload. */
+export const RecordedTransactionSchema = z
+  .object({
+    network: NetworkSchema,
+    signers: z.array(z.string()),
+    invocations: z.array(ContractInvocationSchema).max(MAX_INVOCATIONS),
+    tokenMovements: z.array(TokenMovementSchema),
+    events: z.array(OnChainEventSchema),
+    authEntries: z.array(z.unknown()),
+    ledgerSequence: z.number().int().nonnegative(),
+    fetchedAt: z.number().int().nonnegative(),
+    parseConfidence: ParseConfidenceSchema,
+    sourceAccount: z.string(),
+  })
+  .passthrough()
+
+/** MandateSpec mirrors the core MandateSpec. The deterministic Mandate
+ *  front-end needs no parseConfidence; the tool adapter injects the full
+ *  confidence after synthesis so the orchestrator can compare. */
+export const MandateSpecSchema = z
+  .object({
+    chain: z.literal('stellar'),
+    contract: z.string(),
+    method: z.string().optional(),
+    spendingLimit: z
+      .object({
+        token: z.string(),
+        limit: z.string().regex(/^[0-9]+$/),
+        windowSeconds: z.number().int().positive(),
+      })
+      .optional(),
+    // A threshold of 0 means "0 approvals", which is not a real M-of-N gate.
+    approvalThreshold: z.number().int().positive().optional(),
+    recipients: z.array(z.string()).optional(),
+    expiry: z
+      .object({
+        validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+        validUntilUnixSeconds: z.number().int().positive().optional(),
+      })
+      .optional(),
+  })
+  .passthrough()
+
+/** ComposeUserResponses mirrors the core. */
+export const ComposeUserResponsesSchema = z
+  .object({
+    windowSeconds: z.number().int().positive().optional(),
+    validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+    limitAmount: z
+      .string()
+      .regex(/^[0-9]+$/)
+      .optional(),
+    invocationLimit: z.number().int().positive().optional(),
+  })
+  .passthrough()
+
+/** OzAdapterConfig - the per-network OZ built-in instance addresses. */
+export const OzAdapterConfigSchema = z.object({
+  network: NetworkSchema,
+  instances: z.object({
+    spending_limit: z.string(),
+    simple_threshold: z.string(),
+    weighted_threshold: z.string(),
+  }),
+})
+
+// ===== record_transaction =====
+
+export const RecordTransactionInputSchema = z
+  .object({
+    hash: z.string().min(1).optional(),
+    xdr: z.string().min(1).optional(),
+    network: NetworkSchema,
+    confidenceOverride: z.number().min(0).max(1).optional(),
+  })
+  .refine((v) => !(v.hash && v.xdr), {
+    message: 'provide exactly one of `hash` or `xdr`, not both',
+  })
+  .refine((v) => Boolean(v.hash) || Boolean(v.xdr), {
+    message: 'one of `hash` or `xdr` is required',
+  })
+export type RecordTransactionInput = z.infer<typeof RecordTransactionInputSchema>
+
+/** Flat ZodRawShape used for the MCP SDK tool registration. The body
+ *  re-validates against `RecordTransactionInputSchema` so the mutual-exclusion
+ *  rule still fires (the SDK does not invoke `.refine()` at registration time). */
+export const RecordTransactionToolShape = {
+  hash: z.string().min(1).optional(),
+  xdr: z.string().min(1).optional(),
+  network: NetworkSchema,
+  confidenceOverride: z.number().min(0).max(1).optional(),
+} as const
+
+// ===== synthesize_policy =====
+//
+// Discriminated union on `source` exposes BOTH front-ends through ONE tool.
+// - `source: 'mandate'` -> calls synthesizeFromMandate
+// - `source: 'recording'` -> calls synthesizeFromRecording
+//
+// The MCP SDK's `tool()` API only accepts a flat ZodRawShape (named
+// properties keyed by Zod schemas), so we ALSO export a flat shape used at
+// the transport boundary. The discriminated union is the strict body-side
+// validator; the tool handler runs BOTH and treats the flat shape as the
+// friendly wire contract.
+
+export const SynthesizePolicyMandateInputSchema = z.object({
+  source: z.literal('mandate'),
+  mandate: MandateSpecSchema,
+  ozConfig: OzAdapterConfigSchema.optional(),
+})
+
+export const SynthesizePolicyRecordingInputSchema = z.object({
+  source: z.literal('recording'),
+  recordedTx: RecordedTransactionSchema,
+  network: NetworkSchema,
+  userResponses: ComposeUserResponsesSchema.optional(),
+  confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
+  ozConfig: OzAdapterConfigSchema.optional(),
+})
+
+export const SynthesizePolicyInputSchema = z.discriminatedUnion('source', [
+  SynthesizePolicyMandateInputSchema,
+  SynthesizePolicyRecordingInputSchema,
+])
+export type SynthesizePolicyInput = z.infer<typeof SynthesizePolicyInputSchema>
+
+/** Flat ZodRawShape used for MCP tool registration. Every field is optional
+ *  so the JSON-Schema the SDK exposes to clients does not forbid either
+ *  front-end; the body re-validates against the discriminated union. */
+export const SynthesizePolicyToolShape = {
+  source: z.enum(['mandate', 'recording']).optional(),
+  mandate: MandateSpecSchema.optional(),
+  recordedTx: RecordedTransactionSchema.optional(),
+  network: NetworkSchema.optional(),
+  userResponses: ComposeUserResponsesSchema.optional(),
+  confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
+  ozConfig: OzAdapterConfigSchema.optional(),
+} as const
+
+// ===== Error envelope (canonical) =====
+//
+// Mirrors ToolError from packages/policy-synth/src/errors.ts. We use a
+// `z.string()` for `code` (not an enum) because the core's ErrorCode union
+// evolves over time; the transport contract only promises a string code the
+// caller can dispatch on. A drift test asserts the canonical codes still
+// pass through unchanged.
+export const ToolErrorSchema = z
+  .object({
+    code: z.string(),
+    message: z.string(),
+    severity: z.enum(['info', 'warning', 'error', 'fatal']),
+    retryable: z.boolean(),
+    remediation: z
+      .object({
+        toolCall: z.object({ name: z.string(), args: z.record(z.unknown()) }).optional(),
+        userQuestion: z.object({ code: z.string(), question: z.string() }).optional(),
+        docsUrl: z.string().optional(),
+      })
+      .optional(),
+    details: z.unknown().optional(),
+  })
+  .passthrough()

package/src/server.ts

@@ -0,0 +1,56 @@
+// apps/policy-builder-mcp/src/server.ts
+//
+// Registers the T1 tool surface on a fresh McpServer instance. The
+// registration uses the official MCP SDK's `tool()` API with ZodRawShape
+// schemas (the SDK does not accept ZodEffects / discriminated unions at the
+// tool registration boundary - the known gotcha). The body re-validates
+// against the strict discriminated union in src/tools/run.ts so wire inputs
+// still fail closed.
+//
+// Stateless: a fresh McpServer is constructed per transport (stdio/HTTP). No
+// shared mutable state across calls; nothing here caches, queues, or holds
+// key material.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+import { RecordTransactionToolShape, SynthesizePolicyToolShape } from './schemas.ts'
+import { mcpResultFromCore } from './tools/result.ts'
+import { runRecordTransaction, runSynthesizePolicy } from './tools/run.ts'
+
+/** Build a fresh, stateless MCP server. The caller owns the returned object
+ *  and connects it to a single transport (stdio or Streamable HTTP). */
+export function createMcpServer(): McpServer {
+  const server = new McpServer(
+    { name: 'policy-builder-mcp', version: '0.0.0' },
+    { capabilities: { tools: {} } }
+  )
+  registerTools(server)
+  return server
+}
+
+/** Idempotent registration of the T1 tool set on the given server. */
+export function registerTools(server: McpServer): void {
+  server.tool(
+    'record_transaction',
+    'Decode a Soroban transaction (on-chain hash OR base64 envelope XDR) into a RecordedTransaction. Returns a machine-readable ToolError on validation failure.',
+    RecordTransactionToolShape,
+    async (args) => {
+      const res = await runRecordTransaction(args)
+      // Our envelope types `structuredContent` precisely (T / ToolError); the
+      // SDK's CallToolResult widens it to Record<string, unknown>, so the
+      // nominal types do not overlap. The runtime shapes match, so assert
+      // through `unknown` at this transport boundary.
+      return mcpResultFromCore(res) as unknown as CallToolResult
+    }
+  )
+
+  server.tool(
+    'synthesize_policy',
+    'Synthesize a ProposedPolicy from either a deterministic MandateSpec (`source: mandate`) or a RecordedTransaction (`source: recording`). The discriminated `source` field selects the front-end.',
+    SynthesizePolicyToolShape,
+    async (args) => {
+      const res = await runSynthesizePolicy(args)
+      return mcpResultFromCore(res) as unknown as CallToolResult
+    }
+  )
+}

package/src/tools/result.ts

@@ -0,0 +1,53 @@
+// apps/policy-builder-mcp/src/tools/result.ts
+//
+// Transport-layer mapping between the core's ToolResponse<T> envelope and the
+// MCP result envelope. This is the ONLY place the two envelopes meet; no
+// business logic lives here. The shapes follow the MCP spec for the
+// `CallToolResult` type:
+//
+//   success:  { content: [{ type: 'text', text: JSON.stringify(data) }], isError: false }
+//   failure:  { content: [{ type: 'text', text: JSON.stringify(error) }], isError: true }
+//
+// Both branches carry the structured content as a single JSON-encoded text
+// block so clients that do not parse `structuredContent` still see a usable
+// payload. The shape is intentionally tiny - any extra keys belong in the
+// core, not here.
+
+import type { ToolError, ToolResponse } from '@crediolabs/policy-synth'
+
+export interface McpToolSuccess<T> {
+  isError: false
+  content: Array<{ type: 'text'; text: string }>
+  structuredContent: T
+}
+
+export interface McpToolError {
+  isError: true
+  content: Array<{ type: 'text'; text: string }>
+  structuredContent: ToolError
+}
+
+export type McpToolResult<T> = McpToolSuccess<T> | McpToolError
+
+/** Map a core ToolResponse<T> to the MCP result envelope. The handler in
+ *  src/server.ts wraps this in the SDK's `{ content, isError }` shape. */
+export function mcpResultFromCore<T>(res: ToolResponse<T>): McpToolResult<T> {
+  if (res.ok) {
+    return {
+      isError: false,
+      content: [{ type: 'text', text: JSON.stringify(res.data) }],
+      structuredContent: res.data,
+    }
+  }
+  return mcpErrorFromCore(res.error)
+}
+
+/** Map a core ToolError directly (for inputs that already failed validation
+ *  inside the handler). */
+export function mcpErrorFromCore(err: ToolError): McpToolError {
+  return {
+    isError: true,
+    content: [{ type: 'text', text: JSON.stringify(err) }],
+    structuredContent: err,
+  }
+}

package/src/tools/run.ts

@@ -0,0 +1,133 @@
+// apps/policy-builder-mcp/src/tools/run.ts
+//
+// Tool bodies for `record_transaction` and `synthesize_policy`. Each body is a
+// THIN adapter over the pure core:
+//
+//   1. Re-validate the parsed input via Zod. This is a defence-in-depth check -
+//      the SDK has already parsed it through the registered schema, but we never
+//      want a tool body to throw on garbage (the SDK treats uncaught throws as
+//      transport errors and the agent loses the machine-readable ToolError).
+//   2. Dispatch to the matching core entry point with the minimum required
+//      inputs.
+//   3. Return the core's ToolResponse<T> unchanged. The server layer maps it
+//      to the MCP envelope; nothing here knows about MCP.
+//
+// No business logic. No retries. No session state. The same call shape can
+// drive the CLI (which calls into the same core directly without MCP).
+
+import {
+  type ErrorCode,
+  type MandateSpec,
+  type OzAdapterConfig,
+  type ProposedPolicy,
+  placeholderOzConfig,
+  type RecordedTransaction,
+  recordTransaction,
+  type SynthesizeFromRecordingOptions,
+  synthesizeFromMandate,
+  synthesizeFromRecording,
+  type ToolError,
+  type ToolResponse,
+} from '@crediolabs/policy-synth'
+import {
+  type RecordTransactionInput,
+  RecordTransactionInputSchema,
+  type SynthesizePolicyInput,
+  SynthesizePolicyInputSchema,
+} from '../schemas.ts'
+
+export type RunRecordTransactionInput = RecordTransactionInput
+
+export type RunSynthesizePolicyInput = SynthesizePolicyInput
+
+/** `record_transaction` body - wraps `recordTransaction`. The tool input
+ *  matches the core RecordInput minus the injected `fetcher` (the transport
+ *  layer does not own the RPC). Returns the core ToolResponse unchanged. */
+export async function runRecordTransaction(
+  raw: unknown
+): Promise<ToolResponse<RecordedTransaction>> {
+  const parsed = RecordTransactionInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: validationError('record_transaction', parsed.error.issues),
+    }
+  }
+  const input: RecordTransactionInput = parsed.data
+  // Strip the wire-only `confidenceOverride` and pass the rest straight through.
+  const coreInput = {
+    network: input.network,
+    ...(input.hash !== undefined ? { hash: input.hash } : {}),
+    ...(input.xdr !== undefined ? { xdr: input.xdr } : {}),
+    ...(input.confidenceOverride !== undefined
+      ? { confidenceOverride: input.confidenceOverride }
+      : {}),
+  }
+  return recordTransaction(coreInput)
+}
+
+/** `synthesize_policy` body - discriminated union on `source`:
+ *    - `mandate`   -> synthesizeFromMandate
+ *    - `recording` -> synthesizeFromRecording
+ *  Exposing BOTH front-ends through ONE tool keeps the MCP surface tiny while
+ *  letting the agent pick the deterministic or the inferred path. The CLI
+ *  routes the same way. */
+export async function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy>> {
+  const parsed = SynthesizePolicyInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: validationError('synthesize_policy', parsed.error.issues),
+    }
+  }
+  const input = parsed.data
+  const ozConfig: OzAdapterConfig = resolveOzConfig(input)
+
+  if (input.source === 'mandate') {
+    // Zod's optional fields widen to `T | undefined`, which the core's
+    // exact-optional MandateSpec rejects; the schema already validated the
+    // shape, so assert it (same pattern as the recordedTx cast below).
+    return synthesizeFromMandate(input.mandate as MandateSpec, ozConfig)
+  }
+  // recording source
+  const recorded: RecordedTransaction = input.recordedTx as RecordedTransaction
+  return synthesizeFromRecording(
+    recorded,
+    {
+      network: input.network,
+      ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
+      ...(input.confidenceOverride !== undefined
+        ? { confidenceOverride: input.confidenceOverride }
+        : {}),
+    } as SynthesizeFromRecordingOptions,
+    ozConfig
+  )
+}
+
+function resolveOzConfig(input: SynthesizePolicyInput): OzAdapterConfig {
+  if (input.ozConfig) return input.ozConfig
+  // The mandate path is network-agnostic; fall back to mainnet so the
+  // placeholder OZ instance addresses are deterministic.
+  return placeholderOzConfig('mainnet')
+}
+
+/** Build a canonical ToolError for a Zod validation failure. The remediation
+ *  hint points the agent back at the right tool with an empty arg bag - the
+ *  tool name IS the machine-readable hint. */
+function validationError(
+  toolName: 'record_transaction' | 'synthesize_policy',
+  issues: ReadonlyArray<{ path: ReadonlyArray<string | number>; message: string }>
+): ToolError {
+  const code: ErrorCode = toolName === 'record_transaction' ? 'RECORDING_FAILED' : 'SYNTHESIS_ERROR'
+  return {
+    code,
+    message: `${toolName}: invalid input: ${issues
+      .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
+      .join('; ')}`,
+    severity: 'error',
+    retryable: false,
+    remediation: {
+      toolCall: { name: toolName, args: {} },
+    },
+  }
+}

package/src/transports/http.ts

@@ -0,0 +1,155 @@
+// apps/policy-builder-mcp/src/transports/http.ts
+//
+// Streamable HTTP transport (hosted). Uses the Node http module directly so
+// the package stays thin - no express / hono dep. We run in STATELESS mode
+// (sessionIdGenerator: undefined) so each POST /mcp is its own transaction:
+// this matches the brief's "stateless across calls" invariant.
+//
+// Single endpoint: POST /mcp (the SDK also accepts GET for SSE streaming, but
+// the T1 surface does not emit server-initiated messages so we omit it).
+// Listens on 127.0.0.1 by default; pass `host: '0.0.0.0'` to expose.
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
+import type { ToolError } from '@crediolabs/policy-synth'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { createMcpServer } from '../server.ts'
+
+export interface StartHttpServerOptions {
+  port: number
+  host?: string
+  /** Path the server mounts the MCP endpoint at. Default `/mcp`. */
+  path?: string
+}
+
+export interface RunningHttpServer {
+  port: number
+  host: string
+  path: string
+  close: () => Promise<void>
+}
+
+/** Stateless Streamable HTTP server. Resolves once the server is listening.
+ *  The returned handle exposes `close()` for tests + clean shutdown. */
+export async function startHttpServer(opts: StartHttpServerOptions): Promise<RunningHttpServer> {
+  const host = opts.host ?? '127.0.0.1'
+  const path = opts.path ?? '/mcp'
+  const server = createMcpServer()
+  // One transport per server (the SDK reuses the transport for every request
+  // in stateless mode). We connect it once at startup and reuse it.
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  })
+  await server.connect(transport)
+
+  const httpServer: Server = createServer(async (req, res) => {
+    if (!req.url) {
+      sendJson(res, 400, { error: 'missing url' })
+      return
+    }
+    const url = new URL(req.url, `http://${host}`)
+    if (url.pathname !== path) {
+      sendJson(res, 404, { error: 'not found', path: url.pathname })
+      return
+    }
+    if (req.method !== 'POST') {
+      // The SDK ignores non-POST in stateless mode (no GET/SSE needed in T1).
+      sendJson(res, 405, { error: 'method not allowed', method: req.method ?? null })
+      return
+    }
+
+    // Reject an over-cap body fast via Content-Length; the streaming reader is
+    // the backstop for chunked/unknown-length requests.
+    const declaredLength = Number(req.headers['content-length'])
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_BODY_BYTES) {
+      sendJson(res, 413, { error: 'request body too large' })
+      return
+    }
+
+    // Read the JSON-RPC body. The SDK accepts a pre-parsed body, so we parse
+    // it here rather than the SDK trying to re-stream the raw req.
+    let body: unknown
+    try {
+      body = await readJsonBody(req)
+    } catch (e) {
+      if (e instanceof BodyTooLargeError) {
+        sendJson(res, 413, { error: 'request body too large' })
+      } else {
+        sendJson(res, 400, { error: 'invalid JSON body' })
+      }
+      return
+    }
+    // The T1 surface is one request per call. A JSON-RPC batch (array) is
+    // rejected explicitly rather than silently dropping the extra calls.
+    if (Array.isArray(body)) {
+      sendJson(res, 400, {
+        error: 'JSON-RPC batch requests are not supported; send one request per call',
+      })
+      return
+    }
+
+    try {
+      // `handleRequest` writes the response and returns once the message has
+      // been dispatched. No shared state across calls in stateless mode.
+      await transport.handleRequest(req as IncomingMessage & { auth?: never }, res, body)
+    } catch {
+      // The SDK normally writes structured errors itself; this is a belt +
+      // braces guard so a thrown error does not leave the socket hanging.
+      if (!res.headersSent) {
+        const error: ToolError = {
+          code: 'SYNTHESIS_ERROR',
+          message: 'internal server error',
+          severity: 'error',
+          retryable: false,
+        }
+        sendJson(res, 500, { error })
+      } else res.end()
+    }
+  })
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once('error', reject)
+    httpServer.listen(opts.port, host, () => {
+      httpServer.off('error', reject)
+      resolve()
+    })
+  })
+
+  return {
+    port: opts.port,
+    host,
+    path,
+    close: async () => {
+      await new Promise<void>((resolve) => httpServer.close(() => resolve()))
+      await transport.close().catch(() => {})
+      await server.close().catch(() => {})
+    },
+  }
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json')
+  res.end(JSON.stringify(body))
+}
+
+/** Reject bodies larger than this before buffering the whole payload - a
+ *  recorded transaction is far smaller, so this only stops abusive requests. */
+const MAX_BODY_BYTES = 1_048_576
+
+/** Distinguishes an over-cap body from a malformed one so the handler can send
+ *  a 413 rather than a misleading 400. */
+class BodyTooLargeError extends Error {}
+
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let total = 0
+  for await (const chunk of req) {
+    total += (chunk as Buffer).length
+    if (total > MAX_BODY_BYTES) throw new BodyTooLargeError('request body too large')
+    chunks.push(chunk as Buffer)
+  }
+  if (chunks.length === 0) return {}
+  const raw = Buffer.concat(chunks).toString('utf8')
+  if (!raw) return {}
+  return JSON.parse(raw)
+}

package/src/transports/stdio.ts

@@ -0,0 +1,17 @@
+// apps/policy-builder-mcp/src/transports/stdio.ts
+//
+// stdio transport (Claude Desktop / local agents). The MCP SDK reads JSON-RPC
+// from stdin and writes to stdout. Each process serves ONE client and exits
+// when the client closes the stream. No key custody, no global state; the
+// per-call state lives entirely in the McpServer instance.
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { createMcpServer } from '../server.ts'
+
+export async function startStdioServer(): Promise<void> {
+  const server = createMcpServer()
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  // The transport owns the process from here; no shutdown signal handling -
+  // SIGPIPE / EOF on stdin terminates the loop naturally.
+}