@ontrails/mcp 0.2.0

package/src/index.ts

@@ -0,0 +1,52 @@
+// Build
+export {
+  MCP_TOOL_ERROR_META_KEY,
+  MCP_TOOL_EXAMPLES_META_KEY,
+  MCP_TOOL_DEFERRED_META_KEY,
+  MCP_TOOL_TRAILHEAD_META_KEY,
+  deriveMcpTools,
+  type DeriveMcpToolsOptions,
+  type McpSurfaceTrailheadDefinition,
+  type McpSurfaceTrailheadMap,
+  type McpSurfaceTrailheadTrailSelector,
+  type McpToolDefinition,
+  type McpToolResult,
+  type McpToolErrorMeta,
+  type McpContent,
+  type McpExtra,
+  type ResolveMcpPermit,
+  type ResolveMcpPermitInput,
+} from './build.js';
+
+// MCP resources
+export {
+  MCP_EXAMPLES_RESOURCE_PREFIX,
+  MCP_SURFACE_MAP_RESOURCE_URI,
+  MCP_TRAIL_RESOURCE_PREFIX,
+  buildMcpResources,
+  isMcpTrailheadTool,
+  type BuiltMcpResources,
+  type McpResourceContent,
+  type McpResourceDefinition,
+  type McpResourcesConfig,
+} from './resources.js';
+
+// Tool naming
+export { deriveToolName } from './tool-name.js';
+
+// Annotations
+export { deriveAnnotations, type McpAnnotations } from './annotations.js';
+
+// Progress
+export { createMcpProgressCallback } from './progress.js';
+
+// Surface
+export {
+  createServer,
+  surface,
+  type CreateServerOptions,
+  type SurfaceMcpResult,
+} from './surface.js';
+
+// Transport
+export { connectStdio } from './stdio.js';

package/src/progress.ts

@@ -0,0 +1,95 @@
+/**
+ * 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).
+ *
+ * @example
+ * ```ts
+ * import { createMcpProgressCallback, type McpExtra } from '@ontrails/mcp';
+ *
+ * const extra: McpExtra = {
+ *   progressToken: 'token-123',
+ *   sendProgress: async (current, total) => {
+ *     console.log(`progress ${current}/${total}`);
+ *   },
+ * };
+ *
+ * const progress = createMcpProgressCallback(extra);
+ * if (progress !== undefined) {
+ *   progress({
+ *     current: 0,
+ *     ts: new Date().toISOString(),
+ *     total: 1,
+ *     type: 'start',
+ *   });
+ * }
+ * ```
+ */
+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/resources.ts

