@ontrails/mcp 1.0.0-beta.0

package/dist/index.js

@@ -0,0 +1,13 @@
+// Build
+export { buildMcpTools, } from './build.js';
+// Tool naming
+export { deriveToolName } from './tool-name.js';
+// Annotations
+export { deriveAnnotations } from './annotations.js';
+// Progress
+export { createMcpProgressCallback } from './progress.js';
+// Blaze
+export { blaze } from './blaze.js';
+// Transport
+export { connectStdio } from './stdio.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,OAAO,EACL,aAAa,GAMd,MAAM,YAAY,CAAC;AAEpB,cAAc;AACd,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,cAAc;AACd,OAAO,EAAE,iBAAiB,EAAuB,MAAM,kBAAkB,CAAC;AAE1E,WAAW;AACX,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE1D,QAAQ;AACR,OAAO,EAAE,KAAK,EAAwB,MAAM,YAAY,CAAC;AAEzD,YAAY;AACZ,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/progress.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bridge Trails ProgressCallback to MCP sendProgress notifications.
+ */
+import type { ProgressCallback } from '@ontrails/core';
+import type { McpExtra } from './build.js';
+/**
+ * Create a ProgressCallback that bridges to MCP's sendProgress.
+ *
+ * Returns `undefined` if the MCP client did not provide a progressToken
+ * (meaning no progress reporting was requested).
+ */
+export declare const createMcpProgressCallback: (extra: McpExtra) => ProgressCallback | undefined;
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAiB,MAAM,gBAAgB,CAAC;AAEtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA6C3C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,OAAO,QAAQ,KACd,gBAAgB,GAAG,SAarB,CAAC"}

package/dist/progress.js

@@ -0,0 +1,51 @@
+/**
+ * Bridge Trails ProgressCallback to MCP sendProgress notifications.
+ */
+/** Fire-and-forget a progress send, swallowing transport errors. */
+const fireSend = async (send, current, total) => {
+    try {
+        await send(current, total);
+    }
+    catch {
+        /* Transport errors are expected and safe to ignore */
+    }
+};
+const handleProgress = (event, send) => {
+    if (event.current !== undefined && event.total !== undefined) {
+        fireSend(send, event.current, event.total);
+    }
+    else if (event.current !== undefined) {
+        fireSend(send, event.current, 0);
+    }
+};
+const progressHandlers = {
+    complete: (_event, send) => fireSend(send, 1, 1),
+    error: () => {
+        /* No progress notification for errors */
+    },
+    progress: handleProgress,
+    start: (_event, send) => fireSend(send, 0, 1),
+};
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a ProgressCallback that bridges to MCP's sendProgress.
+ *
+ * Returns `undefined` if the MCP client did not provide a progressToken
+ * (meaning no progress reporting was requested).
+ */
+export const createMcpProgressCallback = (extra) => {
+    if (extra.progressToken === undefined || extra.progressToken === null) {
+        return undefined;
+    }
+    if (typeof extra.sendProgress !== 'function') {
+        return undefined;
+    }
+    const send = extra.sendProgress;
+    return (event) => {
+        const handler = progressHandlers[event.type];
+        handler?.(event, send);
+    };
+};
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,oEAAoE;AACpE,MAAM,QAAQ,GAAG,KAAK,EACpB,IAAY,EACZ,OAAe,EACf,KAAa,EACE,EAAE;IACjB,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,sDAAsD;IACxD,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,KAAoB,EAAE,IAAY,EAAQ,EAAE;IAClE,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7D,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACvC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAGlB;IACF,QAAQ,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IAChD,KAAK,EAAE,GAAG,EAAE;QACV,yCAAyC;IAC3C,CAAC;IACD,QAAQ,EAAE,cAAc;IACxB,KAAK,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;CAC9C,CAAC;AAEF,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,KAAe,EACe,EAAE;IAChC,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS,IAAI,KAAK,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;QACtE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;QAC7C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC;IAChC,OAAO,CAAC,KAAoB,EAAQ,EAAE;QACpC,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC;AACJ,CAAC,CAAC"}

