@crediolabs/policy-builder-mcp 0.2.0 → 0.3.1

package/src/schemas.ts

@@ -26,18 +26,13 @@ import {
   GetInterpreterInfoInputSchema,
   InstallPolicyInputSchema,
   InterpreterOptionsSchema,
-  MandateSpecSchema,
   NetworkSchema,
-  OraclePriceFixtureSchema,
-  OzAdapterConfigSchema,
   PredicateNodeSchema,
   RecordedTransactionSchema,
   RecordTransactionInputSchema,
   RevokePolicyInputSchema,
-  SimulatePolicyInputSchema,
   SynthesizePolicyInputSchema,
   ToolErrorSchema,
-  VerifyPolicyInputSchema,
 } from '@crediolabs/policy-synth/run'
 import { z } from 'zod'
 
@@ -51,18 +46,13 @@ export {
   GetInterpreterInfoInputSchema,
   InstallPolicyInputSchema,
   InterpreterOptionsSchema,
-  MandateSpecSchema,
   NetworkSchema,
-  OraclePriceFixtureSchema,
-  OzAdapterConfigSchema,
   PredicateNodeSchema,
   RecordedTransactionSchema,
   RecordTransactionInputSchema,
   RevokePolicyInputSchema,
-  SimulatePolicyInputSchema,
   SynthesizePolicyInputSchema,
   ToolErrorSchema,
-  VerifyPolicyInputSchema,
 }
 
 /** Flat ZodRawShape used for the MCP SDK tool registration. The body
@@ -76,17 +66,15 @@ export const RecordTransactionToolShape = {
 } as const
 
 /** 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,
@@ -97,35 +85,18 @@ export const SynthesizePolicyToolShape = {
   explain: z.boolean().optional(),
 } as const
 
-/** 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(),
 } as const
 
-/** 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(),
-} as const
+export const SimulatePolicyToolShape = { ...PolicyCheckToolShape } as const
+export const VerifyPolicyToolShape = { ...PolicyCheckToolShape } as const
 
-// Re-export the strict input schemas so MCP consumers (and downstream
-// tests) can import the canonical wire shapes from the same module
-// that owns the tool-shape glue.
 export type {
   GetInterpreterInfoInput,
   InstallPolicyInput,
@@ -135,13 +106,20 @@ export type {
 } from '@crediolabs/policy-synth/run'
 
 /** 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(),
 }
@@ -167,15 +145,6 @@ export const RevokePolicyToolShape = {
   interpreterAddress: z.string().optional(),
 } as const
 
-/** 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']),
-} as const
-
 /** 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/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(() => {})
     },
   }
 }