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

package/src/build.ts

@@ -2,12 +2,13 @@
  * 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
+ * validate input, compose gates, execute the implementation, and map
  * Results to MCP responses.
  */
 
 import {
   Result,
+  TRAILHEAD_KEY,
   ValidationError,
   executeTrail,
   isBlobRef,
@@ -15,8 +16,8 @@ import {
 } from '@ontrails/core';
 import type {
   BlobRef,
-  Layer,
-  ServiceOverrideMap,
+  Gate,
+  ProvisionOverrideMap,
   Topo,
   Trail,
   TrailContextInit,
@@ -32,13 +33,17 @@ import { deriveToolName } from './tool-name.js';
 // ---------------------------------------------------------------------------
 
 export interface BuildMcpToolsOptions {
+  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
+  readonly configValues?:
+    | Readonly<Record<string, Record<string, unknown>>>
+    | undefined;
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
   readonly excludeTrails?: readonly string[] | undefined;
   readonly includeTrails?: readonly string[] | undefined;
-  readonly layers?: readonly Layer[] | undefined;
-  readonly services?: ServiceOverrideMap | undefined;
+  readonly gates?: readonly Gate[] | undefined;
+  readonly provisions?: ProvisionOverrideMap | undefined;
 }
 
 export interface McpToolDefinition {
@@ -59,7 +64,7 @@ export interface McpExtra {
   readonly sendProgress?:
     | ((current: number, total: number) => Promise<void>)
     | undefined;
-  readonly signal?: AbortSignal | undefined;
+  readonly abortSignal?: AbortSignal | undefined;
 }
 
 export interface McpToolResult {
@@ -207,10 +212,20 @@ const mcpError = (message: string): McpToolResult => ({
   isError: true,
 });
 
+/** Add the MCP trailhead marker while preserving any existing context extras. */
+const withMcpTrailhead = (
+  progressCb: TrailContextInit['progress']
+): Partial<TrailContextInit> => ({
+  ...(progressCb === undefined ? {} : { progress: progressCb }),
+  extensions: {
+    [TRAILHEAD_KEY]: 'mcp' as const,
+  },
+});
+
 const createHandler =
   (
     t: Trail<unknown, unknown>,
-    layers: readonly Layer[],
+    gates: readonly Gate[],
     options: BuildMcpToolsOptions
   ): ((
     args: Record<string, unknown>,
@@ -219,11 +234,12 @@ const createHandler =
   async (args, extra): Promise<McpToolResult> => {
     const progressCb = createMcpProgressCallback(extra);
     const result = await executeTrail(t, args, {
+      abortSignal: extra.abortSignal,
+      configValues: options.configValues,
       createContext: options.createContext,
-      ctx: progressCb === undefined ? undefined : { progress: progressCb },
-      layers,
-      services: options.services,
-      signal: extra.signal,
+      ctx: withMcpTrailhead(progressCb),
+      gates,
+      provisions: options.provisions,
     });
     if (result.isOk()) {
       return { content: await serializeOutput(result.value) };
@@ -241,15 +257,15 @@ const createHandler =
  * 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 metadata
- * - A handler that validates, composes layers, executes, and maps results
+ * - MCP annotations from trail meta
+ * - A handler that validates, composes gates, executes, and maps results
  */
-/** Check if a trail should be included based on metadata and filters. */
+/** Check if a trail should be included based on meta and filters. */
 const shouldInclude = (
   trail: Trail<unknown, unknown>,
   options: BuildMcpToolsOptions
 ): boolean => {
-  if (trail.metadata?.['internal'] === true) {
+  if (trail.meta?.['internal'] === true) {
     return false;
   }
   if (options.includeTrails !== undefined && options.includeTrails.length > 0) {
@@ -286,7 +302,7 @@ const buildDescription = (
 const buildToolDefinition = (
   app: Topo,
   trail: Trail<unknown, unknown>,
-  layers: readonly Layer[],
+  gates: readonly Gate[],
   options: BuildMcpToolsOptions
 ): McpToolDefinition => {
   const rawAnnotations = deriveAnnotations(trail);
@@ -295,7 +311,7 @@ const buildToolDefinition = (
   return {
     annotations,
     description: buildDescription(trail),
-    handler: createHandler(trail, layers, options),
+    handler: createHandler(trail, gates, options),
     inputSchema: zodToJsonSchema(trail.input),
     name: deriveToolName(app.name, trail.id),
     trailId: trail.id,
@@ -306,7 +322,7 @@ const buildToolDefinition = (
 const registerTool = (
   app: Topo,
   trailItem: Trail<unknown, unknown>,
-  layers: readonly Layer[],
+  gates: readonly Gate[],
   options: BuildMcpToolsOptions,
   nameToTrailId: Map<string, string>,
   tools: McpToolDefinition[]
@@ -321,7 +337,7 @@ const registerTool = (
     );
   }
   nameToTrailId.set(toolName, trailItem.id);
-  tools.push(buildToolDefinition(app, trailItem, layers, options));
+  tools.push(buildToolDefinition(app, trailItem, gates, options));
   return Result.ok();
 };
 
@@ -336,7 +352,7 @@ export const buildMcpTools = (
   app: Topo,
   options: BuildMcpToolsOptions = {}
 ): Result<McpToolDefinition[], Error> => {
-  const layers = options.layers ?? [];
+  const gates = options.gates ?? [];
   const tools: McpToolDefinition[] = [];
   const nameToTrailId = new Map<string, string>();
 
@@ -344,7 +360,7 @@ export const buildMcpTools = (
     const registered = registerTool(
       app,
       trailItem,
-      layers,
+      gates,
       options,
       nameToTrailId,
       tools

package/src/index.ts

@@ -17,8 +17,8 @@ export { deriveAnnotations, type McpAnnotations } from './annotations.js';
 // Progress
 export { createMcpProgressCallback } from './progress.js';
 
-// Blaze
-export { blaze, type BlazeMcpOptions } from './blaze.js';
+// Trailhead
+export { trailhead, type TrailheadMcpOptions } from './trailhead.js';
 
 // Transport
 export { connectStdio } from './stdio.js';

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 trailhead().
  */
 
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';

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

@@ -1,11 +1,11 @@
 /**
- * blaze() -- the one-liner MCP server launcher.
+ * trailhead() -- the one-liner MCP server launcher.
  *
  * Three lines to expose trails as MCP tools:
  *
  * ```ts
  * const app = topo("myapp", entity);
- * await blaze(app);
+ * await trailhead(app);
  * ```
  */
 
@@ -15,8 +15,8 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import type {
-  Layer,
-  ServiceOverrideMap,
+  Gate,
+  ProvisionOverrideMap,
   Topo,
   TrailContextInit,
 } from '@ontrails/core';
@@ -30,13 +30,18 @@ import { connectStdio } from './stdio.js';
 // Options
 // ---------------------------------------------------------------------------
 
-export interface BlazeMcpOptions {
+export interface TrailheadMcpOptions {
+  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
+  readonly configValues?:
+    | Readonly<Record<string, Record<string, unknown>>>
+    | undefined;
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
   readonly excludeTrails?: readonly string[] | undefined;
   readonly includeTrails?: readonly string[] | undefined;
-  readonly layers?: readonly Layer[] | undefined;
+  readonly gates?: readonly Gate[] | undefined;
+  readonly provisions?: ProvisionOverrideMap | undefined;
   readonly serverInfo?:
     | {
         readonly name?: string | undefined;
@@ -44,7 +49,6 @@ export interface BlazeMcpOptions {
       }
     | undefined;
   readonly transport?: 'stdio' | undefined;
-  readonly services?: ServiceOverrideMap | undefined;
   /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
   readonly validate?: boolean | undefined;
 }
@@ -115,9 +119,9 @@ export const createMcpServer = (
           };
 
     const extra = {
+      abortSignal: undefined as AbortSignal | undefined,
       progressToken,
       sendProgress,
-      signal: undefined as AbortSignal | undefined,
     };
 
     const result = await tool.handler(args, extra);
@@ -129,15 +133,15 @@ export const createMcpServer = (
 };
 
 // ---------------------------------------------------------------------------
-// blaze
+// trailhead
 // ---------------------------------------------------------------------------
 
 /**
  * Build MCP tools from an App, create a server, and connect via stdio.
  */
-export const blaze = async (
+export const trailhead = async (
   app: Topo,
-  options: BlazeMcpOptions = {}
+  options: TrailheadMcpOptions = {}
 ): Promise<void> => {
   if (options.validate !== false) {
     const validated = validateTopo(app);
@@ -147,11 +151,12 @@ export const blaze = async (
   }
 
   const toolsResult = buildMcpTools(app, {
+    configValues: options.configValues,
     createContext: options.createContext,
     excludeTrails: options.excludeTrails,
+    gates: options.gates,
     includeTrails: options.includeTrails,
-    layers: options.layers,
-    services: options.services,
+    provisions: options.provisions,
   });
 
   if (toolsResult.isErr()) {

package/tsconfig.tsbuildinfo

@@ -1 +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"}
+{"root":["./src/annotations.ts","./src/build.ts","./src/index.ts","./src/progress.ts","./src/stdio.ts","./src/tool-name.ts","./src/trailhead.ts"],"version":"5.9.3"}