package/dist/stdio.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Thin wrapper around MCP SDK's StdioServerTransport.
+ *
+ * Exists as a separate function so it can be swapped for other transports
+ * (SSE, streamable HTTP) without changing blaze().
+ */
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/**
+ * Connect an MCP server to stdio transport.
+ */
+export declare const connectStdio: (server: Server) => Promise<void>;
+//# sourceMappingURL=stdio.d.ts.map

package/dist/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGxE;;GAEG;AACH,eAAO,MAAM,YAAY,GAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAG/D,CAAC"}

package/dist/stdio.js

@@ -0,0 +1,15 @@
+/**
+ * Thin wrapper around MCP SDK's StdioServerTransport.
+ *
+ * Exists as a separate function so it can be swapped for other transports
+ * (SSE, streamable HTTP) without changing blaze().
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+/**
+ * Connect an MCP server to stdio transport.
+ */
+export const connectStdio = async (server) => {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+};
+//# sourceMappingURL=stdio.js.map

package/dist/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAAE,MAAc,EAAiB,EAAE;IAClE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC,CAAC"}

package/dist/tool-name.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Derive MCP-safe tool names from app name + trail ID.
+ *
+ * MCP tool names must be [a-z0-9_]+. We prefix with the app name,
+ * replace dots and hyphens with underscores, and lowercase everything.
+ */
+/**
+ * Convert app name + trail ID to an MCP-safe tool name.
+ *
+ * @example
+ * deriveToolName("myapp", "entity.show") // "myapp_entity_show"
+ * deriveToolName("dispatch", "patch.search") // "dispatch_patch_search"
+ */
+export declare const deriveToolName: (appName: string, trailId: string) => string;
+//# sourceMappingURL=tool-name.d.ts.map

package/dist/tool-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name.d.ts","sourceRoot":"","sources":["../src/tool-name.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,KAAG,MAIjE,CAAC"}

package/dist/tool-name.js

@@ -0,0 +1,19 @@
+/**
+ * Derive MCP-safe tool names from app name + trail ID.
+ *
+ * MCP tool names must be [a-z0-9_]+. We prefix with the app name,
+ * replace dots and hyphens with underscores, and lowercase everything.
+ */
+/**
+ * Convert app name + trail ID to an MCP-safe tool name.
+ *
+ * @example
+ * deriveToolName("myapp", "entity.show") // "myapp_entity_show"
+ * deriveToolName("dispatch", "patch.search") // "dispatch_patch_search"
+ */
+export const deriveToolName = (appName, trailId) => {
+    const prefix = appName.toLowerCase().replaceAll(/[.-]/g, '_');
+    const suffix = trailId.toLowerCase().replaceAll(/[.-]/g, '_');
+    return `${prefix}_${suffix}`;
+};
+//# sourceMappingURL=tool-name.js.map

package/dist/tool-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name.js","sourceRoot":"","sources":["../src/tool-name.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAe,EAAE,OAAe,EAAU,EAAE;IACzE,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9D,OAAO,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAC/B,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@ontrails/mcp",
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "catalog:"
+  }
+}

