@ontrails/mcp 1.0.0-beta.0

package/src/blaze.ts

@@ -0,0 +1,146 @@
+/**
+ * blaze() -- the one-liner MCP server launcher.
+ *
+ * Three lines to expose trails as MCP tools:
+ *
+ * ```ts
+ * const app = topo("myapp", entity);
+ * await blaze(app);
+ * ```
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import type { Layer, Topo, TrailContext } from '@ontrails/core';
+
+import type { McpToolDefinition } from './build.js';
+import { buildMcpTools } from './build.js';
+import { connectStdio } from './stdio.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface BlazeMcpOptions {
+  readonly createContext?:
+    | (() => TrailContext | Promise<TrailContext>)
+    | undefined;
+  readonly excludeTrails?: readonly string[] | undefined;
+  readonly includeTrails?: readonly string[] | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  readonly serverInfo?:
+    | {
+        readonly name?: string | undefined;
+        readonly version?: string | undefined;
+      }
+    | undefined;
+  readonly transport?: 'stdio' | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Internal: create MCP server with tool handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an MCP Server instance and register all tools.
+ */
+export const createMcpServer = (
+  tools: McpToolDefinition[],
+  info: { readonly name: string; readonly version: string }
+): Server => {
+  const server = new Server(
+    { name: info.name, version: info.version },
+    { capabilities: { tools: {} } }
+  );
+
+  // Build a lookup map for tool dispatch
+  const toolMap = new Map<string, McpToolDefinition>();
+  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' as const,
+          },
+        ],
+        isError: true,
+      } as Record<string, unknown>;
+    }
+
+    const args = (request.params.arguments ?? {}) as Record<string, unknown>;
+    const progressToken = request.params._meta?.progressToken;
+
+    const sendProgress =
+      progressToken === undefined
+        ? undefined
+        : async (current: number, total: number) => {
+            await server.notification({
+              method: 'notifications/progress',
+              params: {
+                progress: current,
+                progressToken: progressToken,
+                total,
+              },
+            });
+          };
+
+    const extra = {
+      progressToken,
+      sendProgress,
+      signal: undefined as AbortSignal | undefined,
+    };
+
+    const result = await tool.handler(args, extra);
+    // Spread to satisfy MCP SDK's index-signature requirement
+    return { ...result } as Record<string, unknown>;
+  });
+
+  return server;
+};
+
+// ---------------------------------------------------------------------------
+// blaze
+// ---------------------------------------------------------------------------
+
+/**
+ * Build MCP tools from an App, create a server, and connect via stdio.
+ */
+export const blaze = async (
+  app: Topo,
+  options: BlazeMcpOptions = {}
+): Promise<void> => {
+  const tools = buildMcpTools(app, {
+    createContext: options.createContext,
+    excludeTrails: options.excludeTrails,
+    includeTrails: options.includeTrails,
+    layers: options.layers,
+  });
+
+  const server = createMcpServer(tools, {
+    name: options.serverInfo?.name ?? app.name,
+    version: options.serverInfo?.version ?? '0.1.0',
+  });
+
+  await connectStdio(server);
+};

package/src/build.ts

