@crediolabs/policy-builder-mcp 0.2.0 → 0.3.1

package/dist/src/schemas.js

@@ -20,14 +20,14 @@
 // `ZodEffects`, which has no `.shape`). They MUST stay in lockstep with
 // the strict schemas - a drift in field type or optionality breaks the
 // SDK's emitted JSON Schema.
-import { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OraclePriceFixtureSchema, OzAdapterConfigSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, VerifyPolicyInputSchema, } from '@crediolabs/policy-synth/run';
+import { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, NetworkSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, } from '@crediolabs/policy-synth/run';
 import { z } from 'zod';
 // Re-export the strict schemas so MCP package consumers (and existing tests)
 // still get them from this module. The canonical home is
 // `@crediolabs/policy-synth/run`; the re-exports here are a shim kept for
 // backward compatibility with downstream callers that imported from the MCP
 // package directly.
-export { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OraclePriceFixtureSchema, OzAdapterConfigSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, VerifyPolicyInputSchema, };
+export { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, NetworkSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, };
 /** 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). */
@@ -38,17 +38,15 @@ export const RecordTransactionToolShape = {
     confidenceOverride: z.number().min(0).max(1).optional(),
 };
 /** 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. */
+ *  so the JSON-Schema the SDK exposes to clients stays permissive; the body
+ *  re-validates against the strict schema. */
 export const SynthesizePolicyToolShape = {
-    source: z.enum(['mandate', 'recording']).optional(),
-    mandate: MandateSpecSchema.optional(),
+    source: z.literal('recording').optional(),
     recordedTx: RecordedTransactionSchema.optional(),
     network: NetworkSchema.optional(),
     userResponses: ComposeUserResponsesSchema.optional(),
     confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
     interpreter: InterpreterOptionsSchema.optional(),
-    ozConfig: OzAdapterConfigSchema.optional(),
     // Without this the tool chain has no join. A ProposedPolicy carries
     // `policyDocuments[].encodedPredicate` (canonical ScVal bytes), while
     // `simulate_policy` and `verify_policy` both want the PredicateNode TREE,
@@ -58,38 +56,31 @@ export const SynthesizePolicyToolShape = {
     // which skips the interpreter predicate entirely.
     explain: z.boolean().optional(),
 };
-/** Flat ZodRawShape for `simulate_policy`. The `predicate` is typed as
- *  `z.unknown()` at the tool boundary because the recursive
- *  `PredicateNodeSchema` is a `z.lazy()` union (the SDK does not accept
- *  unions at the tool-registration boundary); the body re-validates
- *  against `SimulatePolicyInputSchema`, which fails closed on a
- *  malformed predicate. `predicate` is nullable here (vs required for
- *  verify_policy) so the SDK-emitted JSON Schema mirrors the engine's
- *  "OZ-only / no interpreter predicate" contract. */
-export const SimulatePolicyToolShape = {
-    predicate: z.unknown().nullable().optional(),
+/** `simulate_policy` and `verify_policy` share their input: the predicate tree
+ *  (from `synthesize_policy` under `explain`) plus the recording it was
+ *  synthesised from. */
+const PolicyCheckToolShape = {
+    predicate: PredicateNodeSchema,
     permitTx: RecordedTransactionSchema,
     validUntilLedger: z.number().int().positive().optional(),
-    oraclePricesByAsset: z.record(z.string(), OraclePriceFixtureSchema).optional(),
-};
-/** Flat ZodRawShape for `verify_policy`. Same `z.unknown()` boundary
- *  trick for `predicate` as `SimulatePolicyToolShape`; `predicate` is
- *  required at the strict-schema level (`VerifyPolicyInputSchema`) so
- *  the body fails closed on a missing predicate. */
-export const VerifyPolicyToolShape = {
-    predicate: z.unknown(),
-    permitTx: RecordedTransactionSchema,
-    validUntilLedger: z.number().int().positive().optional(),
-    oraclePricesByAsset: z.record(z.string(), OraclePriceFixtureSchema).optional(),
 };
+export const SimulatePolicyToolShape = { ...PolicyCheckToolShape };
+export const VerifyPolicyToolShape = { ...PolicyCheckToolShape };
 /** Common base for `install_policy` and `revoke_policy`: smartAccount,
- *  sourceAccount, optional RPC URL, optional base fee. Both share the
- *  same smart-account context, so the SDK-emitted JSON Schema stays
+ *  sourceAccount, target network, optional RPC URL, optional base fee. Both
+ *  share the same smart-account context, so the SDK-emitted JSON Schema stays
  *  identical for those fields. The body re-validates against the strict
  *  schemas in `@crediolabs/policy-synth/run`. */
 const SmartAccountToolShape = {
     smartAccount: z.string().min(1).optional(),
     sourceAccount: z.string().min(1).optional(),
+    /** Omitting this from the shape made both tools testnet-ONLY. The input
+     *  schema defaults `network` to `testnet` and expects a mainnet caller to
+     *  set it, but a field absent from the tool shape is STRIPPED before the
+     *  body runs, so an MCP client could not reach the mainnet pin at all. The
+     *  failure presented as a deliberate testnet pin rather than as a missing
+     *  parameter, which sent integrators to build the install by hand. */
+    network: NetworkSchema.optional(),
     rpcUrl: z.string().url().optional(),
     baseFee: z.number().int().positive().optional(),
 };
@@ -112,14 +103,6 @@ export const RevokePolicyToolShape = {
     ruleId: z.number().int().nonnegative().optional(),
     interpreterAddress: z.string().optional(),
 };
-/** Flat ZodRawShape for `merge_policy`: the tightening remedy when two rules
- *  our interpreter polices can serve the same calls. Two steps, in order. */
-export const MergePolicyToolShape = {
-    ...SmartAccountToolShape,
-    ruleId: z.number().int().nonnegative(),
-    incomingPredicateBlobBase64: z.string().min(1),
-    step: z.enum(['detach', 'reinstall']),
-};
 /** Flat ZodRawShape for `get_interpreter_info`. `verifyLive` triggers an
  *  optional RPC `grammar_version()` call so the caller can verify the
  *  deployed contract matches the pin. */

package/dist/src/server.js

@@ -10,9 +10,9 @@
 // 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 { runGetInterpreterInfo, runInstallPolicy, runMergePolicy, runRecordTransaction, runRevokePolicy, runSimulatePolicy, runSynthesizePolicy, runVerifyPolicy, } from '@crediolabs/policy-synth/run';
+import { runGetInterpreterInfo, runInstallPolicy, runRecordTransaction, runRevokePolicy, runSimulatePolicy, runSynthesizePolicy, runVerifyPolicy, } from '@crediolabs/policy-synth/run';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { GetInterpreterInfoToolShape, InstallPolicyToolShape, MergePolicyToolShape, RecordTransactionToolShape, RevokePolicyToolShape, SimulatePolicyToolShape, SynthesizePolicyToolShape, VerifyPolicyToolShape, } from "./schemas.js";
+import { GetInterpreterInfoToolShape, InstallPolicyToolShape, RecordTransactionToolShape, RevokePolicyToolShape, SimulatePolicyToolShape, SynthesizePolicyToolShape, VerifyPolicyToolShape, } from "./schemas.js";
 import { mcpResultFromCore } from "./tools/result.js";
 /** Our envelope types `structuredContent` precisely (T / ToolError); the SDK's
  *  CallToolResult widens it to Record<string, unknown>, so the nominal types
@@ -29,11 +29,10 @@ export function createMcpServer() {
 /** 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, (args) => runRecordTransaction(args).then(toCallToolResult));
-    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, (args) => runSynthesizePolicy(args).then(toCallToolResult));
-    server.tool('simulate_policy', 'Replay a RecordedTransaction against a proposed PredicateNode (or null for an OZ-only policy) and emit the SimulationResult envelope (permit verdict + deny-case battery). Returns a SIMULATION_ERROR ToolError on runtime evaluation failure.', SimulatePolicyToolShape, (args) => runSimulatePolicy(args).then(toCallToolResult));
-    server.tool('verify_policy', 'Run the static minimality check on a proposed PredicateNode against a RecordedTransaction (no conjunct is load-bearing-free). Returns VERIFICATION_FAILED with the dropped-constraint fingerprints when the predicate is over-broad.', VerifyPolicyToolShape, (args) => runVerifyPolicy(args).then(toCallToolResult));
+    server.tool('synthesize_policy', 'Synthesize a ProposedPolicy from a RecordedTransaction (`source: recording`).', SynthesizePolicyToolShape, (args) => runSynthesizePolicy(args).then(toCallToolResult));
+    server.tool('simulate_policy', 'Evaluate a predicate against one recorded call and report permit/deny with the deny reason. The evaluator is a second implementation of the on-chain semantics, cross-checked against the Rust interpreter by the conformance harness, so a verdict here is a claim about what the contract would do. Pass the `predicate` returned by `synthesize_policy` under `explain`.', SimulatePolicyToolShape, (args) => toCallToolResult(runSimulatePolicy(args)));
+    server.tool('verify_policy', 'Check a predicate against the transaction it was synthesised from, plus a generated deny case per dimension. Reports `ok` only when the permit case is permitted AND every deny case is denied - a denied permit case means the policy is too strict, a permitted deny case means it is too loose.', VerifyPolicyToolShape, (args) => toCallToolResult(runVerifyPolicy(args)));
     server.tool('install_policy', 'Build an UNSIGNED Soroban transaction XDR for `account.add_context_rule(...)` that installs a new policy rule on the given smart account. The wallet signs the returned XDR - the signature IS the user-confirmation step (this server is stateless and holds no key material, so there is no two-call confirm pair). Only CALL 1 is emitted; the interpreter `install` follow-up needs the rule id the account assigns in call 1 and is documented in `followUp` in the response.', InstallPolicyToolShape, (args) => runInstallPolicy(args).then(toCallToolResult));
     server.tool('revoke_policy', 'Build an UNSIGNED Soroban transaction XDR for `account.remove_context_rule(ruleId)` that removes a policy rule from the given smart account. The smart account handles uninstalling each attached policy itself. Auth is master-only - the source account MUST be the master signer set; delegated signers cannot uninstall.', RevokePolicyToolShape, (args) => runRevokePolicy(args).then(toCallToolResult));
-    server.tool('merge_policy', "Tighten a rule by replacing its predicate with the conjunction of the installed one and a new one. This is the remedy for the overlap `install_policy` reports between two rules the interpreter polices: because OpenZeppelin enforces only the rule a signer names, adding a second, tighter rule restricts nothing, so the restriction has to become one predicate. TWO transactions, in order: call with step 'detach' to remove the current attachment, wait for it to confirm, then call with step 'reinstall'. Detaching uninstalls the policy, which RESETS every counter on the rule, and the rule is unpoliced in between - both are reported in `warnings`.", MergePolicyToolShape, (args) => runMergePolicy(args).then(toCallToolResult));
     server.tool('get_interpreter_info', 'Read-only fingerprint lookup for the policy interpreter contract: returns the pinned address, grammar version, and wasm sha256 (from the pinned constants + SELF_VERSION). When `verifyLive=true`, performs an additional `grammar_version()` RPC call against the pinned address and reports whether the deployed contract matches the pin - a live mismatch check is more useful than a fabricated audit field.', GetInterpreterInfoToolShape, (args) => runGetInterpreterInfo(args).then(toCallToolResult));
 }

package/dist/src/transports/http.js

@@ -2,13 +2,10 @@
 //
 // Streamable HTTP transport (hosted). Uses the Node http module directly so
 // the package stays thin - no express / hono dep. We run in STATELESS mode
-// (no `sessionIdGenerator` option), and the SDK 1.26+ requires a FRESH
-// transport per request in stateless mode: reusing one across requests lets
-// concurrent clients share internal message-id state, which is exactly the
-// cross-client data leak GHSA-345p-7cg4-v4c7 warns about. We therefore build
-// a transport inside the request handler, connect it, dispatch the request,
-// then close it (close() resets the McpServer's transport slot so the next
-// request can reconnect cleanly).
+// (no sessionIdGenerator: the SDK disables session management when it is not
+// provided) so each POST /mcp is its own transaction: this matches the
+// brief's "stateless across calls" invariant. Stateless means a fresh server
+// and transport per request - see the handler for why the SDK requires it.
 //
 // 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).
@@ -39,11 +36,6 @@ export async function startHttpServer(opts) {
     if (!LOOPBACK_HOSTS.has(host) && opts.allowExternalHost !== true) {
         throw new Error(`startHttpServer: refusing to bind host ${host}: the MCP surface is unauthenticated, so only loopback (127.0.0.1, ::1, localhost) is permitted by default. Pass \`allowExternalHost: true\` to opt in to a non-loopback bind.`);
     }
-    // The McpServer is stateless and per-process; we keep ONE instance alive
-    // for the lifetime of the listener, but each request creates + connects a
-    // fresh StreamableHTTPServerTransport (SDK 1.26+ refuses to reuse a
-    // stateless transport across requests).
-    const server = createMcpServer();
     const httpServer = createServer(async (req, res) => {
         if (!req.url) {
             sendJson(res, 400, { error: 'missing url' });
@@ -89,21 +81,33 @@ export async function startHttpServer(opts) {
             });
             return;
         }
-        // One transport per request. Omitting `sessionIdGenerator` selects
-        // stateless mode in SDK 1.26+ (the previous `sessionIdGenerator:
-        // undefined` form is rejected because the option type no longer
-        // includes `undefined` under `exactOptionalPropertyTypes`).
-        //
-        // The cast `as unknown as Transport` is narrowly scoped to the SDK
-        // boundary: the Node wrapper exposes `onclose` via getter/setter with
-        // type `(() => void) | undefined`, while the `Transport` interface
-        // declares `onclose?: () => void`. Under `exactOptionalPropertyTypes:
-        // true` those are not structurally assignable. The runtime contract is
-        // the same (the setter accepts `() => void`), so we cast once here.
+        // A stateless transport handles exactly ONE request: the SDK refuses to
+        // reuse one ("Stateless transport cannot be reused across requests"),
+        // because a shared instance would let concurrent clients collide on
+        // JSON-RPC message ids. So the server and its transport are built here,
+        // per request, and torn down when the response closes.
+        // No `sessionIdGenerator`: the SDK disables session management when the
+        // option is absent, which is the stateless mode this surface wants.
+        // Passing an explicit `undefined` means the same thing to the SDK but is
+        // not assignable under `exactOptionalPropertyTypes`, so omission is both
+        // the type-correct and the documented spelling.
+        const server = createMcpServer();
         const transport = new StreamableHTTPServerTransport();
-        const sdkTransport = transport;
-        await server.connect(sdkTransport);
+        // Registered before dispatch, not after: once the response has closed the
+        // event is gone, so a listener attached afterwards would never fire and
+        // the pair would leak.
+        res.on('close', () => {
+            void transport.close().catch(() => { });
+            void server.close().catch(() => { });
+        });
         try {
+            // The SDK declares `Transport.onclose` as an optional `() => void`, but
+            // exposes it on this class as an accessor pair typed `(() => void) |
+            // undefined`. Those are not assignable under `exactOptionalPropertyTypes`.
+            // The widening is upstream and structural only - the runtime object does
+            // satisfy `Transport` - so the assertion is narrowed to this one call
+            // rather than relaxing the compiler flag for the whole package.
+            await server.connect(transport);
             // `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);
@@ -124,14 +128,6 @@ export async function startHttpServer(opts) {
                 sendJson(res, 500, { error });
             }
         }
-        finally {
-            // Closing the transport fires its `onclose`, which resets
-            // `server._transport` to undefined so the next request can connect
-            // a fresh transport. We swallow the close error: a request that
-            // already wrote its response does not care whether the close path
-            // threw.
-            await transport.close().catch(() => { });
-        }
     });
     await new Promise((resolve, reject) => {
         httpServer.once('error', reject);
@@ -144,9 +140,11 @@ export async function startHttpServer(opts) {
         port: opts.port,
         host,
         path,
+        // Nothing outlives a request, so closing the listener is the whole
+        // shutdown: each request's server and transport are already torn down by
+        // the `close` handler on its own response.
         close: async () => {
             await new Promise((resolve) => httpServer.close(() => resolve()));
-            await server.close().catch(() => { });
         },
     };
 }

package/dist-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist-cjs/src/index.d.ts

@@ -0,0 +1,7 @@
+export { type RunRecordTransactionInput, type RunSynthesizePolicyInput, runRecordTransaction, runSynthesizePolicy, } from '@crediolabs/policy-synth/run';
+export { RecordTransactionToolShape, 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 { startHttpServer } from './transports/http.ts';
+export { startStdioServer } from './transports/stdio.ts';

package/dist-cjs/src/index.js

@@ -0,0 +1,20 @@
+"use strict";
+// packages/policy-builder-mcp/src/index.ts - public re-exports for the MCP server package.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startStdioServer = exports.startHttpServer = exports.mcpResultFromCore = exports.mcpErrorFromCore = exports.registerTools = exports.createMcpServer = exports.SynthesizePolicyToolShape = exports.RecordTransactionToolShape = exports.runSynthesizePolicy = exports.runRecordTransaction = void 0;
+var run_1 = require("@crediolabs/policy-synth/run");
+Object.defineProperty(exports, "runRecordTransaction", { enumerable: true, get: function () { return run_1.runRecordTransaction; } });
+Object.defineProperty(exports, "runSynthesizePolicy", { enumerable: true, get: function () { return run_1.runSynthesizePolicy; } });
+var schemas_ts_1 = require("./schemas.js");
+Object.defineProperty(exports, "RecordTransactionToolShape", { enumerable: true, get: function () { return schemas_ts_1.RecordTransactionToolShape; } });
+Object.defineProperty(exports, "SynthesizePolicyToolShape", { enumerable: true, get: function () { return schemas_ts_1.SynthesizePolicyToolShape; } });
+var server_ts_1 = require("./server.js");
+Object.defineProperty(exports, "createMcpServer", { enumerable: true, get: function () { return server_ts_1.createMcpServer; } });
+Object.defineProperty(exports, "registerTools", { enumerable: true, get: function () { return server_ts_1.registerTools; } });
+var result_ts_1 = require("./tools/result.js");
+Object.defineProperty(exports, "mcpErrorFromCore", { enumerable: true, get: function () { return result_ts_1.mcpErrorFromCore; } });
+Object.defineProperty(exports, "mcpResultFromCore", { enumerable: true, get: function () { return result_ts_1.mcpResultFromCore; } });
+var http_ts_1 = require("./transports/http.js");
+Object.defineProperty(exports, "startHttpServer", { enumerable: true, get: function () { return http_ts_1.startHttpServer; } });
+var stdio_ts_1 = require("./transports/stdio.js");
+Object.defineProperty(exports, "startStdioServer", { enumerable: true, get: function () { return stdio_ts_1.startStdioServer; } });