package/src/__tests__/annotations.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from 'bun:test';
+
+import { deriveAnnotations } from '../annotations.js';
+
+describe('deriveAnnotations', () => {
+  test('readOnly trail produces readOnlyHint', () => {
+    const annotations = deriveAnnotations({ readOnly: true });
+    expect(annotations.readOnlyHint).toBe(true);
+    expect(annotations.destructiveHint).toBeUndefined();
+    expect(annotations.idempotentHint).toBeUndefined();
+  });
+
+  test('destructive trail produces destructiveHint', () => {
+    const annotations = deriveAnnotations({ destructive: true });
+    expect(annotations.destructiveHint).toBe(true);
+    expect(annotations.readOnlyHint).toBeUndefined();
+  });
+
+  test('idempotent trail produces idempotentHint', () => {
+    const annotations = deriveAnnotations({ idempotent: true });
+    expect(annotations.idempotentHint).toBe(true);
+  });
+
+  test('multiple markers combine correctly', () => {
+    const annotations = deriveAnnotations({
+      idempotent: true,
+      readOnly: true,
+    });
+    expect(annotations.readOnlyHint).toBe(true);
+    expect(annotations.idempotentHint).toBe(true);
+    expect(annotations.destructiveHint).toBeUndefined();
+  });
+
+  test('no markers produces empty annotations', () => {
+    const annotations = deriveAnnotations({});
+    expect(annotations.readOnlyHint).toBeUndefined();
+    expect(annotations.destructiveHint).toBeUndefined();
+    expect(annotations.idempotentHint).toBeUndefined();
+    expect(annotations.title).toBeUndefined();
+  });
+
+  test('description maps to title', () => {
+    const annotations = deriveAnnotations({
+      description: 'Show entity details',
+    });
+    expect(annotations.title).toBe('Show entity details');
+  });
+
+  test('all markers plus description', () => {
+    const annotations = deriveAnnotations({
+      description: 'A trail',
+      destructive: true,
+      idempotent: true,
+      readOnly: true,
+    });
+    expect(annotations.readOnlyHint).toBe(true);
+    expect(annotations.destructiveHint).toBe(true);
+    expect(annotations.idempotentHint).toBe(true);
+    expect(annotations.title).toBe('A trail');
+  });
+
+  test('false values are not included', () => {
+    const annotations = deriveAnnotations({
+      destructive: false,
+      readOnly: false,
+    });
+    expect(annotations.readOnlyHint).toBeUndefined();
+    expect(annotations.destructiveHint).toBeUndefined();
+  });
+});

package/src/__tests__/blaze.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Result, trail, topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { createMcpServer } from '../blaze.js';
+import { buildMcpTools } from '../build.js';
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+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 createIntegrationTools = () => {
+  const greetTrail = trail('greet', {
+    description: 'Greet someone',
+    implementation: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
+    input: z.object({ name: 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() }),
+  });
+
+  return buildMcpTools(topo('myapp', { deleteTrail, greetTrail }));
+};
+
+describe('blaze', () => {
+  test('createMcpServer registers tools that can be listed', () => {
+    const echoTrail = trail('echo', {
+      description: 'Echo',
+      implementation: (input) => Result.ok({ reply: input.message }),
+      input: z.object({ message: z.string() }),
+      readOnly: true,
+    });
+
+    const app = topo('testapp', { echoTrail });
+    const tools = buildMcpTools(app);
+    const server = createMcpServer(tools, {
+      name: 'testapp',
+      version: '0.1.0',
+    });
+
+    // Server is created successfully
+    expect(server).toBeDefined();
+  });
+
+  test('createMcpServer handles multiple tools', () => {
+    const echoTrail = trail('echo', {
+      description: 'Echo',
+      implementation: (input) => Result.ok({ reply: input.message }),
+      input: z.object({ message: z.string() }),
+    });
+
+    const searchTrail = trail('search', {
+      description: 'Search',
+      implementation: (input) => Result.ok({ results: [input.query] }),
+      input: z.object({ query: z.string() }),
+      readOnly: true,
+    });
+
+    const app = topo('testapp', { echoTrail, searchTrail });
+    const tools = buildMcpTools(app);
+
+    expect(tools).toHaveLength(2);
+
+    const server = createMcpServer(tools, {
+      name: 'testapp',
+      version: '0.1.0',
+    });
+    expect(server).toBeDefined();
+  });
+
+  test('buildMcpTools + createMcpServer integration', () => {
+    const tools = createIntegrationTools();
+    const names = tools.map((t) => t.name);
+    expect(names).toContain('myapp_greet');
+    expect(names).toContain('myapp_item_delete');
+
+    expect(requireTool(tools, 'myapp_greet').annotations?.readOnlyHint).toBe(
+      true
+    );
+    expect(
+      requireTool(tools, 'myapp_item_delete').annotations?.destructiveHint
+    ).toBe(true);
+
+    const server = createMcpServer(tools, {
+      name: 'myapp',
+      version: '1.0.0',
+    });
+    expect(server).toBeDefined();
+  });
+});