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

package/src/__tests__/{trailhead.test.ts → surface.test.ts}

@@ -3,14 +3,22 @@ import { describe, expect, test } from 'bun:test';
 import { Result, trail, topo } from '@ontrails/core';
 import { z } from 'zod';
 
-import { trailhead, createMcpServer } from '../trailhead.js';
-import { buildMcpTools } from '../build.js';
+import { createServer, surface } from '../surface.js';
+import { deriveMcpTools } from '../build.js';
 import type { McpToolDefinition } from '../build.js';
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
+const unwrapOk = <T>(result: Result<T, Error>): T =>
+  result.match({
+    err: (error) => {
+      throw error;
+    },
+    ok: (value) => value,
+  });
+
 const requireTool = (tools: McpToolDefinition[], name: string) => {
   const tool = tools.find((entry) => entry.name === name);
   expect(tool).toBeDefined();
@@ -21,19 +29,19 @@ const requireTool = (tools: McpToolDefinition[], name: string) => {
 };
 
 /**
- * Unwrap buildMcpTools result, throwing on error so test failures show up clearly.
+ * Unwrap deriveMcpTools result, throwing on error so test failures show up clearly.
  */
-const buildTools = (
-  ...args: Parameters<typeof buildMcpTools>
+const deriveTools = (
+  ...args: Parameters<typeof deriveMcpTools>
 ): McpToolDefinition[] => {
-  const result = buildMcpTools(...args);
+  const result = deriveMcpTools(...args);
   if (result.isErr()) {
     throw result.error;
   }
   return result.value;
 };
 
-const createIntegrationTools = () => {
+const createIntegrationFixtures = () => {
   const greetTrail = trail('greet', {
     blaze: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
     description: 'Greet someone',
@@ -48,11 +56,12 @@ const createIntegrationTools = () => {
     intent: 'destroy',
   });
 
-  return buildTools(topo('myapp', { deleteTrail, greetTrail }));
+  const app = topo('myapp', { deleteTrail, greetTrail });
+  return { app, tools: deriveTools(app) };
 };
 
-describe('trailhead', () => {
-  test('trailhead throws on invalid topo', async () => {
+describe('surface', () => {
+  test('surface throws on invalid topo', async () => {
     const t = trail('broken', {
       blaze: () => Result.ok({}),
       crosses: ['nonexistent.trail'],
@@ -60,10 +69,10 @@ describe('trailhead', () => {
       output: z.object({}),
     });
     const app = topo('test', { t });
-    await expect(trailhead(app)).rejects.toThrow(/validation/i);
+    await expect(surface(app)).rejects.toThrow(/validation/i);
   });
 
-  test('trailhead skips validation when validate: false', async () => {
+  test('surface skips validation when validate: false', async () => {
     const t = trail('broken', {
       blaze: () => Result.ok({}),
       crosses: ['nonexistent.trail'],
@@ -72,7 +81,7 @@ describe('trailhead', () => {
     });
     const app = topo('test', { t });
     const result = await Promise.race([
-      trailhead(app, { validate: false }).then(() => 'resolved' as const),
+      surface(app, { validate: false }).then(() => 'resolved' as const),
       // oxlint-disable-next-line avoid-new -- Promise constructor needed for setTimeout-based timeout
       new Promise<'timeout'>((resolve) => {
         setTimeout(() => {
@@ -83,15 +92,22 @@ describe('trailhead', () => {
     expect(['resolved', 'timeout']).toContain(result);
   });
 
-  test('TrailheadMcpOptions accepts provision overrides', () => {
-    const opts: Parameters<typeof trailhead>[1] = {
-      provisions: {},
+  test('CreateServerOptions accepts flattened identity and resource fields', () => {
+    const opts: Parameters<typeof surface>[1] = {
+      description: 'Test MCP server',
+      name: 'testapp',
+      resources: {},
       validate: false,
+      version: '1.2.3',
     };
-    expect(opts.provisions).toEqual({});
+    expect(opts.description).toBe('Test MCP server');
+    expect(opts.name).toBe('testapp');
+    expect(opts.resources).toEqual({});
+    expect(opts.validate).toBe(false);
+    expect(opts.version).toBe('1.2.3');
   });
 
-  test('createMcpServer registers tools that can be listed', () => {
+  test('createServer registers tools that can be listed', () => {
     const echoTrail = trail('echo', {
       blaze: (input) => Result.ok({ reply: input.message }),
       description: 'Echo',
@@ -100,8 +116,7 @@ describe('trailhead', () => {
     });
 
     const app = topo('testapp', { echoTrail });
-    const tools = buildTools(app);
-    const server = createMcpServer(tools, {
+    const server = createServer(app, {
       name: 'testapp',
       version: '0.1.0',
     });
@@ -110,7 +125,7 @@ describe('trailhead', () => {
     expect(server).toBeDefined();
   });
 
-  test('createMcpServer handles multiple tools', () => {
+  test('createServer handles multiple tools', () => {
     const echoTrail = trail('echo', {
       blaze: (input) => Result.ok({ reply: input.message }),
       description: 'Echo',
@@ -125,19 +140,37 @@ describe('trailhead', () => {
     });
 
     const app = topo('testapp', { echoTrail, searchTrail });
-    const tools = buildTools(app);
+    const tools = deriveTools(app);
 
     expect(tools).toHaveLength(2);
 
-    const server = createMcpServer(tools, {
+    const server = createServer(app, {
       name: 'testapp',
       version: '0.1.0',
     });
     expect(server).toBeDefined();
   });
 
-  test('buildMcpTools + createMcpServer integration', () => {
-    const tools = createIntegrationTools();
+  test('deriveMcpTools returns tools and createServer materializes the server', () => {
+    const echoTrail = trail('echo', {
+      blaze: (input) => Result.ok({ reply: input.message }),
+      description: 'Echo',
+      input: z.object({ message: z.string() }),
+    });
+    const app = topo('surface-api', { echoTrail });
+
+    const tools = unwrapOk(deriveMcpTools(app));
+    expect(tools).toHaveLength(1);
+
+    const server = createServer(app, {
+      description: 'Surface API smoke',
+      version: '2.0.0',
+    });
+    expect(server).toBeDefined();
+  });
+
+  test('deriveMcpTools + createServer integration', () => {
+    const { app, tools } = createIntegrationFixtures();
     const names = tools.map((t) => t.name);
     expect(names).toContain('myapp_greet');
     expect(names).toContain('myapp_item_delete');
@@ -149,7 +182,7 @@ describe('trailhead', () => {
       requireTool(tools, 'myapp_item_delete').annotations?.destructiveHint
     ).toBe(true);
 
-    const server = createMcpServer(tools, {
+    const server = createServer(app, {
       name: 'myapp',
       version: '1.0.0',
     });

package/src/annotations.ts

@@ -27,7 +27,10 @@ export interface McpAnnotations {
  * Omitted hints let the MCP SDK use its defaults.
  */
 export const deriveAnnotations = (
-  trail: Pick<Trail<unknown, unknown>, 'intent' | 'idempotent' | 'description'>
+  trail: Pick<
+    Trail<unknown, unknown, unknown>,
+    'intent' | 'idempotent' | 'description'
+  >
 ): McpAnnotations => {
   const annotations: Record<string, unknown> = {};
 

package/src/build.ts

@@ -1,8 +1,8 @@
 /**
- * Build MCP tool definitions from a Trails App.
+ * Build MCP tool definitions from a Trails graph.
  *
  * Iterates the topo, generates McpToolDefinition[] with handlers that
- * validate input, compose gates, execute the implementation, and map
+ * validate input, compose layers, execute the implementation, and map
  * Results to MCP responses.
  */
 
@@ -11,14 +11,16 @@ import {
   TRAILHEAD_KEY,
   ValidationError,
   executeTrail,
+  filterSurfaceTrails,
   isBlobRef,
   validateEstablishedTopo,
   zodToJsonSchema,
 } from '@ontrails/core';
 import type {
   BlobRef,
-  Gate,
-  ProvisionOverrideMap,
+  Intent,
+  Layer,
+  ResourceOverrideMap,
   Topo,
   Trail,
   TrailContextInit,
@@ -33,18 +35,19 @@ import { deriveToolName } from './tool-name.js';
 // Public types
 // ---------------------------------------------------------------------------
 
-export interface BuildMcpToolsOptions {
-  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
+export interface DeriveMcpToolsOptions {
+  /** Config values for resources that declare a `config` schema, keyed by resource 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 gates?: readonly Gate[] | undefined;
-  readonly provisions?: ProvisionOverrideMap | undefined;
+  readonly exclude?: readonly string[] | undefined;
+  readonly include?: readonly string[] | undefined;
+  readonly intent?: readonly Intent[] | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
   /** Set to `false` to skip topo validation while building tools. */
   readonly validate?: boolean | undefined;
 }
@@ -227,9 +230,10 @@ const withMcpTrailhead = (
 
 const createHandler =
   (
-    t: Trail<unknown, unknown>,
-    gates: readonly Gate[],
-    options: BuildMcpToolsOptions
+    graph: Topo,
+    t: Trail<unknown, unknown, unknown>,
+    layers: readonly Layer[],
+    options: DeriveMcpToolsOptions
   ): ((
     args: Record<string, unknown>,
     extra: McpExtra
@@ -241,8 +245,9 @@ const createHandler =
       configValues: options.configValues,
       createContext: options.createContext,
       ctx: withMcpTrailhead(progressCb),
-      gates,
-      provisions: options.provisions,
+      layers,
+      resources: options.resources,
+      topo: graph,
     });
     if (result.isOk()) {
       return { content: await serializeOutput(result.value) };
@@ -255,37 +260,18 @@ const createHandler =
 // ---------------------------------------------------------------------------
 
 /**
- * Build MCP tool definitions from an App's topology.
+ * Build MCP tool definitions from a graph's topology.
  *
  * Each trail in the topo becomes an McpToolDefinition with:
- * - A derived tool name (app-prefixed, underscore-delimited)
+ * - A derived tool name (topo-name-prefixed, underscore-delimited)
  * - JSON Schema input from zodToJsonSchema
  * - MCP annotations from trail meta
- * - A handler that validates, composes gates, executes, and maps results
+ * - A handler that validates, composes layers, executes, and maps results
  */
-/** Check if a trail should be included based on meta and filters. */
-const shouldInclude = (
-  trail: Trail<unknown, unknown>,
-  options: BuildMcpToolsOptions
-): boolean => {
-  if (trail.meta?.['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>
+  trail: Trail<unknown, unknown, unknown>
 ): string | undefined => {
   let { description } = trail;
   if (
@@ -303,10 +289,10 @@ const buildDescription = (
 
 /** Build a single MCP tool definition from a trail. */
 const buildToolDefinition = (
-  app: Topo,
-  trail: Trail<unknown, unknown>,
-  gates: readonly Gate[],
-  options: BuildMcpToolsOptions
+  graph: Topo,
+  trail: Trail<unknown, unknown, unknown>,
+  layers: readonly Layer[],
+  options: DeriveMcpToolsOptions
 ): McpToolDefinition => {
   const rawAnnotations = deriveAnnotations(trail);
   const annotations =
@@ -314,23 +300,23 @@ const buildToolDefinition = (
   return {
     annotations,
     description: buildDescription(trail),
-    handler: createHandler(trail, gates, options),
+    handler: createHandler(graph, trail, layers, options),
     inputSchema: zodToJsonSchema(trail.input),
-    name: deriveToolName(app.name, trail.id),
+    name: deriveToolName(graph.name, trail.id),
     trailId: trail.id,
   };
 };
 
 /** Register a trail as an MCP tool, checking for name collisions. */
 const registerTool = (
-  app: Topo,
-  trailItem: Trail<unknown, unknown>,
-  gates: readonly Gate[],
-  options: BuildMcpToolsOptions,
+  graph: Topo,
+  trailItem: Trail<unknown, unknown, unknown>,
+  layers: readonly Layer[],
+  options: DeriveMcpToolsOptions,
   nameToTrailId: Map<string, string>,
   tools: McpToolDefinition[]
 ): Result<void, Error> => {
-  const toolName = deriveToolName(app.name, trailItem.id);
+  const toolName = deriveToolName(graph.name, trailItem.id);
   const existingId = nameToTrailId.get(toolName);
   if (existingId !== undefined) {
     return Result.err(
@@ -340,42 +326,46 @@ const registerTool = (
     );
   }
   nameToTrailId.set(toolName, trailItem.id);
-  tools.push(buildToolDefinition(app, trailItem, gates, options));
+  tools.push(buildToolDefinition(graph, trailItem, layers, options));
   return Result.ok();
 };
 
 /** Filter topo items to eligible trails. */
 const eligibleTrails = (
-  app: Topo,
-  options: BuildMcpToolsOptions
-): Trail<unknown, unknown>[] =>
-  app.list().filter((trail) => shouldInclude(trail, options));
+  graph: Topo,
+  options: DeriveMcpToolsOptions
+): Trail<unknown, unknown, unknown>[] =>
+  filterSurfaceTrails(graph.list(), {
+    exclude: options.exclude,
+    include: options.include,
+    intent: options.intent,
+  });
 
 const validateToolBuild = (
-  app: Topo,
-  options: BuildMcpToolsOptions
+  graph: Topo,
+  options: DeriveMcpToolsOptions
 ): Result<void, Error> => {
   if (options.validate === false) {
     return Result.ok();
   }
 
-  const validated = validateEstablishedTopo(app);
+  const validated = validateEstablishedTopo(graph);
   return validated.isErr() ? Result.err(validated.error) : Result.ok();
 };
 
 const registerTools = (
-  app: Topo,
-  options: BuildMcpToolsOptions,
-  gates: readonly Gate[]
+  graph: Topo,
+  options: DeriveMcpToolsOptions,
+  layers: readonly Layer[]
 ): Result<McpToolDefinition[], Error> => {
   const tools: McpToolDefinition[] = [];
   const nameToTrailId = new Map<string, string>();
 
-  for (const trailItem of eligibleTrails(app, options)) {
+  for (const trailItem of eligibleTrails(graph, options)) {
     const registered = registerTool(
-      app,
+      graph,
       trailItem,
-      gates,
+      layers,
       options,
       nameToTrailId,
       tools
@@ -388,14 +378,14 @@ const registerTools = (
   return Result.ok(tools);
 };
 
-export const buildMcpTools = (
-  app: Topo,
-  options: BuildMcpToolsOptions = {}
+export const deriveMcpTools = (
+  graph: Topo,
+  options: DeriveMcpToolsOptions = {}
 ): Result<McpToolDefinition[], Error> => {
-  const validation = validateToolBuild(app, options);
+  const validation = validateToolBuild(graph, options);
   if (validation.isErr()) {
     return validation;
   }
 
-  return registerTools(app, options, options.gates ?? []);
+  return registerTools(graph, options, options.layers ?? []);
 };

package/src/index.ts

@@ -1,7 +1,7 @@
 // Build
 export {
-  buildMcpTools,
-  type BuildMcpToolsOptions,
+  deriveMcpTools,
+  type DeriveMcpToolsOptions,
   type McpToolDefinition,
   type McpToolResult,
   type McpContent,
@@ -17,8 +17,13 @@ export { deriveAnnotations, type McpAnnotations } from './annotations.js';
 // Progress
 export { createMcpProgressCallback } from './progress.js';
 
-// Trailhead
-export { trailhead, type TrailheadMcpOptions } from './trailhead.js';
+// Surface
+export {
+  createServer,
+  surface,
+  type CreateServerOptions,
+  type SurfaceMcpResult,
+} from './surface.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 trailhead().
+ * (SSE, streamable HTTP) without changing surface().
  */
 
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';

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

@@ -1,12 +1,5 @@
 /**
- * trailhead() -- the one-liner MCP server launcher.
- *
- * Three lines to expose trails as MCP tools:
- *
- * ```ts
- * const app = topo("myapp", entity);
- * await trailhead(app);
- * ```
+ * Surface helpers for exposing a topo over MCP.
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -15,42 +8,43 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import type {
-  Gate,
-  ProvisionOverrideMap,
+  Intent,
+  Layer,
+  ResourceOverrideMap,
   Topo,
   TrailContextInit,
 } from '@ontrails/core';
-import { validateEstablishedTopo } from '@ontrails/core';
 
 import type { McpToolDefinition } from './build.js';
-import { buildMcpTools } from './build.js';
+import { deriveMcpTools } from './build.js';
 import { connectStdio } from './stdio.js';
 
 // ---------------------------------------------------------------------------
 // Options
 // ---------------------------------------------------------------------------
 
-export interface TrailheadMcpOptions {
-  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
+export interface CreateServerOptions {
+  /** Config values for resources that declare a `config` schema, keyed by resource 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 gates?: readonly Gate[] | undefined;
-  readonly provisions?: ProvisionOverrideMap | undefined;
-  readonly serverInfo?:
-    | {
-        readonly name?: string | undefined;
-        readonly version?: string | undefined;
-      }
-    | undefined;
-  readonly transport?: 'stdio' | undefined;
+  readonly description?: string | undefined;
+  readonly exclude?: readonly string[] | undefined;
+  readonly include?: readonly string[] | undefined;
+  readonly intent?: readonly Intent[] | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  readonly name?: string | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
   /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
   readonly validate?: boolean | undefined;
+  readonly version?: string | undefined;
+}
+
+export interface SurfaceMcpResult {
+  readonly close: () => Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -59,14 +53,27 @@ export interface TrailheadMcpOptions {
 
 /**
  * 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."
  */
-export const createMcpServer = (
+const createMcpServer = (
   tools: McpToolDefinition[],
-  info: { readonly name: string; readonly version: string }
+  info: {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string | undefined;
+  }
 ): Server => {
   const server = new Server(
     { name: info.name, version: info.version },
-    { capabilities: { tools: {} } }
+    {
+      capabilities: { tools: {} },
+      ...(info.description === undefined
+        ? {}
+        : { instructions: info.description }),
+    }
   );
 
   // Build a lookup map for tool dispatch
@@ -133,30 +140,24 @@ export const createMcpServer = (
 };
 
 // ---------------------------------------------------------------------------
-// trailhead
+// createServer
 // ---------------------------------------------------------------------------
 
 /**
- * Build MCP tools from an App, create a server, and connect via stdio.
+ * Build MCP tools from a topo and create an MCP server.
  */
-export const trailhead = async (
-  app: Topo,
-  options: TrailheadMcpOptions = {}
-): Promise<void> => {
-  if (options.validate !== false) {
-    const validated = validateEstablishedTopo(app);
-    if (validated.isErr()) {
-      throw validated.error;
-    }
-  }
-
-  const toolsResult = buildMcpTools(app, {
+export const createServer = (
+  graph: Topo,
+  options: CreateServerOptions = {}
+): Server => {
+  const toolsResult = deriveMcpTools(graph, {
     configValues: options.configValues,
     createContext: options.createContext,
-    excludeTrails: options.excludeTrails,
-    gates: options.gates,
-    includeTrails: options.includeTrails,
-    provisions: options.provisions,
+    exclude: options.exclude,
+    include: options.include,
+    intent: options.intent,
+    layers: options.layers,
+    resources: options.resources,
     validate: options.validate,
   });
 
@@ -164,10 +165,33 @@ export const trailhead = async (
     throw toolsResult.error;
   }
 
-  const server = createMcpServer(toolsResult.value, {
-    name: options.serverInfo?.name ?? app.name,
-    version: options.serverInfo?.version ?? '0.1.0',
+  return createMcpServer(toolsResult.value, {
+    description: options.description ?? graph.description,
+    name: options.name ?? graph.name,
+    version: options.version ?? graph.version ?? '0.1.0',
   });
+};
+
+// ---------------------------------------------------------------------------
+// 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 connector.
+ */
+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/tsconfig.tests.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.test.ts", "src/__tests__/**/*.ts"],
+  "exclude": []
+}

package/tsconfig.tsbuildinfo

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