@ontrails/mcp 1.0.0-beta.1 → 1.0.0-beta.11

package/src/__tests__/build.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, test } from 'bun:test';
 
-import { Result, trail, topo } from '@ontrails/core';
+import { Result, createBlobRef, service, trail, topo } from '@ontrails/core';
 import type { Layer } from '@ontrails/core';
 import { z } from 'zod';
 
 import { buildMcpTools } from '../build.js';
-import type { McpExtra } from '../build.js';
+import type { McpExtra, McpToolDefinition } from '../build.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -13,23 +13,23 @@ import type { McpExtra } from '../build.js';
 
 const echoTrail = trail('echo', {
   description: 'Echo a message back',
-  implementation: (input) => Result.ok({ reply: input.message }),
   input: z.object({ message: z.string() }),
+  intent: 'read',
   output: z.object({ reply: z.string() }),
-  readOnly: true,
+  run: (input) => Result.ok({ reply: input.message }),
 });
 
 const deleteTrail = trail('item.delete', {
   description: 'Delete an item',
-  destructive: true,
-  implementation: (_input) => Result.ok({ deleted: true }),
   input: z.object({ id: z.string() }),
+  intent: 'destroy',
+  run: (_input) => Result.ok({ deleted: true }),
 });
 
 const failTrail = trail('fail', {
   description: 'Always fails',
-  implementation: (input) => Result.err(new Error(input.reason)),
   input: z.object({ reason: z.string() }),
+  run: (input) => Result.err(new Error(input.reason)),
 });
 
 const exampleTrail = trail('with.examples', {
@@ -41,13 +41,20 @@ const exampleTrail = trail('with.examples', {
       name: 'basic',
     },
   ],
-  implementation: (input) => Result.ok({ greeting: `hello ${input.name}` }),
   input: z.object({ name: z.string() }),
+  run: (input) => Result.ok({ greeting: `hello ${input.name}` }),
+});
+
+const dbService = service('db.main', {
+  create: () =>
+    Result.ok({
+      source: 'factory',
+    }),
 });
 
 const noExtra: McpExtra = {};
 
