@ontrails/mcp 1.0.0-beta.2 → 1.0.0-beta.21

package/src/index.ts

@@ -1,13 +1,35 @@
 // Build
 export {
-  buildMcpTools,
-  type BuildMcpToolsOptions,
+  MCP_TOOL_ERROR_META_KEY,
+  MCP_TOOL_EXAMPLES_META_KEY,
+  MCP_TOOL_DEFERRED_META_KEY,
+  MCP_TOOL_FACET_META_KEY,
+  deriveMcpTools,
+  type DeriveMcpToolsOptions,
+  type McpSurfaceFacetDefinition,
+  type McpSurfaceFacetMap,
+  type McpSurfaceFacetTrailSelector,
   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,
+  buildMcpResources,
+  isMcpFacetTool,
+  type BuiltMcpResources,
+  type McpResourceContent,
+  type McpResourceDefinition,
+  type McpResourcesConfig,
+} from './resources.js';
+
 // Tool naming
 export { deriveToolName } from './tool-name.js';
 
@@ -17,8 +39,13 @@ export { deriveAnnotations, type McpAnnotations } from './annotations.js';
 // Progress
 export { createMcpProgressCallback } from './progress.js';
 
-// Blaze
-export { blaze, type BlazeMcpOptions } from './blaze.js';
+// Surface
+export {
+  createServer,
+  surface,
+  type CreateServerOptions,
+  type SurfaceMcpResult,
+} from './surface.js';
 
 // Transport
 export { connectStdio } from './stdio.js';

package/src/progress.ts

@@ -54,6 +54,28 @@ const progressHandlers: Record<
  *
  * 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

package/src/resources.ts

@@ -0,0 +1,228 @@
+/**
+ * MCP resource projection for cold Trails context.
+ */
+
+import { deriveStructuredTrailExamples } from '@ontrails/core';
+import type { Topo, Trail } from '@ontrails/core';
+
+import {
+  MCP_TOOL_DEFERRED_META_KEY,
+  MCP_TOOL_FACET_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/';
+
+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;
+}
+
+export interface BuiltMcpResources {
+  readonly list: readonly McpResourceDefinition[];
+  readonly read: (uri: string) => McpResourceContent | undefined;
+}
+
+interface McpSurfaceMapTool {
+  readonly annotations: McpToolDefinition['annotations'];
+  readonly description: string | undefined;
+  readonly facetId?: 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[];
+}
+
+const asJson = (value: unknown): string =>
+  `${JSON.stringify(value, null, 2)}\n`;
+
+const projectSurfaceMapTool = (tool: McpToolDefinition): McpSurfaceMapTool => ({
+  annotations: tool.annotations,
+  description: tool.description,
+  inputSchema: tool.inputSchema,
+  name: tool.name,
+  ...(tool.facetId === undefined ? {} : { facetId: tool.facetId }),
+  ...(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(projectSurfaceMapTool),
+});
+
+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 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);
+};
+
+/**
+ * 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 projection 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);
+    }
+  }
+
+  return {
+    list: listings,
+    read: (uri) => contents.get(uri),
+  };
+};
+
+/**
+ * Return whether an MCP tool was projected from a surface facet.
+ *
+ * @example
+ * ```ts
+ * import { isMcpFacetTool } from '@ontrails/mcp';
+ *
+ * const facetTools = tools.filter(isMcpFacetTool);
+ * ```
+ */
+export const isMcpFacetTool = (tool: McpToolDefinition): boolean =>
+  tool._meta?.[MCP_TOOL_FACET_META_KEY] !== undefined;

package/src/stdio.ts

@@ -2,7 +2,7 @@
  * 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().
+ * (SSE, streamable HTTP) without changing surface().
  */
 
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -10,6 +10,14 @@ 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();

package/src/surface.ts

