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

package/dist/trailhead.js

@@ -0,0 +1,108 @@
+/**
+ * trailhead() -- the one-liner MCP server launcher.
+ *
+ * Three lines to expose trails as MCP tools:
+ *
+ * ```ts
+ * const app = topo("myapp", entity);
+ * await trailhead(app);
+ * ```
+ */
+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 { connectStdio } from './stdio.js';
+// ---------------------------------------------------------------------------
+// Internal: create MCP server with tool handlers
+// ---------------------------------------------------------------------------
+/**
+ * Create an MCP Server instance and register all tools.
+ */
+export const createMcpServer = (tools, info) => {
+    const server = new Server({ name: info.name, version: info.version }, { capabilities: { tools: {} } });
+    // Build a lookup map for tool dispatch
+    const toolMap = new Map();
+    for (const tool of tools) {
+        toolMap.set(tool.name, tool);
+    }
+    // Register tools/list handler
+    // oxlint-disable-next-line require-await -- MCP SDK requires async handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({
+            annotations: t.annotations,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            name: t.name,
+        })),
+    }));
+    // Register tools/call handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const tool = toolMap.get(request.params.name);
+        if (tool === undefined) {
+            return {
+                content: [
+                    {
+                        text: `Unknown tool: ${request.params.name}`,
+                        type: 'text',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const args = (request.params.arguments ?? {});
+        const progressToken = request.params._meta?.progressToken;
+        const sendProgress = progressToken === undefined
+            ? undefined
+            : async (current, total) => {
+                await server.notification({
+                    method: 'notifications/progress',
+                    params: {
+                        progress: current,
+                        progressToken: progressToken,
+                        total,
+                    },
+                });
+            };
+        const extra = {
+            abortSignal: undefined,
+            progressToken,
+            sendProgress,
+        };
+        const result = await tool.handler(args, extra);
+        // Spread to satisfy MCP SDK's index-signature requirement
+        return { ...result };
+    });
+    return server;
+};
+// ---------------------------------------------------------------------------
+// trailhead
+// ---------------------------------------------------------------------------
+/**
+ * Build MCP tools from an App, create a server, and connect via stdio.
+ */
+export const trailhead = async (app, options = {}) => {
+    if (options.validate !== false) {
+        const validated = validateTopo(app);
+        if (validated.isErr()) {
+            throw validated.error;
+        }
+    }
+    const toolsResult = buildMcpTools(app, {
+        configValues: options.configValues,
+        createContext: options.createContext,
+        excludeTrails: options.excludeTrails,
+        gates: options.gates,
+        includeTrails: options.includeTrails,
+        provisions: options.provisions,
+    });
+    if (toolsResult.isErr()) {
+        throw toolsResult.error;
+    }
+    const server = createMcpServer(toolsResult.value, {
+        name: options.serverInfo?.name ?? app.name,
+        version: options.serverInfo?.version ?? '0.1.0',
+    });
+    await connectStdio(server);
+};
+//# sourceMappingURL=trailhead.js.map

package/dist/trailhead.js.map

@@ -0,0 +1 @@
+{"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.11",
+  "version": "1.0.0-beta.13",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,7 +14,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.8"
+    "@ontrails/core": "^1.0.0-beta.12"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",

package/src/__tests__/build.test.ts

@@ -1,7 +1,14 @@
 import { describe, expect, test } from 'bun:test';
 
-import { Result, createBlobRef, service, trail, topo } from '@ontrails/core';
-import type { Layer } from '@ontrails/core';
+import {
+  Result,
+  TRAILHEAD_KEY,
+  createBlobRef,
+  provision,
+  trail,
+  topo,
+} from '@ontrails/core';
+import type { Gate } from '@ontrails/core';
 import { z } from 'zod';
 
 import { buildMcpTools } from '../build.js';
@@ -12,27 +19,28 @@ import type { McpExtra, McpToolDefinition } from '../build.js';
 // ---------------------------------------------------------------------------
 
 const echoTrail = trail('echo', {
+  blaze: (input) => Result.ok({ reply: input.message }),
   description: 'Echo a message back',
   input: z.object({ message: z.string() }),
   intent: 'read',
   output: z.object({ reply: z.string() }),
-  run: (input) => Result.ok({ reply: input.message }),
 });
 
 const deleteTrail = trail('item.delete', {
+  blaze: (_input) => Result.ok({ deleted: true }),
   description: 'Delete an item',
   input: z.object({ id: z.string() }),
   intent: 'destroy',
-  run: (_input) => Result.ok({ deleted: true }),
 });
 
 const failTrail = trail('fail', {
+  blaze: (input) => Result.err(new Error(input.reason)),
   description: 'Always fails',
   input: z.object({ reason: z.string() }),
-  run: (input) => Result.err(new Error(input.reason)),
 });
 
 const exampleTrail = trail('with.examples', {
+  blaze: (input) => Result.ok({ greeting: `hello ${input.name}` }),
   description: 'A trail with examples',
   examples: [
     {
@@ -42,10 +50,9 @@ const exampleTrail = trail('with.examples', {
     },
   ],
   input: z.object({ name: z.string() }),
-  run: (input) => Result.ok({ greeting: `hello ${input.name}` }),
 });
 
-const dbService = service('db.main', {
+const dbProvision = provision('db.main', {
   create: () =>
     Result.ok({
       source: 'factory',
@@ -75,7 +82,7 @@ const requireOnlyTool = (tools: McpToolDefinition[]) => {
 
 /**
  * Unwrap buildMcpTools result for success-path tests.
- * Throws if the result is an error so test failures surface clearly.
+ * Throws if the result is an error so test failures show up clearly.
  */
 const buildTools = (
   ...args: Parameters<typeof buildMcpTools>
@@ -196,10 +203,10 @@ describe('buildMcpTools', () => {
 
     test('handler catches thrown exceptions', async () => {
       const throwTrail = trail('throw', {
-        input: z.object({}),
-        run: () => {
+        blaze: () => {
           throw new Error('unexpected crash');
         },
+        input: z.object({}),
       });
 
       const tool = requireOnlyTool(buildTools(topo('myapp', { throwTrail })));
@@ -247,11 +254,11 @@ describe('buildMcpTools', () => {
   });
 
   describe('composition', () => {
-    test('layers compose and execute around the implementation', async () => {
+    test('gates compose and execute around the implementation', async () => {
       const calls: string[] = [];
 
-      const testLayer: Layer = {
-        name: 'test-layer',
+      const testGate: Gate = {
+        name: 'test-gate',
         wrap(_trail, impl) {
           return async (input, ctx) => {
             calls.push('before');
@@ -263,7 +270,7 @@ describe('buildMcpTools', () => {
       };
 
       const app = topo('myapp', { echoTrail });
-      const tool = requireOnlyTool(buildTools(app, { layers: [testLayer] }));
+      const tool = requireOnlyTool(buildTools(app, { gates: [testGate] }));
 
       await tool.handler({ message: 'hi' }, noExtra);
       expect(calls).toEqual(['before', 'after']);
@@ -273,17 +280,17 @@ describe('buildMcpTools', () => {
       let capturedSignal: AbortSignal | undefined;
 
       const signalTrail = trail('signal.check', {
-        input: z.object({}),
-        run: (_input, ctx) => {
-          capturedSignal = ctx.signal;
+        blaze: (_input, ctx) => {
+          capturedSignal = ctx.abortSignal;
           return Result.ok({ ok: true });
         },
+        input: z.object({}),
       });
 
       const controller = new AbortController();
       const tool = requireOnlyTool(buildTools(topo('myapp', { signalTrail })));
 
-      await tool.handler({}, { signal: controller.signal });
+      await tool.handler({}, { abortSignal: controller.signal });
       expect(capturedSignal).toBe(controller.signal);
     });
 
@@ -297,42 +304,45 @@ describe('buildMcpTools', () => {
 
     test('custom createContext is used when provided', async () => {
       let contextUsed = false;
+      let trailheadMarkerUsed = false;
 
       const ctxTrail = trail('ctx.check', {
-        input: z.object({}),
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           contextUsed = ctx.extensions?.['custom'] === true;
+          trailheadMarkerUsed = ctx.extensions?.[TRAILHEAD_KEY] === 'mcp';
           return Result.ok({ ok: true });
         },
+        input: z.object({}),
       });
 
       const app = topo('myapp', { ctxTrail });
       const tool = requireOnlyTool(
         buildTools(app, {
           createContext: () => ({
+            abortSignal: new AbortController().signal,
             extensions: { custom: true },
             requestId: 'test-id',
-            signal: new AbortController().signal,
           }),
         })
       );
 
       await tool.handler({}, noExtra);
       expect(contextUsed).toBe(true);
+      expect(trailheadMarkerUsed).toBe(true);
     });
 
-    test('service overrides are forwarded to executeTrail', async () => {
-      const serviceTrail = trail('service.check', {
+    test('provision overrides are forwarded to executeTrail', async () => {
+      const provisionTrail = trail('provision.check', {
+        blaze: (_input, ctx) =>
+          Result.ok({ source: dbProvision.from(ctx).source as string }),
         input: z.object({}),
         output: z.object({ source: z.string() }),
-        run: (_input, ctx) =>
-          Result.ok({ source: dbService.from(ctx).source as string }),
-        services: [dbService],
+        provisions: [dbProvision],
       });
 
       const tool = requireOnlyTool(
-        buildTools(topo('myapp', { serviceTrail }), {
-          services: { 'db.main': { source: 'override' } },
+        buildTools(topo('myapp', { provisionTrail }), {
+          provisions: { 'db.main': { source: 'override' } },
         })
       );
 
@@ -347,8 +357,7 @@ describe('buildMcpTools', () => {
   describe('blob outputs', () => {
     test('BlobRef output converts to image content', async () => {
       const blobTrail = trail('blob.image', {
-        input: z.object({}),
-        run: () =>
+        blaze: () =>
           Result.ok(
             createBlobRef({
               data: new Uint8Array([1, 2, 3]),
@@ -357,6 +366,7 @@ describe('buildMcpTools', () => {
               size: 3,
             })
           ),
+        input: z.object({}),
       });
 
       const tool = requireOnlyTool(buildTools(topo('myapp', { blobTrail })));
@@ -369,8 +379,7 @@ describe('buildMcpTools', () => {
 
     test('BlobRef output converts to resource content for non-images', async () => {
       const blobTrail = trail('blob.file', {
-        input: z.object({}),
-        run: () =>
+        blaze: () =>
           Result.ok(
             createBlobRef({
               data: new Uint8Array([1, 2, 3]),
@@ -379,6 +388,7 @@ describe('buildMcpTools', () => {
               size: 3,
             })
           ),
+        input: z.object({}),
       });
 
       const tool = requireOnlyTool(buildTools(topo('myapp', { blobTrail })));
@@ -398,8 +408,7 @@ describe('buildMcpTools', () => {
         },
       });
       const blobTrail = trail('blob.stream', {
-        input: z.object({}),
-        run: () =>
+        blaze: () =>
           Result.ok(
             createBlobRef({
               data: stream,
@@ -408,6 +417,7 @@ describe('buildMcpTools', () => {
               size: 3,
             })
           ),
+        input: z.object({}),
       });
 
       const tool = requireOnlyTool(buildTools(topo('myapp', { blobTrail })));
@@ -422,12 +432,12 @@ describe('buildMcpTools', () => {
   describe('tool-name collision detection', () => {
     test('returns Err on trails that produce the same derived tool name', () => {
       const dotTrail = trail('foo.bar', {
+        blaze: () => Result.ok({ ok: true }),
         input: z.object({}),
-        run: () => Result.ok({ ok: true }),
       });
       const underscoreTrail = trail('foo_bar', {
+        blaze: () => Result.ok({ ok: true }),
         input: z.object({}),
-        run: () => Result.ok({ ok: true }),
       });
 
       const app = topo('myapp', { dotTrail, underscoreTrail });
@@ -438,12 +448,12 @@ describe('buildMcpTools', () => {
 
     test('returns Err on trails where hyphen and underscore collide', () => {
       const hyphenTrail = trail('foo-bar', {
+        blaze: () => Result.ok({ ok: true }),
         input: z.object({}),
-        run: () => Result.ok({ ok: true }),
       });
       const underscoreTrail = trail('foo_bar', {
+        blaze: () => Result.ok({ ok: true }),
         input: z.object({}),
-        run: () => Result.ok({ ok: true }),
       });
 
       const app = topo('myapp', { hyphenTrail, underscoreTrail });
@@ -454,12 +464,12 @@ describe('buildMcpTools', () => {
 
     test('returns Ok when trail names are distinct after normalization', () => {
       const fooTrail = trail('foo', {
+        blaze: () => Result.ok({ ok: true }),
         input: z.object({}),
-        run: () => Result.ok({ ok: true }),
       });
       const barTrail = trail('bar', {
+        blaze: () => Result.ok({ ok: true }),
         input: z.object({}),
-        run: () => Result.ok({ ok: true }),
       });
 
       const app = topo('myapp', { barTrail, fooTrail });
@@ -471,12 +481,12 @@ describe('buildMcpTools', () => {
   describe('end-to-end', () => {
     test('full pipeline from trail to MCP response', async () => {
       const greetTrail = trail('greet', {
+        blaze: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
         description: 'Greet someone',
         idempotent: true,
         input: z.object({ name: z.string() }),
         intent: 'read',
         output: z.object({ greeting: z.string() }),
-        run: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
       });
 
       const tool = requireOnlyTool(buildTools(topo('testapp', { greetTrail })));

package/src/__tests__/{blaze.test.ts → trailhead.test.ts}

@@ -3,7 +3,7 @@ import { describe, expect, test } from 'bun:test';
 import { Result, trail, topo } from '@ontrails/core';
 import { z } from 'zod';
 
-import { blaze, createMcpServer } from '../blaze.js';
+import { trailhead, createMcpServer } from '../trailhead.js';
 import { buildMcpTools } from '../build.js';
 import type { McpToolDefinition } from '../build.js';
 
@@ -21,7 +21,7 @@ const requireTool = (tools: McpToolDefinition[], name: string) => {
 };
 
 /**
- * Unwrap buildMcpTools result, throwing on error so test failures surface clearly.
+ * Unwrap buildMcpTools result, throwing on error so test failures show up clearly.
  */
 const buildTools = (
   ...args: Parameters<typeof buildMcpTools>
@@ -35,44 +35,44 @@ const buildTools = (
 
 const createIntegrationTools = () => {
   const greetTrail = trail('greet', {
+    blaze: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
     description: 'Greet someone',
     input: z.object({ name: z.string() }),
     intent: 'read',
-    run: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
   });
 
   const deleteTrail = trail('item.delete', {
+    blaze: (_input) => Result.ok({ deleted: true }),
     description: 'Delete an item',
     input: z.object({ id: z.string() }),
     intent: 'destroy',
-    run: (_input) => Result.ok({ deleted: true }),
   });
 
   return buildTools(topo('myapp', { deleteTrail, greetTrail }));
 };
 
-describe('blaze', () => {
-  test('blaze throws on invalid topo', async () => {
+describe('trailhead', () => {
+  test('trailhead throws on invalid topo', async () => {
     const t = trail('broken', {
-      follow: ['nonexistent.trail'],
+      blaze: () => Result.ok({}),
+      crosses: ['nonexistent.trail'],
       input: z.object({}),
       output: z.object({}),
-      run: () => Result.ok({}),
     });
     const app = topo('test', { t });
-    await expect(blaze(app)).rejects.toThrow(/validation/i);
+    await expect(trailhead(app)).rejects.toThrow(/validation/i);
   });
 
-  test('blaze skips validation when validate: false', async () => {
+  test('trailhead skips validation when validate: false', async () => {
     const t = trail('broken', {
-      follow: ['nonexistent.trail'],
+      blaze: () => Result.ok({}),
+      crosses: ['nonexistent.trail'],
       input: z.object({}),
       output: z.object({}),
-      run: () => Result.ok({}),
     });
     const app = topo('test', { t });
     const result = await Promise.race([
-      blaze(app, { validate: false }).then(() => 'resolved' as const),
+      trailhead(app, { validate: false }).then(() => 'resolved' as const),
       // oxlint-disable-next-line avoid-new -- Promise constructor needed for setTimeout-based timeout
       new Promise<'timeout'>((resolve) => {
         setTimeout(() => {
@@ -83,20 +83,20 @@ describe('blaze', () => {
     expect(['resolved', 'timeout']).toContain(result);
   });
 
-  test('BlazeMcpOptions accepts service overrides', () => {
-    const opts: Parameters<typeof blaze>[1] = {
-      services: {},
+  test('TrailheadMcpOptions accepts provision overrides', () => {
+    const opts: Parameters<typeof trailhead>[1] = {
+      provisions: {},
       validate: false,
     };
-    expect(opts.services).toEqual({});
+    expect(opts.provisions).toEqual({});
   });
 
   test('createMcpServer registers tools that can be listed', () => {
     const echoTrail = trail('echo', {
+      blaze: (input) => Result.ok({ reply: input.message }),
       description: 'Echo',
       input: z.object({ message: z.string() }),
       intent: 'read',
-      run: (input) => Result.ok({ reply: input.message }),
     });
 
     const app = topo('testapp', { echoTrail });
@@ -112,16 +112,16 @@ describe('blaze', () => {
 
   test('createMcpServer handles multiple tools', () => {
     const echoTrail = trail('echo', {
+      blaze: (input) => Result.ok({ reply: input.message }),
       description: 'Echo',
       input: z.object({ message: z.string() }),
-      run: (input) => Result.ok({ reply: input.message }),
     });
 
     const searchTrail = trail('search', {
+      blaze: (input) => Result.ok({ results: [input.query] }),
       description: 'Search',
       input: z.object({ query: z.string() }),
       intent: 'read',
-      run: (input) => Result.ok({ results: [input.query] }),
     });
 
     const app = topo('testapp', { echoTrail, searchTrail });