@ontrails/mcp 1.0.0-beta.12 → 1.0.0-beta.14

package/src/build.ts

@@ -2,22 +2,23 @@
  * 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,
-  SURFACE_KEY,
+  TRAILHEAD_KEY,
   ValidationError,
   executeTrail,
   isBlobRef,
+  validateEstablishedTopo,
   zodToJsonSchema,
 } from '@ontrails/core';
 import type {
   BlobRef,
-  Layer,
-  ServiceOverrideMap,
+  Gate,
+  ProvisionOverrideMap,
   Topo,
   Trail,
   TrailContextInit,
@@ -33,7 +34,7 @@ import { deriveToolName } from './tool-name.js';
 // ---------------------------------------------------------------------------
 
 export interface BuildMcpToolsOptions {
-  /** Config values for services that declare a `config` schema, keyed by service ID. */
+  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
   readonly configValues?:
     | Readonly<Record<string, Record<string, unknown>>>
     | undefined;
@@ -42,8 +43,10 @@ export interface BuildMcpToolsOptions {
     | 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;
+  /** Set to `false` to skip topo validation while building tools. */
+  readonly validate?: boolean | undefined;
 }
 
 export interface McpToolDefinition {
@@ -64,7 +67,7 @@ export interface McpExtra {
   readonly sendProgress?:
     | ((current: number, total: number) => Promise<void>)
     | undefined;
-  readonly signal?: AbortSignal | undefined;
+  readonly abortSignal?: AbortSignal | undefined;
 }
 
 export interface McpToolResult {
@@ -212,20 +215,20 @@ const mcpError = (message: string): McpToolResult => ({
   isError: true,
 });
 
-/** Add the MCP surface marker while preserving any existing context extras. */
-const withMcpSurface = (
+/** Add the MCP trailhead marker while preserving any existing context extras. */
+const withMcpTrailhead = (
   progressCb: TrailContextInit['progress']
 ): Partial<TrailContextInit> => ({
   ...(progressCb === undefined ? {} : { progress: progressCb }),
   extensions: {
-    [SURFACE_KEY]: 'mcp' as const,
+    [TRAILHEAD_KEY]: 'mcp' as const,
   },
 });
 
 const createHandler =
   (
     t: Trail<unknown, unknown>,
-    layers: readonly Layer[],
+    gates: readonly Gate[],
     options: BuildMcpToolsOptions
   ): ((
     args: Record<string, unknown>,
@@ -234,12 +237,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: withMcpSurface(progressCb),
-      layers,
-      services: options.services,
-      signal: extra.signal,
+      ctx: withMcpTrailhead(progressCb),
+      gates,
+      provisions: options.provisions,
     });
     if (result.isOk()) {
       return { content: await serializeOutput(result.value) };
@@ -257,15 +260,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) {
@@ -302,7 +305,7 @@ const buildDescription = (
 const buildToolDefinition = (
   app: Topo,
   trail: Trail<unknown, unknown>,
-  layers: readonly Layer[],
+  gates: readonly Gate[],
   options: BuildMcpToolsOptions
 ): McpToolDefinition => {
   const rawAnnotations = deriveAnnotations(trail);
@@ -311,7 +314,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,
@@ -322,7 +325,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[]
@@ -337,7 +340,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();
 };
 
@@ -348,11 +351,23 @@ const eligibleTrails = (
 ): Trail<unknown, unknown>[] =>
   app.list().filter((trail) => shouldInclude(trail, options));
 
-export const buildMcpTools = (
+const validateToolBuild = (
   app: Topo,
-  options: BuildMcpToolsOptions = {}
+  options: BuildMcpToolsOptions
+): Result<void, Error> => {
+  if (options.validate === false) {
+    return Result.ok();
+  }
+
+  const validated = validateEstablishedTopo(app);
+  return validated.isErr() ? Result.err(validated.error) : Result.ok();
+};
+
+const registerTools = (
+  app: Topo,
+  options: BuildMcpToolsOptions,
+  gates: readonly Gate[]
 ): Result<McpToolDefinition[], Error> => {
-  const layers = options.layers ?? [];
   const tools: McpToolDefinition[] = [];
   const nameToTrailId = new Map<string, string>();
 
@@ -360,7 +375,7 @@ export const buildMcpTools = (
     const registered = registerTool(
       app,
       trailItem,
-      layers,
+      gates,
       options,
       nameToTrailId,
       tools
@@ -372,3 +387,15 @@ export const buildMcpTools = (
 
   return Result.ok(tools);
 };
+
+export const buildMcpTools = (
+  app: Topo,
+  options: BuildMcpToolsOptions = {}
+): Result<McpToolDefinition[], Error> => {
+  const validation = validateToolBuild(app, options);
+  if (validation.isErr()) {
+    return validation;
+  }
+
+  return registerTools(app, options, options.gates ?? []);
+};

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,12 +15,12 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import type {
-  Layer,
-  ServiceOverrideMap,
+  Gate,
+  ProvisionOverrideMap,
   Topo,
   TrailContextInit,
 } from '@ontrails/core';
-import { validateTopo } from '@ontrails/core';
+import { validateEstablishedTopo } from '@ontrails/core';
 
 import type { McpToolDefinition } from './build.js';
 import { buildMcpTools } from './build.js';
@@ -30,8 +30,8 @@ import { connectStdio } from './stdio.js';
 // Options
 // ---------------------------------------------------------------------------
 
-export interface BlazeMcpOptions {
-  /** Config values for services that declare a `config` schema, keyed by service ID. */
+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;
@@ -40,7 +40,8 @@ export interface BlazeMcpOptions {
     | 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;
@@ -48,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;
 }
@@ -119,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);
@@ -133,18 +133,18 @@ 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);
+    const validated = validateEstablishedTopo(app);
     if (validated.isErr()) {
       throw validated.error;
     }
@@ -154,9 +154,10 @@ export const blaze = async (
     configValues: options.configValues,
     createContext: options.createContext,
     excludeTrails: options.excludeTrails,
+    gates: options.gates,
     includeTrails: options.includeTrails,
-    layers: options.layers,
-    services: options.services,
+    provisions: options.provisions,
+    validate: options.validate,
   });
 
   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"}