@ontrails/mcp 1.0.0-beta.0

package/src/__tests__/build.test.ts

@@ -0,0 +1,377 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result, 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';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const echoTrail = trail('echo', {
+  description: 'Echo a message back',
+  implementation: (input) => Result.ok({ reply: input.message }),
+  input: z.object({ message: z.string() }),
+  output: z.object({ reply: z.string() }),
+  readOnly: true,
+});
+
+const deleteTrail = trail('item.delete', {
+  description: 'Delete an item',
+  destructive: true,
+  implementation: (_input) => Result.ok({ deleted: true }),
+  input: z.object({ id: z.string() }),
+});
+
+const failTrail = trail('fail', {
+  description: 'Always fails',
+  implementation: (input) => Result.err(new Error(input.reason)),
+  input: z.object({ reason: z.string() }),
+});
+
+const exampleTrail = trail('with.examples', {
+  description: 'A trail with examples',
+  examples: [
+    {
+      expected: { greeting: 'hello world' },
+      input: { name: 'world' },
+      name: 'basic',
+    },
+  ],
+  implementation: (input) => Result.ok({ greeting: `hello ${input.name}` }),
+  input: z.object({ name: z.string() }),
+});
+
+const noExtra: McpExtra = {};
+
+const requireTool = (tools: ReturnType<typeof buildMcpTools>, name: string) => {
+  const tool = tools.find((entry) => entry.name === name);
+  expect(tool).toBeDefined();
+  if (!tool) {
+    throw new Error(`Expected tool: ${name}`);
+  }
+  return tool;
+};
+
+const requireOnlyTool = (tools: ReturnType<typeof buildMcpTools>) => {
+  expect(tools).toHaveLength(1);
+  const [tool] = tools;
+  expect(tool).toBeDefined();
+  if (!tool) {
+    throw new Error('Expected one MCP tool');
+  }
+  return tool;
+};
+
+const parseJsonContent = (
+  content: { readonly text?: string | undefined } | undefined
+): unknown => {
+  expect(content?.text).toBeDefined();
+  return JSON.parse(content?.text ?? 'null');
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('buildMcpTools', () => {
+  describe('discovery', () => {
+    test('builds tools from a single-trail app', () => {
+      const app = topo('myapp', { echoTrail });
+      const tools = buildMcpTools(app);
+
+      expect(tools).toHaveLength(1);
+      expect(requireOnlyTool(tools).name).toBe('myapp_echo');
+    });
+
+    test('builds tools from a multi-trail app', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
+      const tools = buildMcpTools(app);
+
+      expect(tools).toHaveLength(3);
+      const names = tools.map((t) => t.name);
+      expect(names).toContain('myapp_echo');
+      expect(names).toContain('myapp_item_delete');
+      expect(names).toContain('myapp_fail');
+    });
+
+    test('tool names follow derivation rules', () => {
+      const app = topo('myapp', { deleteTrail });
+      const tools = buildMcpTools(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;
+
+      expect(schema['type']).toBe('object');
+      expect(schema['properties']).toBeDefined();
+      const props = schema['properties'] as Record<string, unknown>;
+      expect(props['message']).toEqual({ type: 'string' });
+    });
+
+    test('annotations are correctly derived', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail });
+      const tools = buildMcpTools(app);
+
+      expect(requireTool(tools, 'myapp_echo').annotations?.readOnlyHint).toBe(
+        true
+      );
+      expect(requireTool(tools, 'myapp_echo').annotations?.title).toBe(
+        'Echo a message back'
+      );
+      expect(
+        requireTool(tools, 'myapp_item_delete').annotations?.destructiveHint
+      ).toBe(true);
+    });
+  });
+
+  describe('handler execution', () => {
+    test('handler validates input and returns isError on invalid', async () => {
+      const app = topo('myapp', { echoTrail });
+      const tool = requireOnlyTool(buildMcpTools(app));
+
+      const result = await tool.handler({ notMessage: 123 }, noExtra);
+      expect(result?.isError).toBe(true);
+      expect(result?.content[0]?.type).toBe('text');
+      expect(result?.content[0]?.text).toBeDefined();
+    });
+
+    test('handler calls implementation and returns result as text content', async () => {
+      const app = topo('myapp', { echoTrail });
+      const tool = requireOnlyTool(buildMcpTools(app));
+
+      const result = await tool.handler({ message: 'hello' }, noExtra);
+      expect(result?.isError).toBeUndefined();
+      expect(result?.content[0]?.type).toBe('text');
+      expect(parseJsonContent(result?.content[0])).toEqual({
+        reply: 'hello',
+      });
+    });
+
+    test('handler maps errors to isError content', async () => {
+      const app = topo('myapp', { failTrail });
+      const tool = requireOnlyTool(buildMcpTools(app));
+
+      const result = await tool.handler({ reason: 'broken' }, noExtra);
+      expect(result?.isError).toBe(true);
+      expect(result?.content[0]?.text).toBe('broken');
+    });
+
+    test('handler catches thrown exceptions', async () => {
+      const throwTrail = trail('throw', {
+        implementation: () => {
+          throw new Error('unexpected crash');
+        },
+        input: z.object({}),
+      });
+
+      const tool = requireOnlyTool(
+        buildMcpTools(topo('myapp', { throwTrail }))
+      );
+      const result = await tool.handler({}, noExtra);
+
+      expect(result?.isError).toBe(true);
+      expect(result?.content[0]?.text).toBe('unexpected crash');
+    });
+  });
+
+  describe('filters', () => {
+    test('include filter limits which trails become tools', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
+      const tools = buildMcpTools(app, {
+        includeTrails: ['echo'],
+      });
+
+      expect(tools).toHaveLength(1);
+      expect(requireOnlyTool(tools).name).toBe('myapp_echo');
+    });
+
+    test('exclude filter removes specific trails', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
+      const tools = buildMcpTools(app, {
+        excludeTrails: ['fail'],
+      });
+
+      expect(tools).toHaveLength(2);
+      const names = tools.map((t) => t.name);
+      expect(names).not.toContain('myapp_fail');
+    });
+
+    test('include takes precedence over exclude', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
+      const tools = buildMcpTools(app, {
+        excludeTrails: ['fail'],
+        includeTrails: ['echo', 'fail'],
+      });
+
+      expect(tools).toHaveLength(2);
+      const names = tools.map((t) => t.name);
+      expect(names).toContain('myapp_echo');
+      expect(names).toContain('myapp_fail');
+    });
+  });
+
+  describe('composition', () => {
+    test('layers compose and execute around the implementation', async () => {
+      const calls: string[] = [];
+
+      const testLayer: Layer = {
+        name: 'test-layer',
+        wrap(_trail, impl) {
+          return async (input, ctx) => {
+            calls.push('before');
+            const result = await impl(input, ctx);
+            calls.push('after');
+            return result;
+          };
+        },
+      };
+
+      const app = topo('myapp', { echoTrail });
+      const tool = requireOnlyTool(buildMcpTools(app, { layers: [testLayer] }));
+
+      await tool.handler({ message: 'hi' }, noExtra);
+      expect(calls).toEqual(['before', 'after']);
+    });
+
+    test('AbortSignal propagates from MCP extra to TrailContext', async () => {
+      let capturedSignal: AbortSignal | undefined;
+
+      const signalTrail = trail('signal.check', {
+        implementation: (_input, ctx) => {
+          capturedSignal = ctx.signal;
+          return Result.ok({ ok: true });
+        },
+        input: z.object({}),
+      });
+
+      const controller = new AbortController();
+      const tool = requireOnlyTool(
+        buildMcpTools(topo('myapp', { signalTrail }))
+      );
+
+      await tool.handler({}, { signal: controller.signal });
+      expect(capturedSignal).toBe(controller.signal);
+    });
+
+    test('description includes first example input when present', () => {
+      const app = topo('myapp', { exampleTrail });
+      const tool = requireOnlyTool(buildMcpTools(app));
+
+      expect(tool.description).toContain('A trail with examples');
+      expect(tool.description).toContain('"name":"world"');
+    });
+
+    test('custom createContext is used when provided', async () => {
+      let contextUsed = false;
+
+      const ctxTrail = trail('ctx.check', {
+        implementation: (_input, ctx) => {
+          const ctxRecord = ctx as Record<string, unknown>;
+          contextUsed = ctxRecord['custom'] === true;
+          return Result.ok({ ok: true });
+        },
+        input: z.object({}),
+      });
+
+      const app = topo('myapp', { ctxTrail });
+      const tool = requireOnlyTool(
+        buildMcpTools(app, {
+          createContext: () => ({
+            custom: true,
+            requestId: 'test-id',
+            signal: new AbortController().signal,
+          }),
+        })
+      );
+
+      await tool.handler({}, noExtra);
+      expect(contextUsed).toBe(true);
+    });
+  });
+
+  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({}),
+      });
+
+      const tool = requireOnlyTool(buildMcpTools(topo('myapp', { blobTrail })));
+      const result = await tool.handler({}, noExtra);
+
+      expect(result?.content[0]?.type).toBe('image');
+      expect(result?.content[0]?.mimeType).toBe('image/png');
+      expect(result?.content[0]?.data).toBeDefined();
+    });
+
+    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({}),
+      });
+
+      const tool = requireOnlyTool(buildMcpTools(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');
+    });
+  });
+
+  describe('end-to-end', () => {
+    test('full pipeline from trail to MCP response', async () => {
+      const greetTrail = trail('greet', {
+        description: 'Greet someone',
+        idempotent: true,
+        implementation: (input) =>
+          Result.ok({ greeting: `Hello, ${input.name}!` }),
+        input: z.object({ name: z.string() }),
+        output: z.object({ greeting: z.string() }),
+        readOnly: true,
+      });
+
+      const tool = requireOnlyTool(
+        buildMcpTools(topo('testapp', { greetTrail }))
+      );
+
+      expect(tool).toMatchObject({
+        annotations: {
+          idempotentHint: true,
+          readOnlyHint: true,
+        },
+        description: 'Greet someone',
+        name: 'testapp_greet',
+      });
+      expect(tool.inputSchema['type']).toBe('object');
+
+      const successResult = await tool.handler({ name: 'World' }, noExtra);
+      expect(successResult?.isError).toBeUndefined();
+      expect(parseJsonContent(successResult?.content[0])).toEqual({
+        greeting: 'Hello, World!',
+      });
+
+      const errorResult = await tool.handler({}, noExtra);
+      expect(errorResult?.isError).toBe(true);
+    });
+  });
+});

