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

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 54ms on 12 files with 93 rules using 24 threads.
+Finished in 67ms on 12 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,151 @@
 # @ontrails/mcp
 
+## 1.0.0-beta.11
+
+### Patch Changes
+
+- Add services as a first-class primitive.
+
+  Services make infrastructure dependencies declarative, injectable, and governable. Define a service with `service()`, declare it on a trail with `services: [db]`, and access it with `db.from(ctx)` or `ctx.service()`.
+
+  **Core:** `service()` factory, `ServiceSpec<T>`, `ServiceContext`, singleton resolution in `executeTrail`, in-flight creation dedup, `isService` guard, `findDuplicateServiceId`, topo service discovery and validation, `services` field on trail specs.
+
+  **Testing:** Auto-resolution of `mock` factories in `testAll`, `testExamples`, `testContracts`, and `testFollows`. Explicit `services` overrides with correct precedence (`explicit > ctx.extensions > auto-mock`). Service mock propagation through follow graphs.
+
+  **Warden:** `service-declarations` rule validates `db.from(ctx)` and `ctx.service()` usage matches declared `services: [...]`. `service-exists` rule validates declared service IDs resolve in project context. Scope-aware AST walking skips nested function boundaries.
+
+  **Surfaces:** Service overrides thread through `dispatch` and `blaze` on CLI, MCP, and HTTP.
+
+  **Introspection:** Survey and surface map outputs include service graph. Topo exposes `.services`, `.getService()`, `.hasService()`, `.listServices()`, `.serviceIds()`, `.serviceCount`.
+
+  **Docs:** ADR-009 accepted. Unified services guide, updated vocabulary, getting-started, architecture, and package READMEs.
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.11
+
+## 1.0.0-beta.10
+
+### Patch Changes
+
+- Cleanup and hardening pass across all packages.
+
+  **core**: Deduplicate `DispatchOptions` as type alias of `ExecuteTrailOptions`. Replace `TrailContext` index signature with typed `extensions` field for type safety. Deep-merge `extensions` in `executeTrail` context resolution. Remove unused `Surface` type, `adapters.ts`, `health.ts`, and `job.ts` proof-of-concept from published package.
+
+  **cli**: Remove vestigial `kind` checks from build. Run `validateTopo()` automatically in `blaze()` with opt-out via `validate: false`.
+
+  **http**: Remove vestigial `kind` checks from build. Run `validateTopo()` automatically in `blaze()` with opt-out.
+
+  **mcp**: Remove vestigial `kind` checks from build. Run `validateTopo()` automatically in `blaze()` with opt-out.
+
+  **warden**: Project-aware rule context preserved in trail wrappers.
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.10
+
+## 1.0.0-beta.9
+
+### Minor Changes
+
+- Consolidated improvements across all surface packages.
+
+  **core**: Add `TrailResult<T>` utility type, `topo.ids()` and `topo.count` accessors, `dispatch()` for headless trail execution, and extract shared `executeTrail` pipeline used by CLI/MCP/HTTP.
+
+  **http**: Detect route path collisions and return `Result` from `buildHttpRoutes()`, wire request `AbortSignal` through to trail context, and make write → POST mapping explicit in intent-to-method lookup.
+
+  **mcp**: Return `Result` from `buildMcpTools()` on collision instead of throwing.
+
+  **cli**: Verify exception catching via centralized `executeTrail`.
+
+  **testing**: Follow context awareness improvements.
+
+  **warden**: Refactor rules as composable trails with examples.
+
+  **schema**: Error code and empty body fixes.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.9
+
+## 1.0.0-beta.8
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.8
+
+## 1.0.0-beta.7
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.7
+
+## 1.0.0-beta.6
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.6
+
+## 1.0.0-beta.5
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.5
+
+## 1.0.0-beta.4
+
+### Major Changes
+
+- API simplification: unified trail model, intent enum, run, metadata.
+
+  **BREAKING CHANGES:**
+
+  - `hike()` removed — use `trail()` with optional `follow: [...]` field
+  - `follows` renamed to `follow` (singular, matching `ctx.follow()`)
+  - `topo.hikes` removed — single `topo.trails` map
+  - `kind: 'hike'` removed — everything is `kind: 'trail'`
+  - `readOnly`/`destructive` booleans replaced by `intent: 'read' | 'write' | 'destroy'`
+  - `implementation` field renamed to `run`
+  - `markers` field renamed to `metadata`
+  - `testHike` renamed to `testFollows`, `HikeScenario` to `FollowScenario`
+  - `blaze()` now returns the surface handle (`Command` for CLI, `Server` for MCP)
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.4
+
+## 1.0.0-beta.3
+
+### Minor Changes
+
+- Bug fixes across all surface packages found via parallel Codex review.
+
+  **core**: Fix Result.toJson false circular detection on DAGs, deserializeError subclass round-trip, topo cross-kind ID collisions, validateTopo multi-node cycle detection, error example input validation bypass, and deriveFields array type collapse.
+
+  **cli**: Switch blaze to parseAsync for proper async error handling, add boolean flag negation (--no-flag), and strict number parsing that rejects partial input.
+
+  **mcp**: Align BlobRef with core (including ReadableStream support) and detect tool-name collisions after normalization.
+
+  **testing**: Include hikes in testContracts validation, with follow-context awareness.
+
+  **warden**: Collect hike detour targets, validate detour refs in hike specs, and stop implementation-returns-result from walking into nested function bodies.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.3
+
+## 1.0.0-beta.2
+
+### Patch Changes
+
+- Fix workspace dependency resolution in published packages. Now using bun publish
+  which correctly replaces workspace:^ with actual version numbers.
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.2
+
 ## 1.0.0-beta.1
 
 ### Patch Changes