@@ -0,0 +1,279 @@
+/**
+ * Surface helpers for exposing a topo over MCP.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import type {
+  BaseSurfaceOptions,
+  Layer,
+  ResourceOverrideMap,
+  Topo,
+  TrailContextInit,
+} from '@ontrails/core';
+
+import type {
+  McpSurfaceFacetMap,
+  McpToolDefinition,
+  ResolveMcpPermit,
+} from './build.js';
+import { deriveMcpTools } from './build.js';
+import { buildMcpResources } from './resources.js';
+import type { BuiltMcpResources, McpResourcesConfig } from './resources.js';
+import { connectStdio } from './stdio.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface CreateServerOptions extends BaseSurfaceOptions {
+  readonly createContext?:
+    | (() => TrailContextInit | Promise<TrailContextInit>)
+    | undefined;
+  readonly description?: string | undefined;
+  readonly facets?: McpSurfaceFacetMap | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  readonly mcpResources?: McpResourcesConfig | false | undefined;
+  readonly name?: string | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
+  readonly resolvePermit?: ResolveMcpPermit | undefined;
+  readonly version?: string | undefined;
+}
+
+export interface SurfaceMcpResult {
+  readonly close: () => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal: create MCP server with tool handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an MCP Server instance and register all tools.
+ *
+ * When provided, `info.description` is forwarded to the MCP SDK as the
+ * server's `instructions` field — the SDK's documented channel for
+ * "optional instructions describing how to use the server and its features."
+ */
+const createMcpServer = (
+  tools: McpToolDefinition[],
+  info: {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string | undefined;
+  },
+  mcpResources?: BuiltMcpResources | undefined
+): Server => {
+  const server = new Server(
+    { name: info.name, version: info.version },
+    {
+      capabilities: {
+        ...(mcpResources === undefined ? {} : { resources: {} }),
+        tools: {},
+      },
+      ...(info.description === undefined
+        ? {}
+        : { instructions: info.description }),
+    }
+  );
+
+  // 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) => ({
+      _meta: t._meta,
+      annotations: t.annotations,
+      description: t.description,
+      inputSchema: t.inputSchema,
+      name: t.name,
+      outputSchema: t.outputSchema,
+    })),
+  }));
+
+  // Register tools/call handler
+  server.setRequestHandler(
+    CallToolRequestSchema,
+    async (request, requestExtra) => {
+      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 { authInfo } = requestExtra as {
+        readonly authInfo?:
+          | {
+              readonly accessToken?: string | undefined;
+              readonly sessionId?: string | undefined;
+              readonly token?: string | undefined;
+            }
+          | undefined;
+      };
+      const authorizationToken = authInfo?.accessToken ?? authInfo?.token;
+
+      const sendProgress =
+        progressToken === undefined
+          ? undefined
+          : async (current: number, total: number) => {
+              await server.notification({
+                method: 'notifications/progress',
+                params: {
+                  progress: current,
+                  progressToken,
+                  total,
+                },
+              });
+            };
+
+      const extra = {
+        abortSignal: requestExtra.signal,
+        ...(authorizationToken === undefined
+          ? {}
+          : { authorization: `Bearer ${authorizationToken}` }),
+        progressToken,
+        sendProgress,
+        ...(authInfo?.sessionId === undefined
+          ? {}
+          : { sessionId: authInfo.sessionId }),
+      };
+
+      const result = await tool.handler(args, extra);
+      // Spread to satisfy MCP SDK's index-signature requirement
+      return { ...result } as Record<string, unknown>;
+    }
+  );
+
+  if (mcpResources !== undefined) {
+    // oxlint-disable-next-line require-await -- MCP SDK requires async handler
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+      resources: mcpResources.list.map((resource) => ({
+        description: resource.description,
+        mimeType: resource.mimeType,
+        name: resource.name,
+        uri: resource.uri,
+      })),
+    }));
+
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const content = mcpResources.read(request.params.uri);
+      return {
+        contents: [
+          content ?? {
+            mimeType: 'text/plain',
+            text: `Unknown MCP resource: ${request.params.uri}`,
+            uri: request.params.uri,
+          },
+        ],
+      };
+    });
+  }
+
+  return server;
+};
+
+// ---------------------------------------------------------------------------
+// createServer
+// ---------------------------------------------------------------------------
+
+/**
+ * Build MCP tools from a topo and create an MCP server.
+ *
+ * @remarks This is a host materialization boundary. Derivation failures are
+ * thrown for server bootstrap code after `deriveMcpTools` has already
+ * represented the framework error as a Result.
+ *
+ * @example
+ * ```ts
+ * import { connectStdio, createServer } from '@ontrails/mcp';
+ *
+ * const server = createServer(graph, { name: 'demo' });
+ * await connectStdio(server);
+ * ```
+ */
+export const createServer = (
+  graph: Topo,
+  options: CreateServerOptions = {}
+): Server => {
+  const toolsResult = deriveMcpTools(graph, {
+    configValues: options.configValues,
+    createContext: options.createContext,
+    exclude: options.exclude,
+    facets: options.facets,
+    include: options.include,
+    intent: options.intent,
+    layers: options.layers,
+    resolvePermit: options.resolvePermit,
+    resources: options.resources,
+    validate: options.validate,
+  });
+
+  if (toolsResult.isErr()) {
+    throw toolsResult.error;
+  }
+
+  const mcpResources =
+    options.mcpResources === false
+      ? undefined
+      : buildMcpResources(graph, toolsResult.value, options.mcpResources);
+
+  return createMcpServer(
+    toolsResult.value,
+    {
+      description: options.description ?? graph.description,
+      name: options.name ?? graph.name,
+      version: options.version ?? graph.version ?? '0.1.0',
+    },
+    mcpResources
+  );
+};
+
+// ---------------------------------------------------------------------------
+// surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Build MCP tools from a topo, create a server, and connect via stdio.
+ *
+ * @remarks Opens the MCP server on stdio. For custom transports, use
+ * `createServer(graph)` with `connectStdio` or your own adapter.
+ *
+ * @example
+ * ```ts
+ * import { surface } from '@ontrails/mcp';
+ *
+ * await surface(graph, { name: 'demo' });
+ * ```
+ */
+export const surface = async (
+  graph: Topo,
+  options: CreateServerOptions = {}
+): Promise<SurfaceMcpResult> => {
+  const server = createServer(graph, options);
+  await connectStdio(server);
+
+  return {
+    close: async () => {
+      await server.close();
+    },
+  };
+};