package/src/__tests__/progress.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { McpExtra } from '../build.js';
+import { createMcpProgressCallback } from '../progress.js';
+
+describe('createMcpProgressCallback', () => {
+  test('returns undefined when no progressToken', () => {
+    const extra: McpExtra = {};
+    expect(createMcpProgressCallback(extra)).toBeUndefined();
+  });
+
+  test('returns undefined when no sendProgress function', () => {
+    const extra: McpExtra = { progressToken: 'tok-1' };
+    expect(createMcpProgressCallback(extra)).toBeUndefined();
+  });
+
+  test('sends 0/1 for start events', () => {
+    const calls: [number, number][] = [];
+    const extra: McpExtra = {
+      progressToken: 'tok-1',
+      sendProgress: (current, total) => {
+        calls.push([current, total]);
+        return Promise.resolve();
+      },
+    };
+
+    const cb = createMcpProgressCallback(extra);
+    expect(cb).toBeDefined();
+
+    const callback = cb as NonNullable<typeof cb>;
+    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
+    callback({
+      ts: new Date().toISOString(),
+      type: 'start',
+    });
+
+    expect(calls).toEqual([[0, 1]]);
+  });
+
+  test('sends progress notification for progress events', () => {
+    const calls: [number, number][] = [];
+    const extra: McpExtra = {
+      progressToken: 'tok-1',
+      sendProgress: (current, total) => {
+        calls.push([current, total]);
+        return Promise.resolve();
+      },
+    };
+
+    const cb = createMcpProgressCallback(extra);
+    expect(cb).toBeDefined();
+    const callback = cb as NonNullable<typeof cb>;
+
+    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
+    callback({
+      current: 5,
+      total: 10,
+      ts: new Date().toISOString(),
+      type: 'progress',
+    });
+
+    expect(calls).toEqual([[5, 10]]);
+  });
+
+  test('sends 1/1 for complete events', () => {
+    const calls: [number, number][] = [];
+    const extra: McpExtra = {
+      progressToken: 'tok-1',
+      sendProgress: (current, total) => {
+        calls.push([current, total]);
+        return Promise.resolve();
+      },
+    };
+
+    const cb = createMcpProgressCallback(extra);
+    expect(cb).toBeDefined();
+    const callback = cb as NonNullable<typeof cb>;
+
+    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
+    callback({
+      ts: new Date().toISOString(),
+      type: 'complete',
+    });
+
+    expect(calls).toEqual([[1, 1]]);
+  });
+
+  test('does not send for error events', () => {
+    const calls: [number, number][] = [];
+    const extra: McpExtra = {
+      progressToken: 'tok-1',
+      sendProgress: (current, total) => {
+        calls.push([current, total]);
+        return Promise.resolve();
+      },
+    };
+
+    const cb = createMcpProgressCallback(extra);
+    expect(cb).toBeDefined();
+    const callback = cb as NonNullable<typeof cb>;
+
+    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
+    callback({
+      message: 'something broke',
+      ts: new Date().toISOString(),
+      type: 'error',
+    });
+
+    expect(calls).toEqual([]);
+  });
+
+  test('handles missing total gracefully', () => {
+    const calls: [number, number][] = [];
+    const extra: McpExtra = {
+      progressToken: 'tok-1',
+      sendProgress: (current, total) => {
+        calls.push([current, total]);
+        return Promise.resolve();
+      },
+    };
+
+    const cb = createMcpProgressCallback(extra);
+    expect(cb).toBeDefined();
+    const callback = cb as NonNullable<typeof cb>;
+
+    // oxlint-disable-next-line prefer-await-to-callbacks -- not a node callback
+    callback({
+      current: 3,
+      ts: new Date().toISOString(),
+      type: 'progress',
+    });
+
+    // Sends current with 0 as indeterminate total
+    expect(calls).toEqual([[3, 0]]);
+  });
+});

