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

package/src/index.ts

@@ -1,11 +1,16 @@
 // Build
 export {
+  MCP_TOOL_ERROR_META_KEY,
+  MCP_TOOL_EXAMPLES_META_KEY,
   deriveMcpTools,
   type DeriveMcpToolsOptions,
   type McpToolDefinition,
   type McpToolResult,
+  type McpToolErrorMeta,
   type McpContent,
   type McpExtra,
+  type ResolveMcpPermit,
+  type ResolveMcpPermitInput,
 } from './build.js';
 
 // Tool naming

package/src/surface.ts

@@ -8,14 +8,14 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import type {
-  Intent,
+  BaseSurfaceOptions,
   Layer,
   ResourceOverrideMap,
   Topo,
   TrailContextInit,
 } from '@ontrails/core';
 
-import type { McpToolDefinition } from './build.js';
+import type { McpToolDefinition, ResolveMcpPermit } from './build.js';
 import { deriveMcpTools } from './build.js';
 import { connectStdio } from './stdio.js';
 
@@ -23,23 +23,15 @@ import { connectStdio } from './stdio.js';
 // Options
 // ---------------------------------------------------------------------------
 
-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;
+export interface CreateServerOptions extends BaseSurfaceOptions {
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | 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 resolvePermit?: ResolveMcpPermit | undefined;
   readonly version?: string | undefined;
 }
 
@@ -86,55 +78,76 @@ const createMcpServer = (
   // 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) => {
-    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>;
+  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>;
     }
-
-    const args = (request.params.arguments ?? {}) as Record<string, unknown>;
-    const progressToken = request.params._meta?.progressToken;
-
-    const sendProgress =
-      progressToken === undefined
-        ? undefined
-        : async (current: number, total: number) => {
-            await server.notification({
-              method: 'notifications/progress',
-              params: {
-                progress: current,
-                progressToken: progressToken,
-                total,
-              },
-            });
-          };
-
-    const extra = {
-      abortSignal: undefined as AbortSignal | undefined,
-      progressToken,
-      sendProgress,
-    };
-
-    const result = await tool.handler(args, extra);
-    // Spread to satisfy MCP SDK's index-signature requirement
-    return { ...result } as Record<string, unknown>;
-  });
+  );
 
   return server;
 };