@@ -0,0 +1,336 @@
+/**
+ * MCP resource rendering for cold Trails context.
+ */
+
+import { deriveStructuredTrailExamples } from '@ontrails/core';
+import type { Topo, Trail } from '@ontrails/core';
+
+import {
+  MCP_TOOL_DEFERRED_META_KEY,
+  MCP_TOOL_TRAILHEAD_META_KEY,
+} from './build.js';
+import type { McpToolDefinition } from './build.js';
+
+/**
+ * Resource URI used for the resolved MCP surface map.
+ *
+ * @example
+ * ```ts
+ * import { MCP_SURFACE_MAP_RESOURCE_URI } from '@ontrails/mcp';
+ *
+ * const surfaceMap = resources.read(MCP_SURFACE_MAP_RESOURCE_URI);
+ * ```
+ */
+export const MCP_SURFACE_MAP_RESOURCE_URI = 'trails://surface-map';
+
+/**
+ * Prefix used for trail example resources exposed through MCP.
+ *
+ * @example
+ * ```ts
+ * import { MCP_EXAMPLES_RESOURCE_PREFIX } from '@ontrails/mcp';
+ *
+ * const uri = `${MCP_EXAMPLES_RESOURCE_PREFIX}${encodeURIComponent('tasks.create')}`;
+ * ```
+ */
+export const MCP_EXAMPLES_RESOURCE_PREFIX = 'trails://examples/';
+
+/**
+ * Prefix used for trail graph fact resources exposed through MCP.
+ *
+ * @example
+ * ```ts
+ * import { MCP_TRAIL_RESOURCE_PREFIX } from '@ontrails/mcp';
+ *
+ * const uri = `${MCP_TRAIL_RESOURCE_PREFIX}${encodeURIComponent('tasks.create')}`;
+ * ```
+ */
+export const MCP_TRAIL_RESOURCE_PREFIX = 'trails://trail/';
+
+export interface McpResourceDefinition {
+  readonly uri: string;
+  readonly mimeType: string;
+  readonly name: string;
+  readonly description?: string | undefined;
+}
+
+export interface McpResourceContent {
+  readonly uri: string;
+  readonly mimeType: string;
+  readonly text: string;
+}
+
+export interface McpResourcesConfig {
+  readonly surfaceMap?: boolean | undefined;
+  readonly examples?: boolean | undefined;
+  readonly graph?: boolean | undefined;
+}
+
+export interface BuiltMcpResources {
+  readonly list: readonly McpResourceDefinition[];
+  readonly read: (uri: string) => McpResourceContent | undefined;
+}
+
+interface McpSurfaceMapTool {
+  readonly annotations: McpToolDefinition['annotations'];
+  readonly description: string | undefined;
+  readonly trailheadId?: string | undefined;
+  readonly inputSchema: Record<string, unknown>;
+  readonly memberTrailIds?: readonly string[] | undefined;
+  readonly name: string;
+  readonly outputSchema?: Record<string, unknown> | undefined;
+  readonly trailId?: string | undefined;
+  readonly versions?: McpToolDefinition['versions'];
+  readonly deferred?: true | undefined;
+}
+
+interface McpSurfaceMap {
+  readonly surface: 'mcp';
+  readonly tools: readonly McpSurfaceMapTool[];
+}
+
+interface McpTrailResource {
+  readonly trailId: string;
+  readonly description?: string | undefined;
+  readonly intent: Trail<unknown, unknown, unknown>['intent'];
+  readonly visibility: Trail<unknown, unknown, unknown>['visibility'];
+  readonly composes: readonly string[];
+  readonly resources: readonly string[];
+  readonly signals: {
+    readonly fires: readonly string[];
+    readonly on: readonly string[];
+  };
+  readonly surface: 'mcp';
+  readonly tools: readonly McpSurfaceMapTool[];
+}
+
+const asJson = (value: unknown): string =>
+  `${JSON.stringify(value, null, 2)}\n`;
+
+const renderSurfaceMapTool = (tool: McpToolDefinition): McpSurfaceMapTool => ({
+  annotations: tool.annotations,
+  description: tool.description,
+  inputSchema: tool.inputSchema,
+  name: tool.name,
+  ...(tool.trailheadId === undefined ? {} : { trailheadId: tool.trailheadId }),
+  ...(tool.memberTrailIds === undefined
+    ? {}
+    : { memberTrailIds: tool.memberTrailIds }),
+  ...(tool.outputSchema === undefined
+    ? {}
+    : { outputSchema: tool.outputSchema }),
+  ...(tool.trailId === undefined ? {} : { trailId: tool.trailId }),
+  ...(tool.versions === undefined ? {} : { versions: tool.versions }),
+  ...(tool._meta?.[MCP_TOOL_DEFERRED_META_KEY] === true
+    ? { deferred: true }
+    : {}),
+});
+
+const buildSurfaceMap = (
+  tools: readonly McpToolDefinition[]
+): McpSurfaceMap => ({
+  surface: 'mcp',
+  tools: tools.map(renderSurfaceMapTool),
+});
+
+const exposedTrailIds = (
+  tools: readonly McpToolDefinition[]
+): ReadonlySet<string> =>
+  new Set(
+    tools.flatMap((tool) => [
+      ...(tool.trailId === undefined ? [] : [tool.trailId]),
+      ...(tool.memberTrailIds ?? []),
+    ])
+  );
+
+const examplesUriForTrail = (trailId: string): string =>
+  `${MCP_EXAMPLES_RESOURCE_PREFIX}${encodeURIComponent(trailId)}`;
+
+const trailUriForTrail = (trailId: string): string =>
+  `${MCP_TRAIL_RESOURCE_PREFIX}${encodeURIComponent(trailId)}`;
+
+const buildExampleResource = (
+  trailItem: Trail<unknown, unknown, unknown>
+):
+  | {
+      readonly content: McpResourceContent;
+      readonly listing: McpResourceDefinition;
+    }
+  | undefined => {
+  const examples = deriveStructuredTrailExamples(trailItem.examples);
+  if (examples === undefined) {
+    return undefined;
+  }
+
+  const uri = examplesUriForTrail(trailItem.id);
+  return {
+    content: {
+      mimeType: 'application/json',
+      text: asJson({
+        examples,
+        trailId: trailItem.id,
+      }),
+      uri,
+    },
+    listing: {
+      description: `Structured examples for trail "${trailItem.id}".`,
+      mimeType: 'application/json',
+      name: `Trail examples: ${trailItem.id}`,
+      uri,
+    },
+  };
+};
+
+const buildExampleResources = (
+  graph: Topo,
+  tools: readonly McpToolDefinition[]
+): readonly {
+  readonly content: McpResourceContent;
+  readonly listing: McpResourceDefinition;
+}[] => {
+  const visibleTrailIds = exposedTrailIds(tools);
+  return graph
+    .list()
+    .filter((trailItem) => visibleTrailIds.has(trailItem.id))
+    .map((trailItem) =>
+      buildExampleResource(trailItem as Trail<unknown, unknown, unknown>)
+    )
+    .filter((resource) => resource !== undefined);
+};
+
+const resourceId = (
+  resource: Trail<unknown, unknown, unknown>['resources'][number]
+) => resource.id;
+
+const buildTrailGraphResource = (
+  trailItem: Trail<unknown, unknown, unknown>,
+  tools: readonly McpToolDefinition[]
+): {
+  readonly content: McpResourceContent;
+  readonly listing: McpResourceDefinition;
+} => {
+  const uri = trailUriForTrail(trailItem.id);
+  const surfaceTools = tools
+    .filter(
+      (tool) =>
+        tool.trailId === trailItem.id ||
+        tool.memberTrailIds?.includes(trailItem.id) === true
+    )
+    .map(renderSurfaceMapTool);
+  const payload: McpTrailResource = {
+    composes: trailItem.composes,
+    ...(trailItem.description === undefined
+      ? {}
+      : { description: trailItem.description }),
+    intent: trailItem.intent,
+    resources: trailItem.resources.map(resourceId),
+    signals: {
+      fires: trailItem.fires,
+      on: trailItem.on,
+    },
+    surface: 'mcp',
+    tools: surfaceTools,
+    trailId: trailItem.id,
+    visibility: trailItem.visibility,
+  };
+
+  return {
+    content: {
+      mimeType: 'application/json',
+      text: asJson(payload),
+      uri,
+    },
+    listing: {
+      description: `MCP-visible graph facts for trail "${trailItem.id}".`,
+      mimeType: 'application/json',
+      name: `Trail graph fact: ${trailItem.id}`,
+      uri,
+    },
+  };
+};
+
+const buildTrailGraphResources = (
+  graph: Topo,
+  tools: readonly McpToolDefinition[]
+): readonly {
+  readonly content: McpResourceContent;
+  readonly listing: McpResourceDefinition;
+}[] => {
+  const visibleTrailIds = exposedTrailIds(tools);
+  return graph
+    .list()
+    .filter((trailItem) => visibleTrailIds.has(trailItem.id))
+    .map((trailItem) =>
+      buildTrailGraphResource(
+        trailItem as Trail<unknown, unknown, unknown>,
+        tools
+      )
+    );
+};
+
+/**
+ * Build the cold-context MCP resources for a Trails graph and tool set.
+ *
+ * @example
+ * ```ts
+ * import { buildMcpResources, deriveMcpTools } from '@ontrails/mcp';
+ *
+ * const tools = deriveMcpTools(app).value;
+ * const resources = buildMcpResources(app, tools);
+ * ```
+ */
+export const buildMcpResources = (
+  graph: Topo,
+  tools: readonly McpToolDefinition[],
+  config: McpResourcesConfig = {}
+): BuiltMcpResources => {
+  const listings: McpResourceDefinition[] = [];
+  const contents = new Map<string, McpResourceContent>();
+
+  if (config.surfaceMap !== false) {
+    const surfaceMapListing = {
+      description: 'Resolved MCP surface rendering for this Trails app.',
+      mimeType: 'application/json',
+      name: 'Trails MCP surface map',
+      uri: MCP_SURFACE_MAP_RESOURCE_URI,
+    };
+    listings.push(surfaceMapListing);
+    contents.set(MCP_SURFACE_MAP_RESOURCE_URI, {
+      mimeType: 'application/json',
+      text: asJson(buildSurfaceMap(tools)),
+      uri: MCP_SURFACE_MAP_RESOURCE_URI,
+    });
+  }
+
+  if (config.examples !== false) {
+    for (const resource of buildExampleResources(graph, tools)) {
+      listings.push(resource.listing);
+      contents.set(resource.content.uri, resource.content);
+    }
+  }
+
+  if (config.graph === true) {
+    for (const resource of buildTrailGraphResources(graph, tools)) {
+      listings.push(resource.listing);
+      contents.set(resource.content.uri, resource.content);
+    }
+  }
+
+  return {
+    list: listings,
+    read: (uri) => contents.get(uri),
+  };
+};
+
+/**
+ * Return whether an MCP tool was rendered from a surface trailhead.
+ *
+ * @example
+ * ```ts
+ * import { isMcpTrailheadTool } from '@ontrails/mcp';
+ *
+ * const trailheadTools = tools.filter(isMcpTrailheadTool);
+ * ```
+ */
+export const isMcpTrailheadTool = (tool: McpToolDefinition): boolean =>
+  tool._meta?.[MCP_TOOL_TRAILHEAD_META_KEY] !== undefined;

package/src/stdio.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 surface().
+ */
+
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+/**
+ * Connect an MCP server to stdio transport.
+ *
+ * @example
+ * ```ts
+ * import { connectStdio, createServer } from '@ontrails/mcp';
+ *
+ * const server = createServer(graph);
+ * await connectStdio(server);
+ * ```
+ */
+export const connectStdio = async (server: Server): Promise<void> => {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+};