@crediolabs/policy-builder-mcp 0.1.0

package/dist/src/schemas.js

@@ -0,0 +1,221 @@
+// 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']);
+/** ScVal subset - normalised subset the synth consumes. Mirrors
+ *  `ScVal` in packages/policy-synth/src/types.ts. */
+export const ScValSchema = 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.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',
+});
+/** 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(),
+};
+// ===== 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,
+]);
+/** 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(),
+};
+// ===== 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/dist/src/server.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** Build a fresh, stateless MCP server. The caller owns the returned object
+ *  and connects it to a single transport (stdio or Streamable HTTP). */
+export declare function createMcpServer(): McpServer;
+/** Idempotent registration of the T1 tool set on the given server. */
+export declare function registerTools(server: McpServer): void;

package/dist/src/server.js

@@ -0,0 +1,38 @@
+// 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 { RecordTransactionToolShape, SynthesizePolicyToolShape } from "./schemas.js";
+import { mcpResultFromCore } from "./tools/result.js";
+import { runRecordTransaction, runSynthesizePolicy } from "./tools/run.js";
+/** 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() {
+    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) {
+    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);
+    });
+    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);
+    });
+}

package/dist/src/tools/result.d.ts

@@ -0,0 +1,24 @@
+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 declare function mcpResultFromCore<T>(res: ToolResponse<T>): McpToolResult<T>;
+/** Map a core ToolError directly (for inputs that already failed validation
+ *  inside the handler). */
+export declare function mcpErrorFromCore(err: ToolError): McpToolError;

package/dist/src/tools/result.js

@@ -0,0 +1,35 @@
+// 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.
+/** 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(res) {
+    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) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(err) }],
+        structuredContent: err,
+    };
+}

package/dist/src/tools/run.d.ts

@@ -0,0 +1,15 @@
+import { type ProposedPolicy, type RecordedTransaction, type ToolResponse } from '@crediolabs/policy-synth';
+import { type RecordTransactionInput, type SynthesizePolicyInput } 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 declare function runRecordTransaction(raw: unknown): Promise<ToolResponse<RecordedTransaction>>;
+/** `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 declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy>>;

package/dist/src/tools/run.js

@@ -0,0 +1,97 @@
+// 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 { placeholderOzConfig, recordTransaction, synthesizeFromMandate, synthesizeFromRecording, } from '@crediolabs/policy-synth';
+import { RecordTransactionInputSchema, SynthesizePolicyInputSchema, } from "../schemas.js";
+/** `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) {
+    const parsed = RecordTransactionInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: validationError('record_transaction', parsed.error.issues),
+        };
+    }
+    const input = 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) {
+    const parsed = SynthesizePolicyInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: validationError('synthesize_policy', parsed.error.issues),
+        };
+    }
+    const input = parsed.data;
+    const ozConfig = 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, ozConfig);
+    }
+    // recording source
+    const recorded = input.recordedTx;
+    return synthesizeFromRecording(recorded, {
+        network: input.network,
+        ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
+        ...(input.confidenceOverride !== undefined
+            ? { confidenceOverride: input.confidenceOverride }
+            : {}),
+    }, ozConfig);
+}
+function resolveOzConfig(input) {
+    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, issues) {
+    const code = 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/dist/src/transports/http.d.ts

@@ -0,0 +1,15 @@
+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 declare function startHttpServer(opts: StartHttpServerOptions): Promise<RunningHttpServer>;

package/dist/src/transports/http.js

@@ -0,0 +1,137 @@
+// 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 } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMcpServer } from "../server.js";
+/** Stateless Streamable HTTP server. Resolves once the server is listening.
+ *  The returned handle exposes `close()` for tests + clean shutdown. */
+export async function startHttpServer(opts) {
+    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 = 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;
+        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, 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 = {
+                    code: 'SYNTHESIS_ERROR',
+                    message: 'internal server error',
+                    severity: 'error',
+                    retryable: false,
+                };
+                sendJson(res, 500, { error });
+            }
+            else
+                res.end();
+        }
+    });
+    await new Promise((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((resolve) => httpServer.close(() => resolve()));
+            await transport.close().catch(() => { });
+            await server.close().catch(() => { });
+        },
+    };
+}
+function sendJson(res, status, body) {
+    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) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        total += chunk.length;
+        if (total > MAX_BODY_BYTES)
+            throw new BodyTooLargeError('request body too large');
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return {};
+    const raw = Buffer.concat(chunks).toString('utf8');
+    if (!raw)
+        return {};
+    return JSON.parse(raw);
+}

package/dist/src/transports/stdio.d.ts

@@ -0,0 +1 @@
+export declare function startStdioServer(): Promise<void>;

package/dist/src/transports/stdio.js

@@ -0,0 +1,15 @@
+// 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.js";
+export async function startStdioServer() {
+    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.
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crediolabs/policy-builder-mcp",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "MCP server exposing the OZ policy-synth core (record_transaction + synthesize_policy) over stdio and Streamable HTTP transports.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "policy-builder-mcp": "./dist/bin/server.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@crediolabs/policy-synth": "^0.1.0",
+    "@modelcontextprotocol/sdk": "1.18.1",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.5",
+    "@types/node": "^26.1.1",
+    "typescript": "5.9.3"
+  }
+}