@@ -0,0 +1,321 @@
+/**
+ * Build MCP tool definitions from a Trails App.
+ *
+ * Iterates the topo, generates McpToolDefinition[] with handlers that
+ * validate input, compose layers, execute the implementation, and map
+ * Results to MCP responses.
+ */
+
+import {
+  composeLayers,
+  createTrailContext,
+  validateInput,
+  zodToJsonSchema,
+} from '@ontrails/core';
+import type { Layer, Topo, Trail, TrailContext } from '@ontrails/core';
+
+import type { McpAnnotations } from './annotations.js';
+import { deriveAnnotations } from './annotations.js';
+import { createMcpProgressCallback } from './progress.js';
+import { deriveToolName } from './tool-name.js';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface BuildMcpToolsOptions {
+  readonly createContext?:
+    | (() => TrailContext | Promise<TrailContext>)
+    | undefined;
+  readonly excludeTrails?: readonly string[] | undefined;
+  readonly includeTrails?: readonly string[] | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+}
+
+export interface McpToolDefinition {
+  readonly annotations: McpAnnotations | undefined;
+  readonly description: string | undefined;
+  readonly handler: (
+    args: Record<string, unknown>,
+    extra: McpExtra
+  ) => Promise<McpToolResult>;
+  readonly inputSchema: Record<string, unknown>;
+  readonly name: string;
+}
+
+export interface McpExtra {
+  readonly progressToken?: string | number | undefined;
+  readonly sendProgress?:
+    | ((current: number, total: number) => Promise<void>)
+    | undefined;
+  readonly signal?: AbortSignal | undefined;
+}
+
+export interface McpToolResult {
+  readonly content: readonly McpContent[];
+  readonly isError?: boolean | undefined;
+}
+
+export interface McpContent {
+  readonly data?: string | undefined;
+  readonly mimeType?: string | undefined;
+  readonly text?: string | undefined;
+  readonly type: 'text' | 'image' | 'resource';
+  readonly uri?: string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers (defined before use)
+// ---------------------------------------------------------------------------
+
+interface BlobRef {
+  readonly data: Uint8Array;
+  readonly kind: 'blob';
+  readonly mimeType: string;
+  readonly name?: string | undefined;
+}
+
+const isBlobRef = (value: unknown): value is BlobRef => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    obj['kind'] === 'blob' &&
+    obj['data'] instanceof Uint8Array &&
+    typeof obj['mimeType'] === 'string'
+  );
+};
+
+const uint8ArrayToBase64 = (bytes: Uint8Array): string => {
+  // Use btoa with manual conversion for runtime-agnostic base64
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCodePoint(byte);
+  }
+  return btoa(binary);
+};
+
+const blobToContent = (blob: BlobRef): McpContent => {
+  if (blob.mimeType.startsWith('image/')) {
+    return {
+      data: uint8ArrayToBase64(blob.data),
+      mimeType: blob.mimeType,
+      type: 'image',
+    };
+  }
+
+  return {
+    mimeType: blob.mimeType,
+    type: 'resource',
+    uri: `blob://${blob.name ?? 'unnamed'}`,
+  };
+};
+
+/** Separate blob fields from non-blob fields in an object. */
+const separateBlobFields = (
+  obj: Record<string, unknown>
+): {
+  blobContents: McpContent[];
+  hasBlobFields: boolean;
+  textFields: Record<string, unknown>;
+} => {
+  const blobContents: McpContent[] = [];
+  const textFields: Record<string, unknown> = {};
+  let hasBlobFields = false;
+  for (const [key, val] of Object.entries(obj)) {
+    if (isBlobRef(val)) {
+      hasBlobFields = true;
+      blobContents.push(blobToContent(val));
+    } else {
+      textFields[key] = val;
+    }
+  }
+  return { blobContents, hasBlobFields, textFields };
+};
+
+/** Serialize a mixed blob/text object to MCP content. */
+const serializeMixedObject = (
+  obj: Record<string, unknown>
+): readonly McpContent[] | undefined => {
+  const { blobContents, hasBlobFields, textFields } = separateBlobFields(obj);
+  if (!hasBlobFields) {
+    return undefined;
+  }
+  if (Object.keys(textFields).length > 0) {
+    blobContents.unshift({ text: JSON.stringify(textFields), type: 'text' });
+  }
+  return blobContents;
+};
+
+const serializeOutput = (value: unknown): readonly McpContent[] => {
+  if (isBlobRef(value)) {
+    return [blobToContent(value)];
+  }
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const mixed = serializeMixedObject(value as Record<string, unknown>);
+    if (mixed) {
+      return mixed;
+    }
+  }
+  return [{ text: JSON.stringify(value), type: 'text' }];
+};
+
+// ---------------------------------------------------------------------------
+// Handler factory
+// ---------------------------------------------------------------------------
+
+/** Create an error result for MCP responses. */
+const mcpError = (message: string): McpToolResult => ({
+  content: [{ text: message, type: 'text' }],
+  isError: true,
+});
+
+/** Build a TrailContext from options and MCP extra. */
+const buildTrailContext = async (
+  options: BuildMcpToolsOptions,
+  extra: McpExtra
+): Promise<TrailContext> => {
+  const baseContext =
+    options.createContext !== undefined && options.createContext !== null
+      ? await options.createContext()
+      : createTrailContext();
+
+  const signal = extra.signal ?? baseContext.signal;
+  const progressCb = createMcpProgressCallback(extra);
+
+  return {
+    ...baseContext,
+    signal,
+    ...(progressCb === undefined ? {} : { progress: progressCb }),
+  };
+};
+
+/** Execute a trail and map the result to an MCP response. */
+const executeAndMap = async (
+  trail: Trail<unknown, unknown>,
+  validatedInput: unknown,
+  ctx: TrailContext,
+  layers: readonly Layer[]
+): Promise<McpToolResult> => {
+  const impl = composeLayers([...layers], trail, trail.implementation);
+  try {
+    const result = await impl(validatedInput, ctx);
+    if (result.isOk()) {
+      return { content: serializeOutput(result.value) };
+    }
+    return mcpError(result.error.message);
+  } catch (error: unknown) {
+    return mcpError(error instanceof Error ? error.message : String(error));
+  }
+};
+
+const createHandler =
+  (
+    trail: Trail<unknown, unknown>,
+    layers: readonly Layer[],
+    options: BuildMcpToolsOptions
+  ): ((
+    args: Record<string, unknown>,
+    extra: McpExtra
+  ) => Promise<McpToolResult>) =>
+  async (args, extra): Promise<McpToolResult> => {
+    const validated = validateInput(trail.input, args);
+    if (validated.isErr()) {
+      return mcpError(validated.error.message);
+    }
+    const ctx = await buildTrailContext(options, extra);
+    return executeAndMap(trail, validated.value, ctx, layers);
+  };
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build MCP tool definitions from an App's topology.
+ *
+ * Each trail in the topo becomes an McpToolDefinition with:
+ * - A derived tool name (app-prefixed, underscore-delimited)
+ * - JSON Schema input from zodToJsonSchema
+ * - MCP annotations from trail markers
+ * - A handler that validates, composes layers, executes, and maps results
+ */
+/** Check if a trail should be included based on markers and filters. */
+const shouldInclude = (
+  trail: Trail<unknown, unknown>,
+  options: BuildMcpToolsOptions
+): boolean => {
+  if (trail.markers?.['internal'] === true) {
+    return false;
+  }
+  if (options.includeTrails !== undefined && options.includeTrails.length > 0) {
+    return options.includeTrails.includes(trail.id);
+  }
+  if (
+    options.excludeTrails !== undefined &&
+    options.excludeTrails.includes(trail.id)
+  ) {
+    return false;
+  }
+  return true;
+};
+
+/** Build a description with optional example input appended. */
+const buildDescription = (
+  trail: Trail<unknown, unknown>
+): string | undefined => {
+  let { description } = trail;
+  if (
+    description !== undefined &&
+    trail.examples !== undefined &&
+    trail.examples.length > 0
+  ) {
+    const [firstExample] = trail.examples;
+    if (firstExample !== undefined) {
+      description = `${description}\n\nExample input: ${JSON.stringify(firstExample.input)}`;
+    }
+  }
+  return description;
+};
+
+/** Build a single MCP tool definition from a trail. */
+const buildToolDefinition = (
+  app: Topo,
+  trail: Trail<unknown, unknown>,
+  layers: readonly Layer[],
+  options: BuildMcpToolsOptions
+): McpToolDefinition => {
+  const rawAnnotations = deriveAnnotations(trail);
+  const annotations =
+    Object.keys(rawAnnotations).length > 0 ? rawAnnotations : undefined;
+  return {
+    annotations,
+    description: buildDescription(trail),
+    handler: createHandler(trail, layers, options),
+    inputSchema: zodToJsonSchema(trail.input),
+    name: deriveToolName(app.name, trail.id),
+  };
+};
+
+export const buildMcpTools = (
+  app: Topo,
+  options: BuildMcpToolsOptions = {}
+): McpToolDefinition[] => {
+  const layers = options.layers ?? [];
+  const tools: McpToolDefinition[] = [];
+
+  for (const item of app.list()) {
+    if (item.kind !== 'trail' && item.kind !== 'hike') {
+      continue;
+    }
+    if (!shouldInclude(item as Trail<unknown, unknown>, options)) {
+      continue;
+    }
+    tools.push(
+      buildToolDefinition(app, item as Trail<unknown, unknown>, layers, options)
+    );
+  }
+
+  return tools;
+};

