@crediolabs/policy-builder-mcp 0.2.0 → 0.3.0

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; } });