@ontrails/mcp 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/build.js

@@ -5,18 +5,44 @@
  * validate input, compose layers, execute the implementation, and map
  * Results to MCP responses.
  */
-import { composeLayers, createTrailContext, validateInput, zodToJsonSchema, } from '@ontrails/core';
+import { Result, ValidationError, executeTrail, isBlobRef, zodToJsonSchema, } from '@ontrails/core';
 import { deriveAnnotations } from './annotations.js';
 import { createMcpProgressCallback } from './progress.js';
 import { deriveToolName } from './tool-name.js';
-const isBlobRef = (value) => {
-    if (typeof value !== 'object' || value === null) {
-        return false;
+// ---------------------------------------------------------------------------
+// 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;
     }
-    const obj = value;
-    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) => {
+    if (blob.data instanceof ReadableStream) {
+        return collectStream(blob.data);
+    }
+    return blob.data;
 };
 const uint8ArrayToBase64 = (bytes) => {
     // Use btoa with manual conversion for runtime-agnostic base64
@@ -26,10 +52,11 @@ const uint8ArrayToBase64 = (bytes) => {
     }
     return btoa(binary);
 };
-const blobToContent = (blob) => {
+const blobToContent = async (blob) => {
+    const bytes = await resolveBlobData(blob);
     if (blob.mimeType.startsWith('image/')) {
         return {
-            data: uint8ArrayToBase64(blob.data),
+            data: uint8ArrayToBase64(bytes),
             mimeType: blob.mimeType,
             type: 'image',
         };
@@ -37,18 +64,18 @@ const blobToContent = (blob) => {
     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 = (obj) => {
+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(blobToContent(val));
+            blobContents.push(await blobToContent(val));
         }
         else {
             textFields[key] = val;
@@ -57,8 +84,8 @@ const separateBlobFields = (obj) => {
     return { blobContents, hasBlobFields, textFields };
 };
 /** Serialize a mixed blob/text object to MCP content. */
-const serializeMixedObject = (obj) => {
-    const { blobContents, hasBlobFields, textFields } = separateBlobFields(obj);
+const serializeMixedObject = async (obj) => {
+    const { blobContents, hasBlobFields, textFields } = await separateBlobFields(obj);
     if (!hasBlobFields) {
         return undefined;
     }
@@ -67,12 +94,12 @@ const serializeMixedObject = (obj) => {
     }
     return blobContents;
 };
-const serializeOutput = (value) => {
+const serializeOutput = async (value) => {
     if (isBlobRef(value)) {
-        return [blobToContent(value)];
+        return [await blobToContent(value)];
     }
     if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-        const mixed = serializeMixedObject(value);
+        const mixed = await serializeMixedObject(value);
         if (mixed) {
             return mixed;
         }
@@ -87,40 +114,18 @@ const mcpError = (message) => ({
     content: [{ text: message, type: 'text' }],
     isError: true,
 });
-/** Build a TrailContext from options and MCP extra. */
-const buildTrailContext = async (options, extra) => {
-    const baseContext = options.createContext !== undefined && options.createContext !== null
-        ? await options.createContext()
-        : createTrailContext();
-    const signal = extra.signal ?? baseContext.signal;
+const createHandler = (t, layers, options) => async (args, extra) => {
     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, validatedInput, ctx, layers) => {
-    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) {
-        return mcpError(error instanceof Error ? error.message : String(error));
-    }
-};
-const createHandler = (trail, layers, options) => async (args, extra) => {
-    const validated = validateInput(trail.input, args);
-    if (validated.isErr()) {
-        return mcpError(validated.error.message);
-    }
-    const ctx = await buildTrailContext(options, extra);
-    return executeAndMap(trail, validated.value, ctx, layers);
+    const result = await executeTrail(t, args, {
+        createContext: options.createContext,
+        ctx: progressCb === undefined ? undefined : { progress: progressCb },
+        layers,
+        signal: extra.signal,
+    });
+    if (result.isOk()) {
+        return { content: await serializeOutput(result.value) };
+    }
+    return mcpError(result.error.message);
 };
 // ---------------------------------------------------------------------------
 // Builder
@@ -131,12 +136,12 @@ const createHandler = (trail, layers, options) => async (args, extra) => {
  * 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, options) => {
-    if (trail.markers?.['internal'] === true) {
+    if (trail.metadata?.['internal'] === true) {
         return false;
     }
     if (options.includeTrails !== undefined && options.includeTrails.length > 0) {
@@ -171,20 +176,32 @@ const buildToolDefinition = (app, trail, layers, options) => {
         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, trailItem, layers, options, nameToTrailId, tools) => {
+    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, options) => app.list().filter((trail) => shouldInclude(trail, options));
 export const buildMcpTools = (app, options = {}) => {
     const layers = options.layers ?? [];
     const tools = [];
-    for (const item of app.list()) {
-        if (item.kind !== 'trail' && item.kind !== 'hike') {
-            continue;
-        }
-        if (!shouldInclude(item, options)) {
-            continue;
+    const nameToTrailId = new Map();
+    for (const trailItem of eligibleTrails(app, options)) {
+        const registered = registerTool(app, trailItem, layers, options, nameToTrailId, tools);
+        if (registered.isErr()) {
+            return registered;
         }
-        tools.push(buildToolDefinition(app, item, layers, options));
     }
-    return tools;
+    return Result.ok(tools);
 };
 //# sourceMappingURL=build.js.map

package/dist/build.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/mcp",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.10",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,10 +14,10 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "workspace:*"
+    "@ontrails/core": "^1.0.0-beta.8"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "catalog:"
+    "zod": "^4.3.5"
   }
 }

package/src/__tests__/annotations.test.ts

@@ -3,36 +3,39 @@ import { describe, expect, test } from 'bun:test';
 import { deriveAnnotations } from '../annotations.js';
 
 describe('deriveAnnotations', () => {
-  test('readOnly trail produces readOnlyHint', () => {
-    const annotations = deriveAnnotations({ readOnly: true });
+  test('read intent produces readOnlyHint', () => {
+    const annotations = deriveAnnotations({ intent: 'read' });
     expect(annotations.readOnlyHint).toBe(true);
     expect(annotations.destructiveHint).toBeUndefined();
     expect(annotations.idempotentHint).toBeUndefined();
   });
 
-  test('destructive trail produces destructiveHint', () => {
-    const annotations = deriveAnnotations({ destructive: true });
+  test('destroy intent produces destructiveHint', () => {
+    const annotations = deriveAnnotations({ intent: 'destroy' });
     expect(annotations.destructiveHint).toBe(true);
     expect(annotations.readOnlyHint).toBeUndefined();
   });
 
   test('idempotent trail produces idempotentHint', () => {
-    const annotations = deriveAnnotations({ idempotent: true });
+    const annotations = deriveAnnotations({
+      idempotent: true,
+      intent: 'write',
+    });
     expect(annotations.idempotentHint).toBe(true);
   });
 
-  test('multiple markers combine correctly', () => {
+  test('read intent with idempotent combines correctly', () => {
     const annotations = deriveAnnotations({
       idempotent: true,
-      readOnly: true,
+      intent: 'read',
     });
     expect(annotations.readOnlyHint).toBe(true);
     expect(annotations.idempotentHint).toBe(true);
     expect(annotations.destructiveHint).toBeUndefined();
   });
 
-  test('no markers produces empty annotations', () => {
-    const annotations = deriveAnnotations({});
+  test('write intent produces empty annotations', () => {
+    const annotations = deriveAnnotations({ intent: 'write' });
     expect(annotations.readOnlyHint).toBeUndefined();
     expect(annotations.destructiveHint).toBeUndefined();
     expect(annotations.idempotentHint).toBeUndefined();
@@ -42,29 +45,19 @@ describe('deriveAnnotations', () => {
   test('description maps to title', () => {
     const annotations = deriveAnnotations({
       description: 'Show entity details',
+      intent: 'write',
     });
     expect(annotations.title).toBe('Show entity details');
   });
 
-  test('all markers plus description', () => {
+  test('all hints plus description', () => {
     const annotations = deriveAnnotations({
       description: 'A trail',
-      destructive: true,
       idempotent: true,
-      readOnly: true,
+      intent: 'destroy',
     });
-    expect(annotations.readOnlyHint).toBe(true);
     expect(annotations.destructiveHint).toBe(true);
     expect(annotations.idempotentHint).toBe(true);
     expect(annotations.title).toBe('A trail');
   });
-
-  test('false values are not included', () => {
-    const annotations = deriveAnnotations({
-      destructive: false,
-      readOnly: false,
-    });
-    expect(annotations.readOnlyHint).toBeUndefined();
-    expect(annotations.destructiveHint).toBeUndefined();
-  });
 });

package/src/__tests__/blaze.test.ts

@@ -3,14 +3,15 @@ import { describe, expect, test } from 'bun:test';
 import { Result, trail, topo } from '@ontrails/core';
 import { z } from 'zod';
 
-import { createMcpServer } from '../blaze.js';
+import { blaze, createMcpServer } from '../blaze.js';
 import { buildMcpTools } from '../build.js';
+import type { McpToolDefinition } from '../build.js';
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-const requireTool = (tools: ReturnType<typeof buildMcpTools>, name: string) => {
+const requireTool = (tools: McpToolDefinition[], name: string) => {
   const tool = tools.find((entry) => entry.name === name);
   expect(tool).toBeDefined();
   if (!tool) {
@@ -19,35 +20,79 @@ const requireTool = (tools: ReturnType<typeof buildMcpTools>, name: string) => {
   return tool;
 };
 
+/**
+ * Unwrap buildMcpTools result, throwing on error so test failures surface clearly.
+ */
+const buildTools = (
+  ...args: Parameters<typeof buildMcpTools>
+): McpToolDefinition[] => {
+  const result = buildMcpTools(...args);
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
 const createIntegrationTools = () => {
   const greetTrail = trail('greet', {
     description: 'Greet someone',
-    implementation: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
     input: z.object({ name: z.string() }),
-    readOnly: true,
+    intent: 'read',
+    run: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
   });
 
   const deleteTrail = trail('item.delete', {
     description: 'Delete an item',
-    destructive: true,
-    implementation: (_input) => Result.ok({ deleted: true }),
     input: z.object({ id: z.string() }),
+    intent: 'destroy',
+    run: (_input) => Result.ok({ deleted: true }),
   });
 
-  return buildMcpTools(topo('myapp', { deleteTrail, greetTrail }));
+  return buildTools(topo('myapp', { deleteTrail, greetTrail }));
 };
 
 describe('blaze', () => {
+  test('blaze throws on invalid topo', async () => {
+    const t = trail('broken', {
+      follow: ['nonexistent.trail'],
+      input: z.object({}),
+      output: z.object({}),
+      run: () => Result.ok({}),
+    });
+    const app = topo('test', { t });
+    await expect(blaze(app)).rejects.toThrow(/validation/i);
+  });
+
+  test('blaze skips validation when validate: false', async () => {
+    const t = trail('broken', {
+      follow: ['nonexistent.trail'],
+      input: z.object({}),
+      output: z.object({}),
+      run: () => Result.ok({}),
+    });
+    const app = topo('test', { t });
+    const result = await Promise.race([
+      blaze(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(() => {
+          resolve('timeout');
+        }, 50);
+      }),
+    ]);
+    expect(['resolved', 'timeout']).toContain(result);
+  });
+
   test('createMcpServer registers tools that can be listed', () => {
     const echoTrail = trail('echo', {
       description: 'Echo',
-      implementation: (input) => Result.ok({ reply: input.message }),
       input: z.object({ message: z.string() }),
-      readOnly: true,
+      intent: 'read',
+      run: (input) => Result.ok({ reply: input.message }),
     });
 
     const app = topo('testapp', { echoTrail });
-    const tools = buildMcpTools(app);
+    const tools = buildTools(app);
     const server = createMcpServer(tools, {
       name: 'testapp',
       version: '0.1.0',
@@ -60,19 +105,19 @@ describe('blaze', () => {
   test('createMcpServer handles multiple tools', () => {
     const echoTrail = trail('echo', {
       description: 'Echo',
-      implementation: (input) => Result.ok({ reply: input.message }),
       input: z.object({ message: z.string() }),
+      run: (input) => Result.ok({ reply: input.message }),
     });
 
     const searchTrail = trail('search', {
       description: 'Search',
-      implementation: (input) => Result.ok({ results: [input.query] }),
       input: z.object({ query: z.string() }),
-      readOnly: true,
+      intent: 'read',
+      run: (input) => Result.ok({ results: [input.query] }),
     });
 
     const app = topo('testapp', { echoTrail, searchTrail });
-    const tools = buildMcpTools(app);
+    const tools = buildTools(app);
 
     expect(tools).toHaveLength(2);