@@ -145,6 +158,10 @@ const createMcpServer = (
 
 /**
  * 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.
  */
 export const createServer = (
   graph: Topo,
@@ -157,6 +174,7 @@ export const createServer = (
     include: options.include,
     intent: options.intent,
     layers: options.layers,
+    resolvePermit: options.resolvePermit,
     resources: options.resources,
     validate: options.validate,
   });
@@ -180,7 +198,7 @@ export const createServer = (
  * 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.
+ * `createServer(graph)` with `connectStdio` or your own adapter.
  */
 export const surface = async (
   graph: Topo,

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 68ms 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 fields.
- */
-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, unknown>, "intent" | "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,EAAU,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAMpD,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,EAAE,OAAO,CAAC,EAChC,QAAQ,GAAG,YAAY,GAAG,aAAa,CACxC,KACA,cAoBF,CAAC"}

package/dist/annotations.js

@@ -1,31 +0,0 @@
-/**
- * Derive MCP tool annotations from trail spec fields.
- */
-// ---------------------------------------------------------------------------
-// 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 = {};
-    const intentToHint = {
-        destroy: 'destructiveHint',
-        read: 'readOnlyHint',
-    };
-    const hint = intentToHint[trail.intent];
-    if (hint) {
-        annotations[hint] = 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,MAAM,YAAY,GAAoC;QACpD,OAAO,EAAE,iBAAiB;QAC1B,IAAI,EAAE,cAAc;KACrB,CAAC;IAEF,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,IAAI,EAAE,CAAC;QACT,WAAW,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3B,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"}

package/dist/build.d.ts

@@ -1,49 +0,0 @@
-/**
- * Build MCP tool definitions from a Trails graph.
- *
- * Iterates the topo, generates McpToolDefinition[] with handlers that
- * validate input, compose layers, execute the implementation, and map
- * Results to MCP responses.
- */
-import { Result } from '@ontrails/core';
-import type { Intent, Layer, ResourceOverrideMap, Topo, TrailContextInit } from '@ontrails/core';
-import type { McpAnnotations } from './annotations.js';
-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 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;
-}
-export interface McpToolDefinition {
-    readonly annotations: McpAnnotations | undefined;
-    readonly description: string | undefined;
-    readonly handler: (args: Record<string, unknown>, extra: McpExtra) => Promise<McpToolResult>;
-    readonly inputSchema: Record<string, unknown>;
-    readonly name: string;
-    /** The trail ID this tool was derived from. */
-    readonly trailId: string;
-}
-export interface McpExtra {
-    readonly progressToken?: string | number | undefined;
-    readonly sendProgress?: ((current: number, total: number) => Promise<void>) | undefined;
-    readonly abortSignal?: AbortSignal | undefined;
-}
-export interface McpToolResult {
-    readonly content: readonly McpContent[];
-    readonly isError?: boolean | undefined;
-}
-export interface McpContent {
-    readonly data?: string | undefined;
-    readonly mimeType?: string | undefined;
-    readonly text?: string | undefined;
-    readonly type: 'text' | 'image' | 'resource';
-    readonly uri?: string | undefined;
-}
-export declare const deriveMcpTools: (graph: Topo, options?: DeriveMcpToolsOptions) => Result<McpToolDefinition[], Error>;
-//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,MAAM,EAQP,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAEV,MAAM,EACN,KAAK,EACL,mBAAmB,EACnB,IAAI,EAEJ,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASvD,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjD,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,GACpD,SAAS,CAAC;IACd,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACrD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,QAAQ,KACZ,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,YAAY,CAAC,EAClB,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GACnD,SAAS,CAAC;IACd,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAsSD,eAAO,MAAM,cAAc,GACzB,OAAO,IAAI,EACX,UAAS,qBAA0B,KAClC,MAAM,CAAC,iBAAiB,EAAE,EAAE,KAAK,CAOnC,CAAC"}

package/dist/build.js

@@ -1,220 +0,0 @@
-/**
- * Build MCP tool definitions from a Trails graph.
- *
- * Iterates the topo, generates McpToolDefinition[] with handlers that
- * validate input, compose layers, execute the implementation, and map
- * Results to MCP responses.
- */
-import { Result, TRAILHEAD_KEY, ValidationError, executeTrail, filterSurfaceTrails, isBlobRef, validateEstablishedTopo, zodToJsonSchema, } from '@ontrails/core';
-import { deriveAnnotations } from './annotations.js';
-import { createMcpProgressCallback } from './progress.js';
-import { deriveToolName } from './tool-name.js';
-// ---------------------------------------------------------------------------
-// Internal helpers (defined before use)
-// ---------------------------------------------------------------------------
-/** Concatenate an array of Uint8Array chunks into a single Uint8Array. */
-const concatChunks = (chunks, totalLength) => {
-    const result = new Uint8Array(totalLength);
-    let offset = 0;
-    for (const chunk of chunks) {
-        result.set(chunk, offset);
-        offset += chunk.length;
-    }
-    return result;
-};
-/** Collect a ReadableStream into a single Uint8Array. */
-const collectStream = async (stream) => {
-    const reader = stream.getReader();
-    const chunks = [];
-    let totalLength = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done) {
-            break;
-        }
-        chunks.push(value);
-        totalLength += value.length;
-    }
-    return concatChunks(chunks, totalLength);
-};
-/** Resolve BlobRef data to Uint8Array (handles ReadableStream). */
-const resolveBlobData = (blob) => {
-    if (blob.data instanceof ReadableStream) {
-        return collectStream(blob.data);
-    }
-    return blob.data;
-};
-const uint8ArrayToBase64 = (bytes) => {
-    // Use btoa with manual conversion for runtime-agnostic base64
-    let binary = '';
-    for (const byte of bytes) {
-        binary += String.fromCodePoint(byte);
-    }
-    return btoa(binary);
-};
-const blobToContent = async (blob) => {
-    const bytes = await resolveBlobData(blob);
-    if (blob.mimeType.startsWith('image/')) {
-        return {
-            data: uint8ArrayToBase64(bytes),
-            mimeType: blob.mimeType,
-            type: 'image',
-        };
-    }
-    return {
-        mimeType: blob.mimeType,
-        type: 'resource',
-        uri: `blob://${blob.name}`,
-    };
-};
-/** Separate blob fields from non-blob fields in an object. */
-const separateBlobFields = async (obj) => {
-    const blobContents = [];
-    const textFields = {};
-    let hasBlobFields = false;
-    for (const [key, val] of Object.entries(obj)) {
-        if (isBlobRef(val)) {
-            hasBlobFields = true;
-            blobContents.push(await blobToContent(val));
-        }
-        else {
-            textFields[key] = val;
-        }
-    }
-    return { blobContents, hasBlobFields, textFields };
-};
-/** Serialize a mixed blob/text object to MCP content. */
-const serializeMixedObject = async (obj) => {
-    const { blobContents, hasBlobFields, textFields } = await separateBlobFields(obj);
-    if (!hasBlobFields) {
-        return undefined;
-    }
-    if (Object.keys(textFields).length > 0) {
-        blobContents.unshift({ text: JSON.stringify(textFields), type: 'text' });
-    }
-    return blobContents;
-};
-const serializeOutput = async (value) => {
-    if (isBlobRef(value)) {
-        return [await blobToContent(value)];
-    }
-    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-        const mixed = await serializeMixedObject(value);
-        if (mixed) {
-            return mixed;
-        }
-    }
-    return [{ text: JSON.stringify(value), type: 'text' }];
-};
-// ---------------------------------------------------------------------------
-// Handler factory
-// ---------------------------------------------------------------------------
-/** Create an error result for MCP responses. */
-const mcpError = (message) => ({
-    content: [{ text: message, type: 'text' }],
-    isError: true,
-});
-/** Add the MCP trailhead marker while preserving any existing context extras. */
-const withMcpTrailhead = (progressCb) => ({
-    ...(progressCb === undefined ? {} : { progress: progressCb }),
-    extensions: {
-        [TRAILHEAD_KEY]: 'mcp',
-    },
-});
-const createHandler = (graph, t, layers, options) => async (args, extra) => {
-    const progressCb = createMcpProgressCallback(extra);
-    const result = await executeTrail(t, args, {
-        abortSignal: extra.abortSignal,
-        configValues: options.configValues,
-        createContext: options.createContext,
-        ctx: withMcpTrailhead(progressCb),
-        layers,
-        resources: options.resources,
-        topo: graph,
-    });
-    if (result.isOk()) {
-        return { content: await serializeOutput(result.value) };
-    }
-    return mcpError(result.error.message);
-};
-// ---------------------------------------------------------------------------
-// Builder
-// ---------------------------------------------------------------------------
-/**
- * Build MCP tool definitions from a graph's topology.
- *
- * Each trail in the topo becomes an McpToolDefinition with:
- * - A derived tool name (topo-name-prefixed, underscore-delimited)
- * - JSON Schema input from zodToJsonSchema
- * - MCP annotations from trail meta
- * - A handler that validates, composes layers, executes, and maps results
- */
-/** Build a description with optional example input appended. */
-const buildDescription = (trail) => {
-    let { description } = trail;
-    if (description !== undefined &&
-        trail.examples !== undefined &&
-        trail.examples.length > 0) {
-        const [firstExample] = trail.examples;
-        if (firstExample !== undefined) {
-            description = `${description}\n\nExample input: ${JSON.stringify(firstExample.input)}`;
-        }
-    }
-    return description;
-};
-/** Build a single MCP tool definition from a trail. */
-const buildToolDefinition = (graph, trail, layers, options) => {
-    const rawAnnotations = deriveAnnotations(trail);
-    const annotations = Object.keys(rawAnnotations).length > 0 ? rawAnnotations : undefined;
-    return {
-        annotations,
-        description: buildDescription(trail),
-        handler: createHandler(graph, trail, layers, options),
-        inputSchema: zodToJsonSchema(trail.input),
-        name: deriveToolName(graph.name, trail.id),
-        trailId: trail.id,
-    };
-};
-/** Register a trail as an MCP tool, checking for name collisions. */
-const registerTool = (graph, trailItem, layers, options, nameToTrailId, tools) => {
-    const toolName = deriveToolName(graph.name, trailItem.id);
-    const existingId = nameToTrailId.get(toolName);
-    if (existingId !== undefined) {
-        return Result.err(new ValidationError(`MCP tool-name collision: trails "${existingId}" and "${trailItem.id}" both derive the tool name "${toolName}"`));
-    }
-    nameToTrailId.set(toolName, trailItem.id);
-    tools.push(buildToolDefinition(graph, trailItem, layers, options));
-    return Result.ok();
-};
-/** Filter topo items to eligible trails. */
-const eligibleTrails = (graph, options) => filterSurfaceTrails(graph.list(), {
-    exclude: options.exclude,
-    include: options.include,
-    intent: options.intent,
-});
-const validateToolBuild = (graph, options) => {
-    if (options.validate === false) {
-        return Result.ok();
-    }
-    const validated = validateEstablishedTopo(graph);
-    return validated.isErr() ? Result.err(validated.error) : Result.ok();
-};
-const registerTools = (graph, options, layers) => {
-    const tools = [];
-    const nameToTrailId = new Map();
-    for (const trailItem of eligibleTrails(graph, options)) {
-        const registered = registerTool(graph, trailItem, layers, options, nameToTrailId, tools);
-        if (registered.isErr()) {
-            return registered;
-        }
-    }
-    return Result.ok(tools);
-};
-export const deriveMcpTools = (graph, options = {}) => {
-    const validation = validateToolBuild(graph, options);
-    if (validation.isErr()) {
-        return validation;
-    }
-    return registerTools(graph, options, options.layers ?? []);
-};
-//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,7 +0,0 @@
-export { deriveMcpTools, type DeriveMcpToolsOptions, type McpToolDefinition, type McpToolResult, type McpContent, type McpExtra, } from './build.js';
-export { deriveToolName } from './tool-name.js';
-export { deriveAnnotations, type McpAnnotations } from './annotations.js';
-export { createMcpProgressCallback } from './progress.js';
-export { createServer, surface, type CreateServerOptions, type SurfaceMcpResult, } from './surface.js';
-export { connectStdio } from './stdio.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,QAAQ,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAG1E,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EACL,YAAY,EACZ,OAAO,EACP,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,13 +0,0 @@
-// Build
-export { deriveMcpTools, } from './build.js';
-// Tool naming
-export { deriveToolName } from './tool-name.js';
-// Annotations
-export { deriveAnnotations } from './annotations.js';
-// Progress
-export { createMcpProgressCallback } from './progress.js';
-// Surface
-export { createServer, surface, } from './surface.js';
-// Transport
-export { connectStdio } from './stdio.js';
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,OAAO,EACL,cAAc,GAMf,MAAM,YAAY,CAAC;AAEpB,cAAc;AACd,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,cAAc;AACd,OAAO,EAAE,iBAAiB,EAAuB,MAAM,kBAAkB,CAAC;AAE1E,WAAW;AACX,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE1D,UAAU;AACV,OAAO,EACL,YAAY,EACZ,OAAO,GAGR,MAAM,cAAc,CAAC;AAEtB,YAAY;AACZ,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/progress.d.ts

@@ -1,13 +0,0 @@
-/**
- * Bridge Trails ProgressCallback to MCP sendProgress notifications.
- */
-import type { ProgressCallback } from '@ontrails/core';
-import type { McpExtra } from './build.js';
-/**
- * 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).
- */
-export declare const createMcpProgressCallback: (extra: McpExtra) => ProgressCallback | undefined;
-//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAiB,MAAM,gBAAgB,CAAC;AAEtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA6C3C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,OAAO,QAAQ,KACd,gBAAgB,GAAG,SAarB,CAAC"}