package/src/index.ts

@@ -0,0 +1,24 @@
+// Build
+export {
+  buildMcpTools,
+  type BuildMcpToolsOptions,
+  type McpToolDefinition,
+  type McpToolResult,
+  type McpContent,
+  type McpExtra,
+} from './build.js';
+
+// Tool naming
+export { deriveToolName } from './tool-name.js';
+
+// Annotations
+export { deriveAnnotations, type McpAnnotations } from './annotations.js';
+
+// Progress
+export { createMcpProgressCallback } from './progress.js';
+
+// Blaze
+export { blaze, type BlazeMcpOptions } from './blaze.js';
+
+// Transport
+export { connectStdio } from './stdio.js';

package/src/progress.ts

@@ -0,0 +1,73 @@
+/**
+ * Bridge Trails ProgressCallback to MCP sendProgress notifications.
+ */
+
+import type { ProgressCallback, ProgressEvent } from '@ontrails/core';
+
+import type { McpExtra } from './build.js';
+
+// ---------------------------------------------------------------------------
+// Event handlers
+// ---------------------------------------------------------------------------
+
+type SendFn = (current: number, total: number) => Promise<void>;
+
+/** Fire-and-forget a progress send, swallowing transport errors. */
+const fireSend = async (
+  send: SendFn,
+  current: number,
+  total: number
+): Promise<void> => {
+  try {
+    await send(current, total);
+  } catch {
+    /* Transport errors are expected and safe to ignore */
+  }
+};
+
+const handleProgress = (event: ProgressEvent, send: SendFn): void => {
+  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: Record<
+  string,
+  (event: ProgressEvent, send: SendFn) => void
+> = {
+  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: McpExtra
+): ProgressCallback | undefined => {
+  if (extra.progressToken === undefined || extra.progressToken === null) {
+    return undefined;
+  }
+  if (typeof extra.sendProgress !== 'function') {
+    return undefined;
+  }
+
+  const send = extra.sendProgress;
+  return (event: ProgressEvent): void => {
+    const handler = progressHandlers[event.type];
+    handler?.(event, send);
+  };
+};

package/src/stdio.ts

@@ -0,0 +1,17 @@
+/**
+ * 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';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+/**
+ * Connect an MCP server to stdio transport.
+ */
+export const connectStdio = async (server: Server): Promise<void> => {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+};

package/src/tool-name.ts

@@ -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: string, trailId: string): string => {
+  const prefix = appName.toLowerCase().replaceAll(/[.-]/g, '_');
+  const suffix = trailId.toLowerCase().replaceAll(/[.-]/g, '_');
+  return `${prefix}_${suffix}`;
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/annotations.ts","./src/blaze.ts","./src/build.ts","./src/index.ts","./src/progress.ts","./src/stdio.ts","./src/tool-name.ts"],"version":"5.9.3"}