@crediolabs/policy-builder-mcp 0.1.17 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-builder-mcp",
-  "version": "0.1.17",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "MCP server exposing the OZ policy-synth core (record_transaction + synthesize_policy) over stdio and Streamable HTTP transports.",
   "type": "module",
@@ -12,12 +12,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/untangledfinance/oz-policy-builder.git",
-    "directory": "apps/policy-builder-mcp"
+    "url": "https://github.com/untangledfinance/octogate.git",
+    "directory": "packages/policy-builder-mcp"
   },
-  "homepage": "https://github.com/untangledfinance/oz-policy-builder#readme",
+  "homepage": "https://github.com/untangledfinance/octogate#readme",
   "bugs": {
-    "url": "https://github.com/untangledfinance/oz-policy-builder/issues"
+    "url": "https://github.com/untangledfinance/octogate/issues"
   },
   "keywords": [
     "stellar",
@@ -37,7 +37,6 @@
       "types": "./dist/src/index.d.ts",
       "bun": "./src/index.ts",
       "import": "./dist/src/index.js",
-      "require": "./dist-cjs/src/index.js",
       "default": "./dist/src/index.js"
     },
     "./package.json": "./package.json"
@@ -47,7 +46,6 @@
   },
   "files": [
     "dist",
-    "dist-cjs",
     "src",
     "!src/**/*.test.ts"
   ],
@@ -56,15 +54,13 @@
   },
   "scripts": {
     "test": "bun test",
-    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.build.cjs.json && node scripts/write-cjs-package-json.cjs",
-    "build:esm": "tsc -p tsconfig.build.json",
-    "build:cjs": "tsc -p tsconfig.build.cjs.json && node scripts/write-cjs-package-json.cjs",
+    "build": "tsc -p tsconfig.build.json",
     "prepublishOnly": "bun run build && bun test",
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@crediolabs/policy-synth": "0.1.16",
-    "@modelcontextprotocol/sdk": "1.18.1",
+    "@crediolabs/policy-synth": "0.2.0",
+    "@modelcontextprotocol/sdk": "1.26.0",
     "@stellar/stellar-sdk": "14.4.0",
     "zod": "3.25.76"
   },

package/src/index.ts

@@ -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 {
   type RunRecordTransactionInput,

package/src/schemas.ts

@@ -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
@@ -134,6 +134,18 @@ export type {
   VerifyPolicyInput,
 } 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
+ *  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
@@ -142,23 +154,26 @@ export type {
  *  (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(),
 } as const
 
 /** 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(),
+} 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

package/src/server.ts

@@ -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
@@ -11,9 +11,11 @@
 // shared mutable state across calls; nothing here caches, queues, or holds
 // key material.
 
+import type { ToolResponse } from '@crediolabs/policy-synth'
 import {
   runGetInterpreterInfo,
   runInstallPolicy,
+  runMergePolicy,
   runRecordTransaction,
   runRevokePolicy,
   runSimulatePolicy,
@@ -25,6 +27,7 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
 import {
   GetInterpreterInfoToolShape,
   InstallPolicyToolShape,
+  MergePolicyToolShape,
   RecordTransactionToolShape,
   RevokePolicyToolShape,
   SimulatePolicyToolShape,
@@ -33,6 +36,14 @@ import {
 } from './schemas.ts'
 import { mcpResultFromCore } from './tools/result.ts'
 
+/** 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 = <T>(
+  res: ToolResponse<T> | (ToolResponse<T> & Record<string, unknown>)
+): CallToolResult => mcpResultFromCore(res as ToolResponse<T>) as unknown as CallToolResult
+
 /** 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(): McpServer {
@@ -50,73 +61,55 @@ export function registerTools(server: McpServer): void {
     '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) as unknown as CallToolResult
-    }
+    (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,
-    async (args) => {
-      const res = await runSynthesizePolicy(args)
-      return mcpResultFromCore(res) as unknown as CallToolResult
-    }
+    (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,
-    async (args) => {
-      const res = await runSimulatePolicy(args)
-      return mcpResultFromCore(res) as unknown as CallToolResult
-    }
+    (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,
-    async (args) => {
-      const res = await runVerifyPolicy(args)
-      return mcpResultFromCore(res) as unknown as CallToolResult
-    }
+    (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,
-    async (args) => {
-      const res = await runInstallPolicy(args)
-      return mcpResultFromCore(res) as unknown as CallToolResult
-    }
+    (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,
-    async (args) => {
-      const res = await runRevokePolicy(args)
-      return mcpResultFromCore(res) as unknown as CallToolResult
-    }
+    (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 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.',
+    '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,
-    async (args) => {
-      const res = await runGetInterpreterInfo(args)
-      return mcpResultFromCore(res) as unknown as CallToolResult
-    }
+    (args) => runGetInterpreterInfo(args).then(toCallToolResult)
   )
 }

package/src/tools/result.ts

@@ -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
@@ -32,14 +32,12 @@ export type McpToolResult<T> = McpToolSuccess<T> | McpToolError
 /** 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<T>(res: ToolResponse<T>): McpToolResult<T> {
-  if (res.ok) {
-    return {
-      isError: false,
-      content: [{ type: 'text', text: JSON.stringify(res.data) }],
-      structuredContent: res.data,
-    }
+  if (!res.ok) return mcpErrorFromCore(res.error)
+  return {
+    isError: false,
+    content: [{ type: 'text', text: JSON.stringify(res.data) }],
+    structuredContent: res.data,
   }
-  return mcpErrorFromCore(res.error)
 }
 
 /** Map a core ToolError directly (for inputs that already failed validation

package/src/transports/http.ts

@@ -1,24 +1,48 @@
-// 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, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
 import type { ToolError } from '@crediolabs/policy-synth'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
 import { createMcpServer } from '../server.ts'
 
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost'])
+
 export interface StartHttpServerOptions {
   port: number
   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 {
@@ -33,13 +57,20 @@ export interface RunningHttpServer {
 export async function startHttpServer(opts: StartHttpServerOptions): Promise<RunningHttpServer> {
   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: Server = createServer(async (req, res) => {
     if (!req.url) {
@@ -87,6 +118,21 @@ 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.
+    const transport = new StreamableHTTPServerTransport()
+    const sdkTransport = transport as unknown as 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.
@@ -94,7 +140,9 @@ export async function startHttpServer(opts: StartHttpServerOptions): Promise<Run
     } 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: ToolError = {
           code: 'SYNTHESIS_ERROR',
           message: 'internal server error',
@@ -102,7 +150,14 @@ export async function startHttpServer(opts: StartHttpServerOptions): Promise<Run
           retryable: false,
         }
         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(() => {})
     }
   })
 
@@ -120,7 +175,6 @@ export async function startHttpServer(opts: StartHttpServerOptions): Promise<Run
     path,
     close: async () => {
       await new Promise<void>((resolve) => httpServer.close(() => resolve()))
-      await transport.close().catch(() => {})
       await server.close().catch(() => {})
     },
   }

package/src/transports/stdio.ts

@@ -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

package/dist-cjs/package.json

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

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

@@ -1,7 +0,0 @@
-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

@@ -1,20 +0,0 @@
-"use strict";
-// apps/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; } });