-const requireTool = (tools: ReturnType<typeof buildMcpTools>, name: string) => {
+const requireTool = (tools: McpToolDefinition[], name: string) => {
   const tool = tools.find((entry) => entry.name === name);
   expect(tool).toBeDefined();
   if (!tool) {
@@ -56,7 +63,7 @@ const requireTool = (tools: ReturnType<typeof buildMcpTools>, name: string) => {
   return tool;
 };
 
-const requireOnlyTool = (tools: ReturnType<typeof buildMcpTools>) => {
+const requireOnlyTool = (tools: McpToolDefinition[]) => {
   expect(tools).toHaveLength(1);
   const [tool] = tools;
   expect(tool).toBeDefined();
@@ -66,6 +73,20 @@ const requireOnlyTool = (tools: ReturnType<typeof buildMcpTools>) => {
   return tool;
 };
 
+/**
+ * Unwrap buildMcpTools result for success-path tests.
+ * Throws if the result is an error so test failures surface clearly.
+ */
+const buildTools = (
+  ...args: Parameters<typeof buildMcpTools>
+): McpToolDefinition[] => {
+  const result = buildMcpTools(...args);
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
 const parseJsonContent = (
   content: { readonly text?: string | undefined } | undefined
 ): unknown => {
@@ -81,7 +102,7 @@ describe('buildMcpTools', () => {
   describe('discovery', () => {
     test('builds tools from a single-trail app', () => {
       const app = topo('myapp', { echoTrail });
-      const tools = buildMcpTools(app);
+      const tools = buildTools(app);
 
       expect(tools).toHaveLength(1);
       expect(requireOnlyTool(tools).name).toBe('myapp_echo');
@@ -89,7 +110,7 @@ describe('buildMcpTools', () => {
 
     test('builds tools from a multi-trail app', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
-      const tools = buildMcpTools(app);
+      const tools = buildTools(app);
 
       expect(tools).toHaveLength(3);
       const names = tools.map((t) => t.name);
@@ -100,14 +121,14 @@ describe('buildMcpTools', () => {
 
     test('tool names follow derivation rules', () => {
       const app = topo('myapp', { deleteTrail });
-      const tools = buildMcpTools(app);
+      const tools = buildTools(app);
 
       expect(requireOnlyTool(tools).name).toBe('myapp_item_delete');
     });
 
     test('input schema is valid JSON Schema', () => {
       const app = topo('myapp', { echoTrail });
-      const schema = requireOnlyTool(buildMcpTools(app)).inputSchema;
+      const schema = requireOnlyTool(buildTools(app)).inputSchema;
 
       expect(schema['type']).toBe('object');
       expect(schema['properties']).toBeDefined();
@@ -117,7 +138,7 @@ describe('buildMcpTools', () => {
 
     test('annotations are correctly derived', () => {
       const app = topo('myapp', { deleteTrail, echoTrail });
-      const tools = buildMcpTools(app);
+      const tools = buildTools(app);
 
       expect(requireTool(tools, 'myapp_echo').annotations?.readOnlyHint).toBe(
         true
@@ -129,12 +150,22 @@ describe('buildMcpTools', () => {
         requireTool(tools, 'myapp_item_delete').annotations?.destructiveHint
       ).toBe(true);
     });
+
+    test('trailId identifies the source trail', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail });
+      const tools = buildTools(app);
+
+      expect(requireTool(tools, 'myapp_echo').trailId).toBe('echo');
+      expect(requireTool(tools, 'myapp_item_delete').trailId).toBe(
+        'item.delete'
+      );
+    });
   });
 
   describe('handler execution', () => {
     test('handler validates input and returns isError on invalid', async () => {
       const app = topo('myapp', { echoTrail });
-      const tool = requireOnlyTool(buildMcpTools(app));
+      const tool = requireOnlyTool(buildTools(app));
 
       const result = await tool.handler({ notMessage: 123 }, noExtra);
       expect(result?.isError).toBe(true);
@@ -144,7 +175,7 @@ describe('buildMcpTools', () => {
 
     test('handler calls implementation and returns result as text content', async () => {
       const app = topo('myapp', { echoTrail });
-      const tool = requireOnlyTool(buildMcpTools(app));
+      const tool = requireOnlyTool(buildTools(app));
 
       const result = await tool.handler({ message: 'hello' }, noExtra);
       expect(result?.isError).toBeUndefined();
@@ -156,7 +187,7 @@ describe('buildMcpTools', () => {
 
     test('handler maps errors to isError content', async () => {
       const app = topo('myapp', { failTrail });
-      const tool = requireOnlyTool(buildMcpTools(app));
+      const tool = requireOnlyTool(buildTools(app));
 
       const result = await tool.handler({ reason: 'broken' }, noExtra);
       expect(result?.isError).toBe(true);
@@ -165,15 +196,13 @@ describe('buildMcpTools', () => {
 
     test('handler catches thrown exceptions', async () => {
       const throwTrail = trail('throw', {
-        implementation: () => {
+        input: z.object({}),
+        run: () => {
           throw new Error('unexpected crash');
         },
-        input: z.object({}),
       });
 
-      const tool = requireOnlyTool(
-        buildMcpTools(topo('myapp', { throwTrail }))
-      );
+      const tool = requireOnlyTool(buildTools(topo('myapp', { throwTrail })));
       const result = await tool.handler({}, noExtra);
 
       expect(result?.isError).toBe(true);
@@ -184,7 +213,7 @@ describe('buildMcpTools', () => {
   describe('filters', () => {
     test('include filter limits which trails become tools', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
-      const tools = buildMcpTools(app, {
+      const tools = buildTools(app, {
         includeTrails: ['echo'],
       });
 
@@ -194,7 +223,7 @@ describe('buildMcpTools', () => {
 
     test('exclude filter removes specific trails', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
-      const tools = buildMcpTools(app, {
+      const tools = buildTools(app, {
         excludeTrails: ['fail'],
       });
 
@@ -205,7 +234,7 @@ describe('buildMcpTools', () => {
 
     test('include takes precedence over exclude', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
-      const tools = buildMcpTools(app, {
+      const tools = buildTools(app, {
         excludeTrails: ['fail'],
         includeTrails: ['echo', 'fail'],
       });
@@ -234,7 +263,7 @@ describe('buildMcpTools', () => {
       };
 
       const app = topo('myapp', { echoTrail });
-      const tool = requireOnlyTool(buildMcpTools(app, { layers: [testLayer] }));
+      const tool = requireOnlyTool(buildTools(app, { layers: [testLayer] }));
 
       await tool.handler({ message: 'hi' }, noExtra);
       expect(calls).toEqual(['before', 'after']);
@@ -244,17 +273,15 @@ describe('buildMcpTools', () => {
       let capturedSignal: AbortSignal | undefined;
 
       const signalTrail = trail('signal.check', {
-        implementation: (_input, ctx) => {
+        input: z.object({}),
+        run: (_input, ctx) => {
           capturedSignal = ctx.signal;
           return Result.ok({ ok: true });
         },
-        input: z.object({}),
       });
 
       const controller = new AbortController();
-      const tool = requireOnlyTool(
-        buildMcpTools(topo('myapp', { signalTrail }))
-      );
+      const tool = requireOnlyTool(buildTools(topo('myapp', { signalTrail })));
 
       await tool.handler({}, { signal: controller.signal });
       expect(capturedSignal).toBe(controller.signal);
@@ -262,7 +289,7 @@ describe('buildMcpTools', () => {
 
     test('description includes first example input when present', () => {
       const app = topo('myapp', { exampleTrail });
-      const tool = requireOnlyTool(buildMcpTools(app));
+      const tool = requireOnlyTool(buildTools(app));
 
       expect(tool.description).toContain('A trail with examples');
       expect(tool.description).toContain('"name":"world"');
@@ -272,19 +299,18 @@ describe('buildMcpTools', () => {
       let contextUsed = false;
 
       const ctxTrail = trail('ctx.check', {
-        implementation: (_input, ctx) => {
-          const ctxRecord = ctx as Record<string, unknown>;
-          contextUsed = ctxRecord['custom'] === true;
+        input: z.object({}),
+        run: (_input, ctx) => {
+          contextUsed = ctx.extensions?.['custom'] === true;
           return Result.ok({ ok: true });
         },
-        input: z.object({}),
       });
 
       const app = topo('myapp', { ctxTrail });
       const tool = requireOnlyTool(
-        buildMcpTools(app, {
+        buildTools(app, {
           createContext: () => ({
-            custom: true,
+            extensions: { custom: true },
             requestId: 'test-id',
             signal: new AbortController().signal,
           }),
@@ -294,22 +320,46 @@ describe('buildMcpTools', () => {
       await tool.handler({}, noExtra);
       expect(contextUsed).toBe(true);
     });
+
+    test('service overrides are forwarded to executeTrail', async () => {
+      const serviceTrail = trail('service.check', {
+        input: z.object({}),
+        output: z.object({ source: z.string() }),
+        run: (_input, ctx) =>
+          Result.ok({ source: dbService.from(ctx).source as string }),
+        services: [dbService],
+      });
+
+      const tool = requireOnlyTool(
+        buildTools(topo('myapp', { serviceTrail }), {
+          services: { 'db.main': { source: 'override' } },
+        })
+      );
+
+      const result = await tool.handler({}, noExtra);
+      expect(result?.isError).toBeUndefined();
+      expect(parseJsonContent(result?.content[0])).toEqual({
+        source: 'override',
+      });
+    });
   });
 
   describe('blob outputs', () => {
     test('BlobRef output converts to image content', async () => {
       const blobTrail = trail('blob.image', {
-        implementation: () =>
-          Result.ok({
-            data: new Uint8Array([1, 2, 3]),
-            kind: 'blob' as const,
-            mimeType: 'image/png',
-            name: 'test.png',
-          }),
         input: z.object({}),
+        run: () =>
+          Result.ok(
+            createBlobRef({
+              data: new Uint8Array([1, 2, 3]),
+              mimeType: 'image/png',
+              name: 'test.png',
+              size: 3,
+            })
+          ),
       });
 
-      const tool = requireOnlyTool(buildMcpTools(topo('myapp', { blobTrail })));
+      const tool = requireOnlyTool(buildTools(topo('myapp', { blobTrail })));
       const result = await tool.handler({}, noExtra);
 
       expect(result?.content[0]?.type).toBe('image');
@@ -319,23 +369,103 @@ describe('buildMcpTools', () => {
 
     test('BlobRef output converts to resource content for non-images', async () => {
       const blobTrail = trail('blob.file', {
-        implementation: () =>
-          Result.ok({
-            data: new Uint8Array([1, 2, 3]),
-            kind: 'blob' as const,
-            mimeType: 'application/pdf',
-            name: 'doc.pdf',
-          }),
         input: z.object({}),
+        run: () =>
+          Result.ok(
+            createBlobRef({
+              data: new Uint8Array([1, 2, 3]),
+              mimeType: 'application/pdf',
+              name: 'doc.pdf',
+              size: 3,
+            })
+          ),
       });
 
-      const tool = requireOnlyTool(buildMcpTools(topo('myapp', { blobTrail })));
+      const tool = requireOnlyTool(buildTools(topo('myapp', { blobTrail })));
       const result = await tool.handler({}, noExtra);
 
       expect(result?.content[0]?.type).toBe('resource');
       expect(result?.content[0]?.uri).toBe('blob://doc.pdf');
       expect(result?.content[0]?.mimeType).toBe('application/pdf');
     });
+
+    test('BlobRef with ReadableStream data is collected and serialized', async () => {
+      const bytes = new Uint8Array([10, 20, 30]);
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(bytes);
+          controller.close();
+        },
+      });
+      const blobTrail = trail('blob.stream', {
+        input: z.object({}),
+        run: () =>
+          Result.ok(
+            createBlobRef({
+              data: stream,
+              mimeType: 'image/gif',
+              name: 'anim.gif',
+              size: 3,
+            })
+          ),
+      });
+
+      const tool = requireOnlyTool(buildTools(topo('myapp', { blobTrail })));
+      const result = await tool.handler({}, noExtra);
+
+      expect(result?.content[0]?.type).toBe('image');
+      expect(result?.content[0]?.mimeType).toBe('image/gif');
+      expect(result?.content[0]?.data).toBeDefined();
+    });
+  });
+
+  describe('tool-name collision detection', () => {
+    test('returns Err on trails that produce the same derived tool name', () => {
+      const dotTrail = trail('foo.bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+      const underscoreTrail = trail('foo_bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+
+      const app = topo('myapp', { dotTrail, underscoreTrail });
+      const result = buildMcpTools(app);
+      expect(result.isErr()).toBe(true);
+      expect(result.error?.message).toMatch(/tool-name collision/i);
+    });
+
+    test('returns Err on trails where hyphen and underscore collide', () => {
+      const hyphenTrail = trail('foo-bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+      const underscoreTrail = trail('foo_bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+
+      const app = topo('myapp', { hyphenTrail, underscoreTrail });
+      const result = buildMcpTools(app);
+      expect(result.isErr()).toBe(true);
+      expect(result.error?.message).toMatch(/tool-name collision/i);
+    });
+
+    test('returns Ok when trail names are distinct after normalization', () => {
+      const fooTrail = trail('foo', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+      const barTrail = trail('bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+
+      const app = topo('myapp', { barTrail, fooTrail });
+      const result = buildMcpTools(app);
+      expect(result.isOk()).toBe(true);
+    });
   });
 
   describe('end-to-end', () => {
@@ -343,16 +473,13 @@ describe('buildMcpTools', () => {
       const greetTrail = trail('greet', {
         description: 'Greet someone',
         idempotent: true,
-        implementation: (input) =>
-          Result.ok({ greeting: `Hello, ${input.name}!` }),
         input: z.object({ name: z.string() }),
+        intent: 'read',
         output: z.object({ greeting: z.string() }),
-        readOnly: true,
+        run: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
       });
 
-      const tool = requireOnlyTool(
-        buildMcpTools(topo('testapp', { greetTrail }))
-      );
+      const tool = requireOnlyTool(buildTools(topo('testapp', { greetTrail })));
 
       expect(tool).toMatchObject({
         annotations: {

package/src/annotations.ts

@@ -1,8 +1,8 @@
 /**
- * Derive MCP tool annotations from trail spec markers.
+ * Derive MCP tool annotations from trail spec fields.
  */
 
-import type { Trail } from '@ontrails/core';
+import type { Intent, Trail } from '@ontrails/core';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -27,18 +27,18 @@ export interface McpAnnotations {
  * Omitted hints let the MCP SDK use its defaults.
  */
 export const deriveAnnotations = (
-  trail: Pick<
-    Trail<unknown, unknown>,
-    'readOnly' | 'destructive' | 'idempotent' | 'description'
-  >
+  trail: Pick<Trail<unknown, unknown>, 'intent' | 'idempotent' | 'description'>
 ): McpAnnotations => {
   const annotations: Record<string, unknown> = {};
 
-  if (trail.readOnly === true) {
-    annotations['readOnlyHint'] = true;
-  }
-  if (trail.destructive === true) {
-    annotations['destructiveHint'] = true;
+  const intentToHint: Partial<Record<Intent, string>> = {
+    destroy: 'destructiveHint',
+    read: 'readOnlyHint',
+  };
+
+  const hint = intentToHint[trail.intent];
+  if (hint) {
+    annotations[hint] = true;
   }
   if (trail.idempotent === true) {
     annotations['idempotentHint'] = true;

package/src/blaze.ts

@@ -14,7 +14,13 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import type { Layer, Topo, TrailContext } from '@ontrails/core';
+import type {
+  Layer,
+  ServiceOverrideMap,
+  Topo,
+  TrailContextInit,
+} from '@ontrails/core';
+import { validateTopo } from '@ontrails/core';
 
 import type { McpToolDefinition } from './build.js';
 import { buildMcpTools } from './build.js';
@@ -26,7 +32,7 @@ import { connectStdio } from './stdio.js';
 
 export interface BlazeMcpOptions {
   readonly createContext?:
-    | (() => TrailContext | Promise<TrailContext>)
+    | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
   readonly excludeTrails?: readonly string[] | undefined;
   readonly includeTrails?: readonly string[] | undefined;
@@ -38,6 +44,9 @@ export interface BlazeMcpOptions {
       }
     | undefined;
   readonly transport?: 'stdio' | undefined;
+  readonly services?: ServiceOverrideMap | undefined;
+  /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
+  readonly validate?: boolean | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -130,14 +139,26 @@ export const blaze = async (
   app: Topo,
   options: BlazeMcpOptions = {}
 ): Promise<void> => {
-  const tools = buildMcpTools(app, {
+  if (options.validate !== false) {
+    const validated = validateTopo(app);
+    if (validated.isErr()) {
+      throw validated.error;
+    }
+  }
+
+  const toolsResult = buildMcpTools(app, {
     createContext: options.createContext,
     excludeTrails: options.excludeTrails,
     includeTrails: options.includeTrails,
     layers: options.layers,
+    services: options.services,
   });
 
-  const server = createMcpServer(tools, {
+  if (toolsResult.isErr()) {
+    throw toolsResult.error;
+  }
+
+  const server = createMcpServer(toolsResult.value, {
     name: options.serverInfo?.name ?? app.name,
     version: options.serverInfo?.version ?? '0.1.0',
   });