package/README.md

@@ -11,8 +11,8 @@ import { z } from 'zod';
 
 const greet = trail('greet', {
   input: z.object({ name: z.string().describe('Who to greet') }),
-  readOnly: true,
-  implementation: (input) => Result.ok(`Hello, ${input.name}!`),
+  intent: 'read',
+  run: (input) => Result.ok(`Hello, ${input.name}!`),
 });
 
 const app = topo('myapp', { greet });
@@ -26,8 +26,9 @@ For more control, build the tools yourself:
 ```typescript
 import { buildMcpTools } from '@ontrails/mcp';
 
-const tools = buildMcpTools(app);
-for (const tool of tools) {
+const result = buildMcpTools(app);
+if (result.isErr()) throw result.error; // ValidationError on tool-name collision
+for (const tool of result.value) {
   server.registerTool(tool.name, tool.handler, {
     inputSchema: tool.inputSchema,
     annotations: tool.annotations,
@@ -35,6 +36,8 @@ for (const tool of tools) {
 }
 ```
 
+`buildMcpTools` returns `Result<McpToolDefinition[], Error>` rather than a bare array. It returns `Result.err(ValidationError)` if two trails derive the same MCP tool name. Each `McpToolDefinition` includes a `trailId` field that records which trail the tool was derived from.
+
 ## API
 
 | Export | What it does |
