@crediolabs/policy-builder-mcp 0.1.17 → 0.1.18

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,31 @@ 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.
+- The on-chain interpreter the policies target is **unaudited**; see the
+  [architecture document](https://github.com/untangledfinance/octogate/blob/main/docs/architecture.md).
 
 ## 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"]>;
@@ -1028,20 +1086,20 @@ 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>;
 };

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,16 @@ 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 `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
@@ -14,6 +14,11 @@ import { runGetInterpreterInfo, runInstallPolicy, runRecordTransaction, runRevok
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.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
+ *  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,11 @@ 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('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,4 +1,4 @@
-// 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
@@ -7,15 +7,33 @@
 //
 // 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.`);
+    }
     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.
@@ -76,7 +94,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 +106,6 @@ export async function startHttpServer(opts) {
                 };
                 sendJson(res, 500, { error });
             }
-            else
-                res.end();
         }
     });
     await new Promise((resolve, reject) => {

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

package/dist-cjs/src/index.js

@@ -1,5 +1,5 @@
 "use strict";
-// 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.
 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");

package/dist-cjs/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"]>;
@@ -1028,20 +1086,20 @@ 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>;
 };

package/dist-cjs/src/schemas.js

@@ -1,5 +1,5 @@
 "use strict";
-// 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
@@ -95,6 +95,17 @@ exports.VerifyPolicyToolShape = {
     validUntilLedger: zod_1.z.number().int().positive().optional(),
     oraclePricesByAsset: zod_1.z.record(zod_1.z.string(), run_1.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: zod_1.z.string().min(1).optional(),
+    sourceAccount: zod_1.z.string().min(1).optional(),
+    rpcUrl: zod_1.z.string().url().optional(),
+    baseFee: zod_1.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
@@ -103,22 +114,16 @@ exports.VerifyPolicyToolShape = {
  *  (the policy already carries the encoded predicate); the run-layer
  *  extracts them from there. */
 exports.InstallPolicyToolShape = {
-    smartAccount: zod_1.z.string().min(1).optional(),
-    sourceAccount: zod_1.z.string().min(1).optional(),
+    ...SmartAccountToolShape,
     rule: zod_1.z.unknown().optional(),
     installNonce: zod_1.z.number().int().positive().optional(),
     interpreterAddress: zod_1.z.string().optional(),
-    rpcUrl: zod_1.z.string().url().optional(),
-    baseFee: zod_1.z.number().int().positive().optional(),
 };
 /** Flat ZodRawShape for `revoke_policy`. */
 exports.RevokePolicyToolShape = {
-    smartAccount: zod_1.z.string().min(1).optional(),
-    sourceAccount: zod_1.z.string().min(1).optional(),
+    ...SmartAccountToolShape,
     ruleId: zod_1.z.number().int().nonnegative().optional(),
     interpreterAddress: zod_1.z.string().optional(),
-    rpcUrl: zod_1.z.string().url().optional(),
-    baseFee: zod_1.z.number().int().positive().optional(),
 };
 /** Flat ZodRawShape for `get_interpreter_info`. `verifyLive` triggers an
  *  optional RPC `grammar_version()` call so the caller can verify the

package/dist-cjs/src/server.js

@@ -1,5 +1,5 @@
 "use strict";
-// 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
@@ -18,6 +18,11 @@ const run_1 = require("@crediolabs/policy-synth/run");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const schemas_ts_1 = require("./schemas.js");
 const result_ts_1 = require("./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) => (0, result_ts_1.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). */
 function createMcpServer() {
@@ -27,36 +32,11 @@ function createMcpServer() {
 }
 /** Idempotent registration of the T1 tool set on the given server. */
 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.', schemas_ts_1.RecordTransactionToolShape, async (args) => {
-        const res = await (0, run_1.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 (0, result_ts_1.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.', schemas_ts_1.SynthesizePolicyToolShape, async (args) => {
-        const res = await (0, run_1.runSynthesizePolicy)(args);
-        return (0, result_ts_1.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.', schemas_ts_1.SimulatePolicyToolShape, async (args) => {
-        const res = await (0, run_1.runSimulatePolicy)(args);
-        return (0, result_ts_1.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.', schemas_ts_1.VerifyPolicyToolShape, async (args) => {
-        const res = await (0, run_1.runVerifyPolicy)(args);
-        return (0, result_ts_1.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.', schemas_ts_1.InstallPolicyToolShape, async (args) => {
-        const res = await (0, run_1.runInstallPolicy)(args);
-        return (0, result_ts_1.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.', schemas_ts_1.RevokePolicyToolShape, async (args) => {
-        const res = await (0, run_1.runRevokePolicy)(args);
-        return (0, result_ts_1.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.', schemas_ts_1.GetInterpreterInfoToolShape, async (args) => {
-        const res = await (0, run_1.runGetInterpreterInfo)(args);
-        return (0, result_ts_1.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.', schemas_ts_1.RecordTransactionToolShape, (args) => (0, run_1.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.', schemas_ts_1.SynthesizePolicyToolShape, (args) => (0, run_1.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.', schemas_ts_1.SimulatePolicyToolShape, (args) => (0, run_1.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.', schemas_ts_1.VerifyPolicyToolShape, (args) => (0, run_1.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.', schemas_ts_1.InstallPolicyToolShape, (args) => (0, run_1.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.', schemas_ts_1.RevokePolicyToolShape, (args) => (0, run_1.runRevokePolicy)(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.', schemas_ts_1.GetInterpreterInfoToolShape, (args) => (0, run_1.runGetInterpreterInfo)(args).then(toCallToolResult));
 }

package/dist-cjs/src/tools/result.js

@@ -1,5 +1,5 @@
 "use strict";
-// 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
@@ -19,14 +19,13 @@ exports.mcpErrorFromCore = mcpErrorFromCore;
 /** 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. */
 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-cjs/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-cjs/src/transports/http.js

@@ -1,5 +1,5 @@
 "use strict";
-// 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
@@ -8,17 +8,35 @@
 //
 // 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.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startHttpServer = startHttpServer;
 const node_http_1 = require("node:http");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const server_ts_1 = require("../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. */
 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.`);
+    }
     const server = (0, server_ts_1.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.
@@ -79,7 +97,10 @@ 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',
@@ -88,8 +109,6 @@ async function startHttpServer(opts) {
                 };
                 sendJson(res, 500, { error });
             }
-            else
-                res.end();
         }
     });
     await new Promise((resolve, reject) => {

package/dist-cjs/src/transports/stdio.js

@@ -1,5 +1,5 @@
 "use strict";
-// 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-builder-mcp",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "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",
@@ -63,7 +63,7 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@crediolabs/policy-synth": "0.1.16",
+    "@crediolabs/policy-synth": "0.1.18",
     "@modelcontextprotocol/sdk": "1.18.1",
     "@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,17 @@ 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 `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,6 +11,7 @@
 // shared mutable state across calls; nothing here caches, queues, or holds
 // key material.
 
+import type { ToolResponse } from '@crediolabs/policy-synth'
 import {
   runGetInterpreterInfo,
   runInstallPolicy,
@@ -33,6 +34,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 +59,48 @@ 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(
     '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,4 +1,4 @@
-// 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
@@ -7,18 +7,36 @@
 //
 // 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 { 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,6 +51,15 @@ 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.`
+    )
+  }
   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.
@@ -94,7 +121,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 +131,7 @@ export async function startHttpServer(opts: StartHttpServerOptions): Promise<Run
           retryable: false,
         }
         sendJson(res, 500, { error })
-      } else res.end()
+      }
     }
   })
 

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