package/.turbo/turbo-build.log

@@ -1 +0,0 @@
-$ tsc -b

package/.turbo/turbo-lint.log

@@ -1,3 +0,0 @@
-$ oxlint ./src
-Found 0 warnings and 0 errors.
-Finished in 54ms on 12 files with 93 rules using 24 threads.

package/.turbo/turbo-typecheck.log

@@ -1 +0,0 @@
-$ tsc --noEmit

package/dist/annotations.d.ts

@@ -1,19 +0,0 @@
-/**
- * Derive MCP tool annotations from trail spec markers.
- */
-import type { Trail } from '@ontrails/core';
-export interface McpAnnotations {
-    readonly readOnlyHint?: boolean | undefined;
-    readonly destructiveHint?: boolean | undefined;
-    readonly idempotentHint?: boolean | undefined;
-    readonly openWorldHint?: boolean | undefined;
-    readonly title?: string | undefined;
-}
-/**
- * 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 declare const deriveAnnotations: (trail: Pick<Trail<unknown, unknown>, "readOnly" | "destructive" | "idempotent" | "description">) => McpAnnotations;
-//# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAM5C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAMD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,IAAI,CACT,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,EACvB,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,aAAa,CAC1D,KACA,cAiBF,CAAC"}

package/dist/annotations.js

@@ -1,29 +0,0 @@
-/**
- * Derive MCP tool annotations from trail spec markers.
- */
-// ---------------------------------------------------------------------------
-// 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) => {
-    const annotations = {};
-    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;
-};
-//# sourceMappingURL=annotations.js.map

package/dist/annotations.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,KAGC,EACe,EAAE;IAClB,MAAM,WAAW,GAA4B,EAAE,CAAC;IAEhD,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC5B,WAAW,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;IACrC,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAC/B,WAAW,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC;IACxC,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QAC9B,WAAW,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;IACvC,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,WAAW,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC;IAC3C,CAAC;IAED,OAAO,WAA6B,CAAC;AACvC,CAAC,CAAC"}