@ontrails/mcp 1.0.0-beta.13 → 1.0.0-beta.15

package/dist/trailhead.d.ts

@@ -9,33 +9,49 @@
  * ```
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { Gate, ProvisionOverrideMap, Topo, TrailContextInit } from '@ontrails/core';
+import type { Intent, Layer, ResourceOverrideMap, Topo, TrailContextInit } from '@ontrails/core';
 import type { McpToolDefinition } from './build.js';
 export interface TrailheadMcpOptions {
-    /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
+    /** Config values for resources that declare a `config` schema, keyed by resource ID. */
     readonly configValues?: Readonly<Record<string, Record<string, unknown>>> | undefined;
     readonly createContext?: (() => TrailContextInit | Promise<TrailContextInit>) | undefined;
-    readonly excludeTrails?: readonly string[] | undefined;
-    readonly includeTrails?: readonly string[] | undefined;
-    readonly gates?: readonly Gate[] | undefined;
-    readonly provisions?: ProvisionOverrideMap | undefined;
-    readonly serverInfo?: {
-        readonly name?: string | undefined;
-        readonly version?: string | undefined;
-    } | undefined;
-    readonly transport?: 'stdio' | undefined;
+    readonly description?: string | undefined;
+    readonly exclude?: readonly string[] | undefined;
+    readonly include?: readonly string[] | undefined;
+    readonly intent?: readonly Intent[] | undefined;
+    readonly layers?: readonly Layer[] | undefined;
+    readonly name?: string | undefined;
+    readonly resources?: ResourceOverrideMap | undefined;
     /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
     readonly validate?: boolean | undefined;
+    readonly version?: string | undefined;
+}
+export type CreateServerOptions = TrailheadMcpOptions;
+export interface SurfaceMcpResult {
+    readonly close: () => Promise<void>;
 }
 /**
  * Create an MCP Server instance and register all tools.
+ *
+ * When provided, `info.description` is forwarded to the MCP SDK as the
+ * server's `instructions` field — the SDK's documented channel for
+ * "optional instructions describing how to use the server and its features."
  */
 export declare const createMcpServer: (tools: McpToolDefinition[], info: {
     readonly name: string;
     readonly version: string;
+    readonly description?: string | undefined;
 }) => Server;
 /**
- * Build MCP tools from an App, create a server, and connect via stdio.
+ * Build MCP tools from a topo and create an MCP server.
+ */
+export declare const createServer: (app: Topo, options?: CreateServerOptions) => Server;
+/**
+ * Build MCP tools from a topo, create a server, and connect via stdio.
+ */
+export declare const surface: (app: Topo, options?: TrailheadMcpOptions) => Promise<SurfaceMcpResult>;
+/**
+ * Build MCP tools from a topo, create a server, and connect via stdio.
  */
 export declare const trailhead: (app: Topo, options?: TrailheadMcpOptions) => Promise<void>;
 //# sourceMappingURL=trailhead.d.ts.map

package/dist/trailhead.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trailhead.d.ts","sourceRoot":"","sources":["../src/trailhead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EACV,IAAI,EACJ,oBAAoB,EACpB,IAAI,EACJ,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAQpD,MAAM,WAAW,mBAAmB;IAClC,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,CAAC,EAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjD,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,GACpD,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,UAAU,CAAC,EAChB;QACE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACvC,GACD,SAAS,CAAC;IACd,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAMD;;GAEG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,iBAAiB,EAAE,EAC1B,MAAM;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KACxD,MAmEF,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,IAAI,EACT,UAAS,mBAAwB,KAChC,OAAO,CAAC,IAAI,CA2Bd,CAAC"}
+{"version":3,"file":"trailhead.d.ts","sourceRoot":"","sources":["../src/trailhead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EACV,MAAM,EACN,KAAK,EACL,mBAAmB,EACnB,IAAI,EACJ,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAQpD,MAAM,WAAW,mBAAmB;IAClC,wFAAwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjD,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,GACpD,SAAS,CAAC;IACd,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACrD,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,iBAAiB,EAAE,EAC1B,MAAM;IACJ,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C,KACA,MAwEF,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,IAAI,EACT,UAAS,mBAAwB,KAChC,MAqBF,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,OAAO,GAClB,KAAK,IAAI,EACT,UAAS,mBAAwB,KAChC,OAAO,CAAC,gBAAgB,CAS1B,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,IAAI,EACT,UAAS,mBAAwB,KAChC,OAAO,CAAC,IAAI,CAEd,CAAC"}

package/dist/trailhead.js

@@ -10,17 +10,25 @@
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { validateTopo } from '@ontrails/core';
-import { buildMcpTools } from './build.js';
+import { deriveMcpTools } from './build.js';
 import { connectStdio } from './stdio.js';
 // ---------------------------------------------------------------------------
 // Internal: create MCP server with tool handlers
 // ---------------------------------------------------------------------------
 /**
  * Create an MCP Server instance and register all tools.
+ *
+ * When provided, `info.description` is forwarded to the MCP SDK as the
+ * server's `instructions` field — the SDK's documented channel for
+ * "optional instructions describing how to use the server and its features."
  */
 export const createMcpServer = (tools, info) => {
-    const server = new Server({ name: info.name, version: info.version }, { capabilities: { tools: {} } });
+    const server = new Server({ name: info.name, version: info.version }, {
+        capabilities: { tools: {} },
+        ...(info.description === undefined
+            ? {}
+            : { instructions: info.description }),
+    });
     // Build a lookup map for tool dispatch
     const toolMap = new Map();
     for (const tool of tools) {
@@ -76,33 +84,53 @@ export const createMcpServer = (tools, info) => {
     return server;
 };
 // ---------------------------------------------------------------------------
-// trailhead
+// createServer
 // ---------------------------------------------------------------------------
 /**
- * Build MCP tools from an App, create a server, and connect via stdio.
+ * Build MCP tools from a topo and create an MCP server.
  */
-export const trailhead = async (app, options = {}) => {
-    if (options.validate !== false) {
-        const validated = validateTopo(app);
-        if (validated.isErr()) {
-            throw validated.error;
-        }
-    }
-    const toolsResult = buildMcpTools(app, {
+export const createServer = (app, options = {}) => {
+    const toolsResult = deriveMcpTools(app, {
         configValues: options.configValues,
         createContext: options.createContext,
-        excludeTrails: options.excludeTrails,
-        gates: options.gates,
-        includeTrails: options.includeTrails,
-        provisions: options.provisions,
+        exclude: options.exclude,
+        include: options.include,
+        intent: options.intent,
+        layers: options.layers,
+        resources: options.resources,
+        validate: options.validate,
     });
     if (toolsResult.isErr()) {
         throw toolsResult.error;
     }
-    const server = createMcpServer(toolsResult.value, {
-        name: options.serverInfo?.name ?? app.name,
-        version: options.serverInfo?.version ?? '0.1.0',
+    return createMcpServer(toolsResult.value, {
+        description: options.description ?? app.description,
+        name: options.name ?? app.name,
+        version: options.version ?? app.version ?? '0.1.0',
     });
+};
+// ---------------------------------------------------------------------------
+// surface
+// ---------------------------------------------------------------------------
+/**
+ * Build MCP tools from a topo, create a server, and connect via stdio.
+ */
+export const surface = async (app, options = {}) => {
+    const server = createServer(app, options);
     await connectStdio(server);
+    return {
+        close: async () => {
+            await server.close();
+        },
+    };
+};
+// ---------------------------------------------------------------------------
+// trailhead
+// ---------------------------------------------------------------------------
+/**
+ * Build MCP tools from a topo, create a server, and connect via stdio.
+ */
+export const trailhead = async (app, options = {}) => {
+    await surface(app, options);
 };
 //# sourceMappingURL=trailhead.js.map

package/dist/trailhead.js.map

@@ -1 +1 @@
-{"version":3,"file":"trailhead.js","sourceRoot":"","sources":["../src/trailhead.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"trailhead.js","sourceRoot":"","sources":["../src/trailhead.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/mcp",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.15",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,7 +14,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.12"
+    "@ontrails/core": "^1.0.0-beta.14"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",

package/src/__tests__/build.test.ts

@@ -4,14 +4,15 @@ import {
   Result,
   TRAILHEAD_KEY,
   createBlobRef,
-  provision,
+  resource,
+  signal,
   trail,
   topo,
 } from '@ontrails/core';
-import type { Gate } from '@ontrails/core';
+import type { Layer, TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
-import { buildMcpTools } from '../build.js';
+import { deriveMcpTools } from '../build.js';
 import type { McpExtra, McpToolDefinition } from '../build.js';
 
 // ---------------------------------------------------------------------------
@@ -52,13 +53,30 @@ const exampleTrail = trail('with.examples', {
   input: z.object({ name: z.string() }),
 });
 
-const dbProvision = provision('db.main', {
+const internalTrail = trail('internal.secret', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  visibility: 'internal',
+});
+
+const dbResource = resource('db.main', {
   create: () =>
     Result.ok({
       source: 'factory',
     }),
 });
 
+const orderPlaced = signal('order.placed', {
+  payload: z.object({ orderId: z.string() }),
+});
+
+const requireFire = (fire: TrailContext['fire']) => {
+  if (!fire) {
+    throw new Error('Expected ctx.fire to be bound');
+  }
+  return fire;
+};
+
 const noExtra: McpExtra = {};
 
 const requireTool = (tools: McpToolDefinition[], name: string) => {
@@ -81,13 +99,13 @@ const requireOnlyTool = (tools: McpToolDefinition[]) => {
 };
 
 /**
- * Unwrap buildMcpTools result for success-path tests.
+ * Unwrap deriveMcpTools result for success-path tests.
  * Throws if the result is an error so test failures show up clearly.
  */
 const buildTools = (
-  ...args: Parameters<typeof buildMcpTools>
+  ...args: Parameters<typeof deriveMcpTools>
 ): McpToolDefinition[] => {
-  const result = buildMcpTools(...args);
+  const result = deriveMcpTools(...args);
   if (result.isErr()) {
     throw result.error;
   }
@@ -105,7 +123,7 @@ const parseJsonContent = (
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('buildMcpTools', () => {
+describe('deriveMcpTools', () => {
   describe('discovery', () => {
     test('builds tools from a single-trail app', () => {
       const app = topo('myapp', { echoTrail });
@@ -192,6 +210,60 @@ describe('buildMcpTools', () => {
       });
     });
 
+    test('passes topo to executeTrail so MCP-invoked producers can fan out', async () => {
+      const captured: string[] = [];
+      const consumer = trail('notify.email', {
+        blaze: (input: { orderId: string }) => {
+          captured.push(input.orderId);
+          return Result.ok({ delivered: true });
+        },
+        input: z.object({ orderId: z.string() }),
+        on: ['order.placed'],
+      });
+      const producer = trail('order.create', {
+        blaze: async (input: { orderId: string }, ctx) => {
+          const fired = await requireFire(ctx.fire)('order.placed', {
+            orderId: input.orderId,
+          });
+          return fired.match({
+            err: (error) => Result.err(error),
+            ok: () => Result.ok({ ok: true }),
+          });
+        },
+        fires: ['order.placed'],
+        input: z.object({ orderId: z.string() }),
+      });
+      const tool = requireTool(
+        buildTools(topo('signal-mcp', { consumer, orderPlaced, producer })),
+        'signal_mcp_order_create'
+      );
+
+      const result = await tool.handler({ orderId: 'o-mcp' }, noExtra);
+
+      expect(result.isError).toBeUndefined();
+      expect(captured).toEqual(['o-mcp']);
+    });
+
+    test('consumer trails with on: are not exposed as MCP tools', () => {
+      const consumer = trail('notify.email', {
+        blaze: () => Result.ok({ delivered: true }),
+        input: z.object({ orderId: z.string() }),
+        on: ['order.placed'],
+      });
+      const producer = trail('order.create', {
+        blaze: () => Result.ok({ ok: true }),
+        fires: ['order.placed'],
+        input: z.object({ orderId: z.string() }),
+      });
+      const tools = buildTools(
+        topo('signal-mcp', { consumer, orderPlaced, producer })
+      );
+      const toolNames = tools.map((t) => t.name);
+
+      expect(toolNames).toContain('signal_mcp_order_create');
+      expect(toolNames).not.toContain('signal_mcp_notify_email');
+    });
+
     test('handler maps errors to isError content', async () => {
       const app = topo('myapp', { failTrail });
       const tool = requireOnlyTool(buildTools(app));
@@ -221,7 +293,7 @@ describe('buildMcpTools', () => {
     test('include filter limits which trails become tools', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
       const tools = buildTools(app, {
-        includeTrails: ['echo'],
+        include: ['echo'],
       });
 
       expect(tools).toHaveLength(1);
@@ -231,7 +303,7 @@ describe('buildMcpTools', () => {
     test('exclude filter removes specific trails', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
       const tools = buildTools(app, {
-        excludeTrails: ['fail'],
+        exclude: ['fail'],
       });
 
       expect(tools).toHaveLength(2);
@@ -239,26 +311,73 @@ describe('buildMcpTools', () => {
       expect(names).not.toContain('myapp_fail');
     });
 
-    test('include takes precedence over exclude', () => {
+    test('exclude patterns apply before include narrowing', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
       const tools = buildTools(app, {
-        excludeTrails: ['fail'],
-        includeTrails: ['echo', 'fail'],
+        exclude: ['fail'],
+        include: ['echo', 'fail'],
       });
 
-      expect(tools).toHaveLength(2);
+      expect(tools).toHaveLength(1);
       const names = tools.map((t) => t.name);
       expect(names).toContain('myapp_echo');
-      expect(names).toContain('myapp_fail');
+      expect(names).not.toContain('myapp_fail');
+    });
+
+    test('exact include can expose an internal trail', () => {
+      const app = topo('myapp', { echoTrail, internalTrail });
+      const tools = buildTools(app, {
+        include: ['internal.secret'],
+      });
+
+      expect(tools.map((tool) => tool.trailId)).toEqual(['internal.secret']);
+    });
+
+    test('wildcard include does not expose internal trails', () => {
+      const app = topo('myapp', { echoTrail, internalTrail });
+      const tools = buildTools(app, {
+        include: ['**'],
+      });
+
+      expect(tools.map((tool) => tool.trailId)).toEqual(['echo']);
+    });
+
+    test('include narrows to a single trail and exclude drops another', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
+      const tools = buildTools(app, {
+        exclude: ['fail'],
+        include: ['echo'],
+      });
+
+      expect(tools.map((tool) => tool.trailId)).toEqual(['echo']);
+    });
+
+    test('intent filters narrow the tool list', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
+      const tools = buildTools(app, {
+        intent: ['read'],
+      });
+
+      expect(tools.map((tool) => tool.trailId)).toEqual(['echo']);
+    });
+
+    test('intent filters compose with include patterns using AND logic', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail });
+      const tools = buildTools(app, {
+        include: ['item.*', 'echo'],
+        intent: ['destroy'],
+      });
+
+      expect(tools.map((tool) => tool.trailId)).toEqual(['item.delete']);
     });
   });
 
   describe('composition', () => {
-    test('gates compose and execute around the implementation', async () => {
+    test('layers compose and execute around the implementation', async () => {
       const calls: string[] = [];
 
-      const testGate: Gate = {
-        name: 'test-gate',
+      const testGate: Layer = {
+        name: 'test-layer',
         wrap(_trail, impl) {
           return async (input, ctx) => {
             calls.push('before');
@@ -270,7 +389,7 @@ describe('buildMcpTools', () => {
       };
 
       const app = topo('myapp', { echoTrail });
-      const tool = requireOnlyTool(buildTools(app, { gates: [testGate] }));
+      const tool = requireOnlyTool(buildTools(app, { layers: [testGate] }));
 
       await tool.handler({ message: 'hi' }, noExtra);
       expect(calls).toEqual(['before', 'after']);
@@ -331,18 +450,18 @@ describe('buildMcpTools', () => {
       expect(trailheadMarkerUsed).toBe(true);
     });
 
-    test('provision overrides are forwarded to executeTrail', async () => {
-      const provisionTrail = trail('provision.check', {
+    test('resource overrides are forwarded to executeTrail', async () => {
+      const resourceTrail = trail('resource.check', {
         blaze: (_input, ctx) =>
-          Result.ok({ source: dbProvision.from(ctx).source as string }),
+          Result.ok({ source: dbResource.from(ctx).source as string }),
         input: z.object({}),
         output: z.object({ source: z.string() }),
-        provisions: [dbProvision],
+        resources: [dbResource],
       });
 
       const tool = requireOnlyTool(
-        buildTools(topo('myapp', { provisionTrail }), {
-          provisions: { 'db.main': { source: 'override' } },
+        buildTools(topo('myapp', { dbResource, resourceTrail }), {
+          resources: { 'db.main': { source: 'override' } },
         })
       );
 
@@ -441,7 +560,7 @@ describe('buildMcpTools', () => {
       });
 
       const app = topo('myapp', { dotTrail, underscoreTrail });
-      const result = buildMcpTools(app);
+      const result = deriveMcpTools(app);
       expect(result.isErr()).toBe(true);
       expect(result.error?.message).toMatch(/tool-name collision/i);
     });
@@ -457,7 +576,7 @@ describe('buildMcpTools', () => {
       });
 
       const app = topo('myapp', { hyphenTrail, underscoreTrail });
-      const result = buildMcpTools(app);
+      const result = deriveMcpTools(app);
       expect(result.isErr()).toBe(true);
       expect(result.error?.message).toMatch(/tool-name collision/i);
     });
@@ -473,7 +592,7 @@ describe('buildMcpTools', () => {
       });
 
       const app = topo('myapp', { barTrail, fooTrail });
-      const result = buildMcpTools(app);
+      const result = deriveMcpTools(app);
       expect(result.isOk()).toBe(true);
     });
   });
@@ -511,4 +630,19 @@ describe('buildMcpTools', () => {
       expect(errorResult?.isError).toBe(true);
     });
   });
+
+  describe('established graph enforcement', () => {
+    test('returns Err when draft contamination remains', () => {
+      const draftTrail = trail('entity.export', {
+        blaze: () => Result.ok({ ok: true }),
+        crosses: ['_draft.entity.prepare'],
+        input: z.object({}),
+      });
+
+      const result = deriveMcpTools(topo('myapp', { draftTrail }));
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error?.message).toMatch(/draft/i);
+    });
+  });
 });