@crediolabs/policy-builder-mcp 0.2.0 → 0.3.0

package/src/server.ts

@@ -15,7 +15,6 @@ import type { ToolResponse } from '@crediolabs/policy-synth'
 import {
   runGetInterpreterInfo,
   runInstallPolicy,
-  runMergePolicy,
   runRecordTransaction,
   runRevokePolicy,
   runSimulatePolicy,
@@ -27,7 +26,6 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
 import {
   GetInterpreterInfoToolShape,
   InstallPolicyToolShape,
-  MergePolicyToolShape,
   RecordTransactionToolShape,
   RevokePolicyToolShape,
   SimulatePolicyToolShape,
@@ -66,23 +64,23 @@ export function registerTools(server: McpServer): void {
 
   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.',
+    'Synthesize a ProposedPolicy from a RecordedTransaction (`source: recording`).',
     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.',
+    '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) => runSimulatePolicy(args).then(toCallToolResult)
+    (args) => toCallToolResult(runSimulatePolicy(args))
   )
 
   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.',
+    '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) => runVerifyPolicy(args).then(toCallToolResult)
+    (args) => toCallToolResult(runVerifyPolicy(args))
   )
 
   server.tool(
@@ -99,13 +97,6 @@ export function registerTools(server: McpServer): void {
     (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.',

package/src/transports/http.ts

@@ -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).
@@ -66,12 +63,6 @@ export async function startHttpServer(opts: StartHttpServerOptions): Promise<Run
       `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: Server = createServer(async (req, res) => {
     if (!req.url) {
       sendJson(res, 400, { error: 'missing url' })
@@ -118,22 +109,33 @@ export async function startHttpServer(opts: StartHttpServerOptions): Promise<Run
       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 as unknown as 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 as unknown as 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 as IncomingMessage & { auth?: never }, res, body)
@@ -151,13 +153,6 @@ export async function startHttpServer(opts: StartHttpServerOptions): Promise<Run
         }
         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(() => {})
     }
   })
 
@@ -173,9 +168,11 @@ export async function startHttpServer(opts: StartHttpServerOptions): Promise<Run
     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<void>((resolve) => httpServer.close(() => resolve()))
-      await server.close().catch(() => {})
     },
   }
 }