package/src/__tests__/tool-name.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test';
+
+import { deriveToolName } from '../tool-name.js';
+
+describe('deriveToolName', () => {
+  test('replaces dots with underscores', () => {
+    expect(deriveToolName('myapp', 'entity.show')).toBe('myapp_entity_show');
+  });
+
+  test('prefixes with app name', () => {
+    expect(deriveToolName('myapp', 'search')).toBe('myapp_search');
+  });
+
+  test('handles multiple dots', () => {
+    expect(deriveToolName('myapp', 'entity.onboard')).toBe(
+      'myapp_entity_onboard'
+    );
+  });
+
+  test('replaces hyphens with underscores', () => {
+    expect(deriveToolName('my-app', 'some-trail')).toBe('my_app_some_trail');
+  });
+
+  test('lowercases everything', () => {
+    expect(deriveToolName('MyApp', 'Entity.Show')).toBe('myapp_entity_show');
+  });
+
+  test('handles single-segment trail IDs', () => {
+    expect(deriveToolName('dispatch', 'search')).toBe('dispatch_search');
+  });
+
+  test('handles dots in app name', () => {
+    expect(deriveToolName('my.app', 'trail')).toBe('my_app_trail');
+  });
+
+  test('matches spec examples', () => {
+    expect(deriveToolName('myapp', 'entity.show')).toBe('myapp_entity_show');
+    expect(deriveToolName('myapp', 'search')).toBe('myapp_search');
+    expect(deriveToolName('myapp', 'entity.onboard')).toBe(
+      'myapp_entity_onboard'
+    );
+    expect(deriveToolName('dispatch', 'patch.search')).toBe(
+      'dispatch_patch_search'
+    );
+  });
+});

