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

package/src/build.ts

@@ -7,12 +7,20 @@
  */
 
 import {
-  composeLayers,
-  createTrailContext,
-  validateInput,
+  Result,
+  ValidationError,
+  executeTrail,
+  isBlobRef,
   zodToJsonSchema,
 } from '@ontrails/core';
-import type { Layer, Topo, Trail, TrailContext } from '@ontrails/core';
+import type {
+  BlobRef,
+  Layer,
+  ServiceOverrideMap,
+  Topo,
+  Trail,
+  TrailContextInit,
+} from '@ontrails/core';
 
 import type { McpAnnotations } from './annotations.js';
 import { deriveAnnotations } from './annotations.js';
@@ -25,11 +33,12 @@ import { deriveToolName } from './tool-name.js';
 
 export interface BuildMcpToolsOptions {
   readonly createContext?:
-    | (() => TrailContext | Promise<TrailContext>)
+    | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
   readonly excludeTrails?: readonly string[] | undefined;
   readonly includeTrails?: readonly string[] | undefined;
   readonly layers?: readonly Layer[] | undefined;
+  readonly services?: ServiceOverrideMap | undefined;
 }
 
 export interface McpToolDefinition {
@@ -41,6 +50,8 @@ export interface McpToolDefinition {
   ) => Promise<McpToolResult>;
   readonly inputSchema: Record<string, unknown>;
   readonly name: string;
+  /** The trail ID this tool was derived from. */
+  readonly trailId: string;
 }
 
 export interface McpExtra {
@@ -68,23 +79,44 @@ export interface McpContent {
 // Internal helpers (defined before use)
 // ---------------------------------------------------------------------------
 
-interface BlobRef {
-  readonly data: Uint8Array;
-  readonly kind: 'blob';
-  readonly mimeType: string;
-  readonly name?: string | undefined;
-}
+/** Concatenate an array of Uint8Array chunks into a single Uint8Array. */
+const concatChunks = (
+  chunks: Uint8Array[],
+  totalLength: number
+): Uint8Array => {
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
+};
 
-const isBlobRef = (value: unknown): value is BlobRef => {
-  if (typeof value !== 'object' || value === null) {
-    return false;
+/** Collect a ReadableStream into a single Uint8Array. */
+const collectStream = async (
+  stream: ReadableStream<Uint8Array>
+): Promise<Uint8Array> => {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalLength = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    chunks.push(value);
+    totalLength += value.length;
   }
-  const obj = value as Record<string, unknown>;
-  return (
-    obj['kind'] === 'blob' &&
-    obj['data'] instanceof Uint8Array &&
-    typeof obj['mimeType'] === 'string'
-  );
+  return concatChunks(chunks, totalLength);
+};
+
+/** Resolve BlobRef data to Uint8Array (handles ReadableStream). */
+const resolveBlobData = (blob: BlobRef): Promise<Uint8Array> | Uint8Array => {
+  if (blob.data instanceof ReadableStream) {
+    return collectStream(blob.data);
+  }
+  return blob.data;
 };
 
 const uint8ArrayToBase64 = (bytes: Uint8Array): string => {
@@ -96,10 +128,11 @@ const uint8ArrayToBase64 = (bytes: Uint8Array): string => {
   return btoa(binary);
 };
 
-const blobToContent = (blob: BlobRef): McpContent => {
+const blobToContent = async (blob: BlobRef): Promise<McpContent> => {
+  const bytes = await resolveBlobData(blob);
   if (blob.mimeType.startsWith('image/')) {
     return {
-      data: uint8ArrayToBase64(blob.data),
+      data: uint8ArrayToBase64(bytes),
       mimeType: blob.mimeType,
       type: 'image',
     };
@@ -108,25 +141,25 @@ const blobToContent = (blob: BlobRef): McpContent => {
   return {
     mimeType: blob.mimeType,
     type: 'resource',
-    uri: `blob://${blob.name ?? 'unnamed'}`,
+    uri: `blob://${blob.name}`,
   };
 };
 
 /** Separate blob fields from non-blob fields in an object. */
-const separateBlobFields = (
+const separateBlobFields = async (
   obj: Record<string, unknown>
-): {
+): Promise<{
   blobContents: McpContent[];
   hasBlobFields: boolean;
   textFields: Record<string, unknown>;
-} => {
+}> => {
   const blobContents: McpContent[] = [];
   const textFields: Record<string, unknown> = {};
   let hasBlobFields = false;
   for (const [key, val] of Object.entries(obj)) {
     if (isBlobRef(val)) {
       hasBlobFields = true;
-      blobContents.push(blobToContent(val));
+      blobContents.push(await blobToContent(val));
     } else {
       textFields[key] = val;
     }
@@ -135,10 +168,11 @@ const separateBlobFields = (
 };
 
 /** Serialize a mixed blob/text object to MCP content. */
-const serializeMixedObject = (
+const serializeMixedObject = async (
   obj: Record<string, unknown>
-): readonly McpContent[] | undefined => {
-  const { blobContents, hasBlobFields, textFields } = separateBlobFields(obj);
+): Promise<readonly McpContent[] | undefined> => {
+  const { blobContents, hasBlobFields, textFields } =
+    await separateBlobFields(obj);
   if (!hasBlobFields) {
     return undefined;
   }
@@ -148,12 +182,14 @@ const serializeMixedObject = (
   return blobContents;
 };
 
-const serializeOutput = (value: unknown): readonly McpContent[] => {
+const serializeOutput = async (
+  value: unknown
+): Promise<readonly McpContent[]> => {
   if (isBlobRef(value)) {
-    return [blobToContent(value)];
+    return [await blobToContent(value)];
   }
   if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-    const mixed = serializeMixedObject(value as Record<string, unknown>);
+    const mixed = await serializeMixedObject(value as Record<string, unknown>);
     if (mixed) {
       return mixed;
     }
@@ -171,48 +207,9 @@ const mcpError = (message: string): McpToolResult => ({
   isError: true,
 });
 
-/** Build a TrailContext from options and MCP extra. */
-const buildTrailContext = async (
-  options: BuildMcpToolsOptions,
-  extra: McpExtra
-): Promise<TrailContext> => {
-  const baseContext =
-    options.createContext !== undefined && options.createContext !== null
-      ? await options.createContext()
-      : createTrailContext();
-
-  const signal = extra.signal ?? baseContext.signal;
-  const progressCb = createMcpProgressCallback(extra);
-
-  return {
-    ...baseContext,
-    signal,
-    ...(progressCb === undefined ? {} : { progress: progressCb }),
-  };
-};
-
-/** Execute a trail and map the result to an MCP response. */
-const executeAndMap = async (
-  trail: Trail<unknown, unknown>,
-  validatedInput: unknown,
-  ctx: TrailContext,
-  layers: readonly Layer[]
-): Promise<McpToolResult> => {
-  const impl = composeLayers([...layers], trail, trail.implementation);
-  try {
-    const result = await impl(validatedInput, ctx);
-    if (result.isOk()) {
-      return { content: serializeOutput(result.value) };
-    }
-    return mcpError(result.error.message);
-  } catch (error: unknown) {
-    return mcpError(error instanceof Error ? error.message : String(error));
-  }
-};
-
 const createHandler =
   (
-    trail: Trail<unknown, unknown>,
+    t: Trail<unknown, unknown>,
     layers: readonly Layer[],
     options: BuildMcpToolsOptions
   ): ((
@@ -220,12 +217,18 @@ const createHandler =
     extra: McpExtra
   ) => Promise<McpToolResult>) =>
   async (args, extra): Promise<McpToolResult> => {
-    const validated = validateInput(trail.input, args);
-    if (validated.isErr()) {
-      return mcpError(validated.error.message);
+    const progressCb = createMcpProgressCallback(extra);
+    const result = await executeTrail(t, args, {
+      createContext: options.createContext,
+      ctx: progressCb === undefined ? undefined : { progress: progressCb },
+      layers,
+      services: options.services,
+      signal: extra.signal,
+    });
+    if (result.isOk()) {
+      return { content: await serializeOutput(result.value) };
     }
-    const ctx = await buildTrailContext(options, extra);
-    return executeAndMap(trail, validated.value, ctx, layers);
+    return mcpError(result.error.message);
   };
 
 // ---------------------------------------------------------------------------
@@ -238,15 +241,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 markers
+ * - MCP annotations from trail metadata
  * - A handler that validates, composes layers, executes, and maps results
  */
-/** Check if a trail should be included based on markers and filters. */
+/** Check if a trail should be included based on metadata and filters. */
 const shouldInclude = (
   trail: Trail<unknown, unknown>,
   options: BuildMcpToolsOptions
 ): boolean => {
-  if (trail.markers?.['internal'] === true) {
+  if (trail.metadata?.['internal'] === true) {
     return false;
   }
   if (options.includeTrails !== undefined && options.includeTrails.length > 0) {
@@ -295,27 +298,61 @@ const buildToolDefinition = (
     handler: createHandler(trail, layers, options),
     inputSchema: zodToJsonSchema(trail.input),
     name: deriveToolName(app.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>,
+  layers: readonly Layer[],
+  options: BuildMcpToolsOptions,
+  nameToTrailId: Map<string, string>,
+  tools: McpToolDefinition[]
+): Result<void, Error> => {
+  const toolName = deriveToolName(app.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(app, 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));
+
 export const buildMcpTools = (
   app: Topo,
   options: BuildMcpToolsOptions = {}
-): McpToolDefinition[] => {
+): Result<McpToolDefinition[], Error> => {
   const layers = options.layers ?? [];
   const tools: McpToolDefinition[] = [];
+  const nameToTrailId = new Map<string, string>();
 
-  for (const item of app.list()) {
-    if (item.kind !== 'trail' && item.kind !== 'hike') {
-      continue;
-    }
-    if (!shouldInclude(item as Trail<unknown, unknown>, options)) {
-      continue;
-    }
-    tools.push(
-      buildToolDefinition(app, item as Trail<unknown, unknown>, layers, options)
+  for (const trailItem of eligibleTrails(app, options)) {
+    const registered = registerTool(
+      app,
+      trailItem,
+      layers,
+      options,
+      nameToTrailId,
+      tools
     );
+    if (registered.isErr()) {
+      return registered;
+    }
   }
 
-  return tools;
+  return Result.ok(tools);
 };