@crediolabs/policy-builder-mcp 0.1.17 → 0.2.0

package/README.md

@@ -1,39 +1,30 @@
 # @crediolabs/policy-builder-mcp
 
-MCP server exposing the OpenZeppelin Accounts Policy Builder core over stdio and
-Streamable HTTP. It wraps [`@crediolabs/policy-synth`](https://www.npmjs.com/package/@crediolabs/policy-synth)
-so an agent can record a Soroban transaction and synthesise the minimal policy
-that permits exactly that flow. MIT-licensed.
-
-## Install
-
-```sh
-npm install @crediolabs/policy-builder-mcp
-# or run without installing:
-npx @crediolabs/policy-builder-mcp
-```
+MCP server exposing the OctoGate policy toolchain to agents. It wraps
+[`@crediolabs/policy-synth`](https://www.npmjs.com/package/@crediolabs/policy-synth):
+an agent records a Soroban transaction, synthesises the minimal policy that
+permits exactly that flow, verifies and simulates it, and receives an
+unsigned install transaction for the user's wallet to sign.
 
 ## Run
 
 ```sh
-policy-builder-mcp                # stdio transport (default; Claude Desktop / local agents)
-policy-builder-mcp --http         # Streamable HTTP transport on default port 3001
-policy-builder-mcp --http --http-port N  # Streamable HTTP transport on port N
-```
+# stdio (default; Claude Desktop and local agents)
+bunx @crediolabs/policy-builder-mcp
 
-Note: `--http-port` only takes effect when `--http` is also supplied (without
-`--http` the server stays on stdio regardless of `--http-port`). The port
-override must be an integer in `1..65535`; otherwise the default `3001` is
-used. Source of truth: [`bin/server.ts`](./bin/server.ts).
+# Streamable HTTP on localhost:3001
+bunx @crediolabs/policy-builder-mcp --http
+bunx @crediolabs/policy-builder-mcp --http --http-port 8080
+```
 
-### Use with an MCP client (e.g. Claude Desktop)
+Claude Desktop / Claude Code configuration:
 
 ```json
 {
   "mcpServers": {
     "policy-builder": {
-      "command": "npx",
-      "args": ["-y", "@crediolabs/policy-builder-mcp"]
+      "command": "bunx",
+      "args": ["@crediolabs/policy-builder-mcp"]
     }
   }
 }
@@ -41,35 +32,34 @@ used. Source of truth: [`bin/server.ts`](./bin/server.ts).
 
 ## Tools
 
-- **`record_transaction`** — decode a Soroban transaction (on-chain `hash` **or**
-  base64 envelope `xdr`, plus `network`) into a `RecordedTransaction`.
-- **`synthesize_policy`** — synthesise a proposed policy from either a
-  deterministic mandate (`source: "mandate"`) or a recording
-  (`source: "recording"`); the `source` field selects the front-end.
-
-Each tool returns the core's structured result. On invalid input it returns a
-machine-readable `ToolError` (never an uncaught throw), so the agent keeps a
-usable, actionable payload.
-
-## Programmatic use
-
-```ts
-import { createMcpServer, startStdioServer, startHttpServer } from '@crediolabs/policy-builder-mcp'
-
-await startStdioServer()          // or: await startHttpServer({ port: 3001 })
-
-// or wire the server into your own transport:
-const server = createMcpServer()
-```
-
-The server is stateless: a fresh instance is built per transport, and nothing
-caches, queues, or holds key material.
-
-## Status
-
-The `record_transaction` and `synthesize_policy` tools are implemented and
-test-covered. Install, on-chain verify, and simulate are later phases.
+| Tool | Purpose |
+| --- | --- |
+| `record_transaction` | Decode a transaction (hash or envelope XDR) into a `RecordedTransaction`. |
+| `synthesize_policy` | Synthesise a `ProposedPolicy` from a recording or a `MandateSpec`. |
+| `simulate_policy` | Replay a recording against a proposed predicate; run the deny-case battery. |
+| `verify_policy` | Static minimality check on a proposed predicate. |
+| `install_policy` | Build the unsigned `add_context_rule` transaction XDR. |
+| `revoke_policy` | Build the unsigned `remove_context_rule` transaction XDR. |
+| `get_interpreter_info` | Pinned interpreter address, grammar version and wasm sha256, optionally verified live. |
+
+Failures come back as machine-readable tool errors (stable `code`,
+`severity`, `retryable`), never as transport-level throws, so an agent can
+branch on them.
+
+## Security model
+
+- **Stateless, no key material.** Install and revoke return *unsigned* XDR;
+  the wallet signature is the user-confirmation step.
+- **Loopback only by default.** The HTTP transport refuses to bind a
+  non-loopback host; it serves `127.0.0.1`, `::1` or `localhost` unless the
+  embedding caller explicitly opts out (`allowExternalHost: true` via the
+  programmatic API), because the surface is unauthenticated by design.
+- See the
+  [architecture document](https://github.com/untangledfinance/octogate/blob/main/docs/architecture.md)
+  for what the on-chain interpreter does and does not enforce, and the
+  [repository README](https://github.com/untangledfinance/octogate#readme)
+  for the contracts' audit status.
 
 ## License
 
-MIT.
+MIT

package/dist/bin/server.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// apps/policy-builder-mcp/bin/server.ts - CLI entry point selecting the transport.
+// packages/policy-builder-mcp/bin/server.ts - CLI entry point selecting the transport.
 //
 // Usage:
 //   policy-builder-mcp                (stdio - default; Claude Desktop / local agents)

package/dist/src/index.js

@@ -1,4 +1,4 @@
-// apps/policy-builder-mcp/src/index.ts - public re-exports for the MCP server package.
+// packages/policy-builder-mcp/src/index.ts - public re-exports for the MCP server package.
 export { runRecordTransaction, runSynthesizePolicy, } from '@crediolabs/policy-synth/run';
 export { RecordTransactionToolShape, SynthesizePolicyToolShape, } from "./schemas.js";
 export { createMcpServer, registerTools } from "./server.js";

package/dist/src/schemas.d.ts

@@ -15,7 +15,7 @@ export declare const RecordTransactionToolShape: {
  *  front-end; the body re-validates against the discriminated union. */
 export declare const SynthesizePolicyToolShape: {
     readonly source: z.ZodOptional<z.ZodEnum<["mandate", "recording"]>>;
-    readonly mandate: z.ZodOptional<z.ZodObject<{
+    readonly mandate: z.ZodOptional<z.ZodEffects<z.ZodObject<{
         chain: z.ZodLiteral<"stellar">;
         contract: z.ZodString;
         method: z.ZodOptional<z.ZodString>;
@@ -102,6 +102,64 @@ export declare const SynthesizePolicyToolShape: {
             validUntilLedger?: number | undefined;
             validUntilUnixSeconds?: number | undefined;
         }>>;
+    }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+        chain: z.ZodLiteral<"stellar">;
+        contract: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        spendingLimit: z.ZodOptional<z.ZodObject<{
+            token: z.ZodString;
+            limit: z.ZodString;
+            windowSeconds: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }>>;
+        approvalThreshold: z.ZodOptional<z.ZodNumber>;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        expiry: z.ZodOptional<z.ZodObject<{
+            validUntilLedger: z.ZodOptional<z.ZodNumber>;
+            validUntilUnixSeconds: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        chain: z.ZodLiteral<"stellar">;
+        contract: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        spendingLimit: z.ZodOptional<z.ZodObject<{
+            token: z.ZodString;
+            limit: z.ZodString;
+            windowSeconds: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }>>;
+        approvalThreshold: z.ZodOptional<z.ZodNumber>;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        expiry: z.ZodOptional<z.ZodObject<{
+            validUntilLedger: z.ZodOptional<z.ZodNumber>;
+            validUntilUnixSeconds: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }>>;
     }, z.ZodTypeAny, "passthrough">>>;
     readonly recordedTx: z.ZodOptional<z.ZodObject<{
         network: z.ZodEnum<["mainnet", "testnet"]>;
@@ -369,18 +427,66 @@ export declare const SynthesizePolicyToolShape: {
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
         swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        oraclePriceBound: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            asset: z.ZodEffects<z.ZodString, string, string>;
+            operator: z.ZodEnum<["eq", "lt", "lte", "gt", "gte"]>;
+            value: z.ZodString;
+            decimals: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            operator: "eq" | "lt" | "lte" | "gt" | "gte";
+            asset: string;
+            decimals: number;
+        }, {
+            value: string;
+            operator: "eq" | "lt" | "lte" | "gt" | "gte";
+            asset: string;
+            decimals: number;
+        }>, "many">>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
         swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        oraclePriceBound: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            asset: z.ZodEffects<z.ZodString, string, string>;
+            operator: z.ZodEnum<["eq", "lt", "lte", "gt", "gte"]>;
+            value: z.ZodString;
+            decimals: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            operator: "eq" | "lt" | "lte" | "gt" | "gte";
+            asset: string;
+            decimals: number;
+        }, {
+            value: string;
+            operator: "eq" | "lt" | "lte" | "gt" | "gte";
+            asset: string;
+            decimals: number;
+        }>, "many">>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
         swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        oraclePriceBound: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            asset: z.ZodEffects<z.ZodString, string, string>;
+            operator: z.ZodEnum<["eq", "lt", "lte", "gt", "gte"]>;
+            value: z.ZodString;
+            decimals: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            operator: "eq" | "lt" | "lte" | "gt" | "gte";
+            asset: string;
+            decimals: number;
+        }, {
+            value: string;
+            operator: "eq" | "lt" | "lte" | "gt" | "gte";
+            asset: string;
+            decimals: number;
+        }>, "many">>;
     }, z.ZodTypeAny, "passthrough">>>;
     readonly confidenceOverride: z.ZodOptional<z.ZodObject<{
         threshold: z.ZodNumber;
@@ -1028,20 +1134,31 @@ export type { GetInterpreterInfoInput, InstallPolicyInput, RevokePolicyInput, Si
  *  (the policy already carries the encoded predicate); the run-layer
  *  extracts them from there. */
 export declare const InstallPolicyToolShape: {
-    readonly smartAccount: z.ZodOptional<z.ZodString>;
-    readonly sourceAccount: z.ZodOptional<z.ZodString>;
     readonly rule: z.ZodOptional<z.ZodUnknown>;
     readonly installNonce: z.ZodOptional<z.ZodNumber>;
     readonly interpreterAddress: z.ZodOptional<z.ZodString>;
+    readonly smartAccount: z.ZodOptional<z.ZodString>;
+    readonly sourceAccount: z.ZodOptional<z.ZodString>;
     readonly rpcUrl: z.ZodOptional<z.ZodString>;
     readonly baseFee: z.ZodOptional<z.ZodNumber>;
 };
 /** Flat ZodRawShape for `revoke_policy`. */
 export declare const RevokePolicyToolShape: {
-    readonly smartAccount: z.ZodOptional<z.ZodString>;
-    readonly sourceAccount: z.ZodOptional<z.ZodString>;
     readonly ruleId: z.ZodOptional<z.ZodNumber>;
     readonly interpreterAddress: z.ZodOptional<z.ZodString>;
+    readonly smartAccount: z.ZodOptional<z.ZodString>;
+    readonly sourceAccount: z.ZodOptional<z.ZodString>;
+    readonly rpcUrl: z.ZodOptional<z.ZodString>;
+    readonly baseFee: z.ZodOptional<z.ZodNumber>;
+};
+/** Flat ZodRawShape for `merge_policy`: the tightening remedy when two rules
+ *  our interpreter polices can serve the same calls. Two steps, in order. */
+export declare const MergePolicyToolShape: {
+    readonly ruleId: z.ZodNumber;
+    readonly incomingPredicateBlobBase64: z.ZodString;
+    readonly step: z.ZodEnum<["detach", "reinstall"]>;
+    readonly smartAccount: z.ZodOptional<z.ZodString>;
+    readonly sourceAccount: z.ZodOptional<z.ZodString>;
     readonly rpcUrl: z.ZodOptional<z.ZodString>;
     readonly baseFee: z.ZodOptional<z.ZodNumber>;
 };

package/dist/src/schemas.js

@@ -1,4 +1,4 @@
-// apps/policy-builder-mcp/src/schemas.ts
+// packages/policy-builder-mcp/src/schemas.ts
 //
 // MCP-only tool shapes. The CORE input/output schemas and the MCP server
 // registrations all live on `@crediolabs/policy-synth` (the tool-body glue
@@ -82,6 +82,17 @@ export const VerifyPolicyToolShape = {
     validUntilLedger: z.number().int().positive().optional(),
     oraclePricesByAsset: z.record(z.string(), OraclePriceFixtureSchema).optional(),
 };
+/** 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
+ *  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(),
+    rpcUrl: z.string().url().optional(),
+    baseFee: z.number().int().positive().optional(),
+};
 /** Flat ZodRawShape for `install_policy`. `rule` is typed as `z.unknown()`
  *  at the tool boundary because the rule schema is a discriminated union
  *  the SDK does not accept at registration; the body re-validates
@@ -90,22 +101,24 @@ export const VerifyPolicyToolShape = {
  *  (the policy already carries the encoded predicate); the run-layer
  *  extracts them from there. */
 export const InstallPolicyToolShape = {
-    smartAccount: z.string().min(1).optional(),
-    sourceAccount: z.string().min(1).optional(),
+    ...SmartAccountToolShape,
     rule: z.unknown().optional(),
     installNonce: z.number().int().positive().optional(),
     interpreterAddress: z.string().optional(),
-    rpcUrl: z.string().url().optional(),
-    baseFee: z.number().int().positive().optional(),
 };
 /** Flat ZodRawShape for `revoke_policy`. */
 export const RevokePolicyToolShape = {
-    smartAccount: z.string().min(1).optional(),
-    sourceAccount: z.string().min(1).optional(),
+    ...SmartAccountToolShape,
     ruleId: z.number().int().nonnegative().optional(),
     interpreterAddress: z.string().optional(),
-    rpcUrl: z.string().url().optional(),
-    baseFee: z.number().int().positive().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

package/dist/src/server.js

@@ -1,4 +1,4 @@
-// apps/policy-builder-mcp/src/server.ts
+// packages/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
@@ -10,10 +10,15 @@
 // 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, runRecordTransaction, runRevokePolicy, runSimulatePolicy, runSynthesizePolicy, runVerifyPolicy, } from '@crediolabs/policy-synth/run';
+import { runGetInterpreterInfo, runInstallPolicy, runMergePolicy, runRecordTransaction, runRevokePolicy, runSimulatePolicy, runSynthesizePolicy, runVerifyPolicy, } from '@crediolabs/policy-synth/run';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { GetInterpreterInfoToolShape, InstallPolicyToolShape, RecordTransactionToolShape, RevokePolicyToolShape, SimulatePolicyToolShape, SynthesizePolicyToolShape, VerifyPolicyToolShape, } from "./schemas.js";
+import { GetInterpreterInfoToolShape, InstallPolicyToolShape, MergePolicyToolShape, 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
+ *  do not overlap. The runtime shapes match, so we assert through `unknown`
+ *  at the transport boundary - in one place, used by every tool. */
+const toCallToolResult = (res) => mcpResultFromCore(res);
 /** 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() {
@@ -23,36 +28,12 @@ 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, 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);
-    });
-    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, async (args) => {
-        const res = await runSimulatePolicy(args);
-        return mcpResultFromCore(res);
-    });
-    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, async (args) => {
-        const res = await runVerifyPolicy(args);
-        return mcpResultFromCore(res);
-    });
-    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, async (args) => {
-        const res = await runInstallPolicy(args);
-        return mcpResultFromCore(res);
-    });
-    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, async (args) => {
-        const res = await runRevokePolicy(args);
-        return mcpResultFromCore(res);
-    });
-    server.tool('get_interpreter_info', 'Read-only fingerprint lookup for the policy interpreter contract: returns the pinned address, grammar version, and wasm sha256 (from DEPLOYMENTS.md + 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, async (args) => {
-        const res = await runGetInterpreterInfo(args);
-        return mcpResultFromCore(res);
-    });
+    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('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/tools/result.js

@@ -1,4 +1,4 @@
-// apps/policy-builder-mcp/src/tools/result.ts
+// packages/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
@@ -15,14 +15,13 @@
 /** 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);
+    if (!res.ok)
+        return mcpErrorFromCore(res.error);
+    return {
+        isError: false,
+        content: [{ type: 'text', text: JSON.stringify(res.data) }],
+        structuredContent: res.data,
+    };
 }
 /** Map a core ToolError directly (for inputs that already failed validation
  *  inside the handler). */

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

@@ -3,6 +3,12 @@ export interface StartHttpServerOptions {
     host?: string;
     /** Path the server mounts the MCP endpoint at. Default `/mcp`. */
     path?: string;
+    /** Opt-in to binding a NON-loopback host (e.g. `0.0.0.0` to expose the
+     *  server on a LAN / public NIC). The MCP surface is unauthenticated, so
+     *  this is gated behind a flag: the default refuse-then-opt-in shape
+     *  keeps the security boundary auditable in code review. A caller that
+     *  sets this is taking responsibility for downstream auth / firewall. */
+    allowExternalHost?: boolean;
 }
 export interface RunningHttpServer {
     port: number;

package/dist/src/transports/http.js

@@ -1,28 +1,49 @@
-// apps/policy-builder-mcp/src/transports/http.ts
+// packages/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.
+// (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).
 //
 // 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.
+// Listens on 127.0.0.1 by default.
+//
+// SECURITY BOUNDARY: the MCP server has NO auth - any request is processed.
+// Binding to a non-loopback interface (e.g. `0.0.0.0`, `::`, an external
+// NIC) would expose that unauthenticated surface to every reachable host
+// (LAN peers, public cloud metadata, the open internet on a misconfigured
+// VPS). The host boundary is therefore FAIL-CLOSED: only loopback
+// (`127.0.0.1`, `::1`, `localhost`) is accepted by default. A caller that
+// KNOWS they want to expose the server MUST pass `allowExternalHost: true`
+// explicitly - the flag is the auditable intent. Test runners and the
+// in-process CLI client do not need it; they bind 127.0.0.1 already.
 import { createServer } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createMcpServer } from "../server.js";
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
 /** 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';
+    // Default-deny: refuse to bind a non-loopback host unless the caller has
+    // explicitly opted in. The MCP server has no auth, so the only thing
+    // standing between this binary and an open attack surface on `0.0.0.0` is
+    // this check; we would rather fail loudly here than silently expose it.
+    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();
-    // 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' });
@@ -68,6 +89,20 @@ 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.
+        const transport = new StreamableHTTPServerTransport();
+        const sdkTransport = transport;
+        await server.connect(sdkTransport);
         try {
             // `handleRequest` writes the response and returns once the message has
             // been dispatched. No shared state across calls in stateless mode.
@@ -76,7 +111,10 @@ export async function startHttpServer(opts) {
         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) {
+            if (res.headersSent) {
+                res.end();
+            }
+            else {
                 const error = {
                     code: 'SYNTHESIS_ERROR',
                     message: 'internal server error',
@@ -85,8 +123,14 @@ export async function startHttpServer(opts) {
                 };
                 sendJson(res, 500, { error });
             }
-            else
-                res.end();
+        }
+        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) => {
@@ -102,7 +146,6 @@ export async function startHttpServer(opts) {
         path,
         close: async () => {
             await new Promise((resolve) => httpServer.close(() => resolve()));
-            await transport.close().catch(() => { });
             await server.close().catch(() => { });
         },
     };

package/dist/src/transports/stdio.js

@@ -1,4 +1,4 @@
-// apps/policy-builder-mcp/src/transports/stdio.ts
+// packages/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