package/src/annotations.ts

@@ -0,0 +1,51 @@
+/**
+ * Derive MCP tool annotations from trail spec markers.
+ */
+
+import type { Trail } from '@ontrails/core';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface McpAnnotations {
+  readonly readOnlyHint?: boolean | undefined;
+  readonly destructiveHint?: boolean | undefined;
+  readonly idempotentHint?: boolean | undefined;
+  readonly openWorldHint?: boolean | undefined;
+  readonly title?: string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Map trail spec fields to MCP tool annotations.
+ *
+ * Only sets hints that are explicitly declared on the trail.
+ * Omitted hints let the MCP SDK use its defaults.
+ */
+export const deriveAnnotations = (
+  trail: Pick<
+    Trail<unknown, unknown>,
+    'readOnly' | 'destructive' | 'idempotent' | 'description'
+  >
+): McpAnnotations => {
+  const annotations: Record<string, unknown> = {};
+
+  if (trail.readOnly === true) {
+    annotations['readOnlyHint'] = true;
+  }
+  if (trail.destructive === true) {
+    annotations['destructiveHint'] = true;
+  }
+  if (trail.idempotent === true) {
+    annotations['idempotentHint'] = true;
+  }
+  if (trail.description !== undefined) {
+    annotations['title'] = trail.description;
+  }
+
+  return annotations as McpAnnotations;
+};