@@ -42,19 +45,19 @@ for (const tool of tools) {
 | `blaze(app, options?)` | Start an MCP server with all trails as tools |
 | `buildMcpTools(app, options?)` | Build tool definitions without starting a server |
 | `deriveToolName(appName, trailId)` | Compute the MCP tool name from app and trail IDs |
-| `deriveAnnotations(trail)` | Extract MCP annotations from trail markers |
+| `deriveAnnotations(trail)` | Extract MCP annotations from trail intent and metadata |
 | `createMcpProgressCallback(server)` | Bridge `ctx.progress` to MCP `notifications/progress` |
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
 ## Annotations
 
-Trail markers map directly to MCP annotations:
+Trail intent and metadata map directly to MCP annotations:
 
 | Trail field | MCP annotation |
 | --- | --- |
-| `readOnly: true` | `readOnlyHint: true` |
-| `destructive: true` | `destructiveHint: true` |
+| `intent: 'read'` | `readOnlyHint: true` |
+| `intent: 'destroy'` | `destructiveHint: true` |
 | `idempotent: true` | `idempotentHint: true` |
 | `description` | `title` |
 
@@ -64,13 +67,17 @@ No manual annotation definitions. The contract is the source of truth.
 
 Trail IDs become MCP tool names with the app prefix: `entity.show` in app `myapp` becomes `myapp_entity_show`. Dots and hyphens become underscores, everything lowercase.
 
+## Service resolution
+
+Declared services on each trail are resolved into the context before the implementation runs.
+
 ## Progress bridge
 
 Implementations report progress through `ctx.progress`. On MCP, these bridge to `notifications/progress` when the client sends a `progressToken`:
 
 ```typescript
 const importTrail = trail('data.import', {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     for (let i = 0; i < items.length; i++) {
       await processItem(items[i]);
       ctx.progress?.({ type: 'progress', current: i + 1, total: items.length });

package/dist/annotations.d.ts

@@ -1,5 +1,5 @@
 /**
- * Derive MCP tool annotations from trail spec markers.
+ * Derive MCP tool annotations from trail spec fields.
  */
 import type { Trail } from '@ontrails/core';
 export interface McpAnnotations {
@@ -15,5 +15,5 @@ export interface McpAnnotations {
  * 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>, "readOnly" | "destructive" | "idempotent" | "description">) => McpAnnotations;
+export declare const deriveAnnotations: (trail: Pick<Trail<unknown, unknown>, "intent" | "idempotent" | "description">) => McpAnnotations;
 //# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAM5C,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,CAAC,EACvB,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,aAAa,CAC1D,KACA,cAiBF,CAAC"}
+{"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,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC,KAC5E,cAoBF,CAAC"}

package/dist/annotations.js

@@ -1,5 +1,5 @@
 /**
- * Derive MCP tool annotations from trail spec markers.
+ * Derive MCP tool annotations from trail spec fields.
  */
 // ---------------------------------------------------------------------------
 // Derivation
@@ -12,11 +12,13 @@
  */
 export const deriveAnnotations = (trail) => {
     const annotations = {};
-    if (trail.readOnly === true) {
-        annotations['readOnlyHint'] = true;
-    }
-    if (trail.destructive === true) {
-        annotations['destructiveHint'] = true;
+    const intentToHint = {
+        destroy: 'destructiveHint',
+        read: 'readOnlyHint',
+    };
+    const hint = intentToHint[trail.intent];
+    if (hint) {
+        annotations[hint] = true;
     }
     if (trail.idempotent === true) {
         annotations['idempotentHint'] = true;

package/dist/annotations.js.map

@@ -1 +1 @@
-{"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,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC5B,WAAW,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;IACrC,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAC/B,WAAW,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC;IACxC,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"}
+{"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,KAA6E,EAC7D,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/blaze.d.ts

@@ -9,10 +9,10 @@
  * ```
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { Layer, Topo, TrailContext } from '@ontrails/core';
+import type { Layer, ServiceOverrideMap, Topo, TrailContextInit } from '@ontrails/core';
 import type { McpToolDefinition } from './build.js';
 export interface BlazeMcpOptions {
-    readonly createContext?: (() => TrailContext | Promise<TrailContext>) | undefined;
+    readonly createContext?: (() => TrailContextInit | Promise<TrailContextInit>) | undefined;
     readonly excludeTrails?: readonly string[] | undefined;
     readonly includeTrails?: readonly string[] | undefined;
     readonly layers?: readonly Layer[] | undefined;
@@ -21,6 +21,9 @@ export interface BlazeMcpOptions {
         readonly version?: string | undefined;
     } | 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;
 }
 /**
  * Create an MCP Server instance and register all tools.

package/dist/blaze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blaze.d.ts","sourceRoot":"","sources":["../src/blaze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAQpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,GAC5C,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAChB;QACE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACvC,GACD,SAAS,CAAC;IACd,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC1C;AAMD;;GAEG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,iBAAiB,EAAE,EAC1B,MAAM;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KACxD,MAmEF,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,KAAK,GAChB,KAAK,IAAI,EACT,UAAS,eAAoB,KAC5B,OAAO,CAAC,IAAI,CAcd,CAAC"}
+{"version":3,"file":"blaze.d.ts","sourceRoot":"","sources":["../src/blaze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EACV,KAAK,EACL,kBAAkB,EAClB,IAAI,EACJ,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAQpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,GACpD,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAChB;QACE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACvC,GACD,SAAS,CAAC;IACd,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACnD,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAMD;;GAEG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,iBAAiB,EAAE,EAC1B,MAAM;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KACxD,MAmEF,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,KAAK,GAChB,KAAK,IAAI,EACT,UAAS,eAAoB,KAC5B,OAAO,CAAC,IAAI,CA0Bd,CAAC"}

package/dist/blaze.js

@@ -10,6 +10,7 @@
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { validateTopo } from '@ontrails/core';
 import { buildMcpTools } from './build.js';
 import { connectStdio } from './stdio.js';
 // ---------------------------------------------------------------------------
@@ -81,13 +82,23 @@ export const createMcpServer = (tools, info) => {
  * Build MCP tools from an App, create a server, and connect via stdio.
  */
 export const blaze = async (app, options = {}) => {
-    const tools = buildMcpTools(app, {
+    if (options.validate !== false) {
+        const validated = validateTopo(app);
+        if (validated.isErr()) {
+            throw validated.error;
+        }
+    }
+    const toolsResult = buildMcpTools(app, {
         createContext: options.createContext,
         excludeTrails: options.excludeTrails,
         includeTrails: options.includeTrails,
         layers: options.layers,
+        services: options.services,
     });
-    const server = createMcpServer(tools, {
+    if (toolsResult.isErr()) {
+        throw toolsResult.error;
+    }
+    const server = createMcpServer(toolsResult.value, {
         name: options.serverInfo?.name ?? app.name,
         version: options.serverInfo?.version ?? '0.1.0',
     });

package/dist/blaze.js.map

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

package/dist/build.d.ts

@@ -5,13 +5,15 @@
  * validate input, compose layers, execute the implementation, and map
  * Results to MCP responses.
  */
-import type { Layer, Topo, TrailContext } from '@ontrails/core';
+import { Result } from '@ontrails/core';
+import type { Layer, ServiceOverrideMap, Topo, TrailContextInit } from '@ontrails/core';
 import type { McpAnnotations } from './annotations.js';
 export interface BuildMcpToolsOptions {
-    readonly createContext?: (() => TrailContext | Promise<TrailContext>) | undefined;
+    readonly createContext?: (() => 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 {
     readonly annotations: McpAnnotations | undefined;
@@ -19,6 +21,8 @@ export interface McpToolDefinition {
     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;
@@ -36,5 +40,5 @@ export interface McpContent {
     readonly type: 'text' | 'image' | 'resource';
     readonly uri?: string | undefined;
 }
-export declare const buildMcpTools: (app: Topo, options?: BuildMcpToolsOptions) => McpToolDefinition[];
+export declare const buildMcpTools: (app: Topo, options?: BuildMcpToolsOptions) => Result<McpToolDefinition[], Error>;
 //# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAS,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASvD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,GAC5C,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;CAChD;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;CACvB;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,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;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;AA4OD,eAAO,MAAM,aAAa,GACxB,KAAK,IAAI,EACT,UAAS,oBAAyB,KACjC,iBAAiB,EAiBnB,CAAC"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,MAAM,EAKP,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAEV,KAAK,EACL,kBAAkB,EAClB,IAAI,EAEJ,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASvD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,CAAC,EACnB,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,GACpD,SAAS,CAAC;IACd,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;CACpD;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,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;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;AAmQD,eAAO,MAAM,aAAa,GACxB,KAAK,IAAI,EACT,UAAS,oBAAyB,KACjC,MAAM,CAAC,iBAAiB,EAAE,EAAE,KAAK,CAoBnC,CAAC"}

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,19 @@ 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,
+        services: options.services,
+        signal: extra.signal,
+    });
+    if (result.isOk()) {
+        return { content: await serializeOutput(result.value) };
+    }
+    return mcpError(result.error.message);
 };
 // ---------------------------------------------------------------------------
 // Builder
@@ -131,12 +137,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 +177,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