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

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @ontrails/mcp
 
+## 1.0.0-beta.16
+
+### Minor Changes
+
+- 26f9ffd: Project typed-layer `input` schemas onto MCP and HTTP surfaces. Closes Phase 7. Lifts `collectAttachedTypedLayers` and `projectLayerFieldName` (collision-rename rule) into `@ontrails/core/internal/layer-projection` so all three surfaces share one source of truth. The CLI surface refactors to consume the lifted helpers (no behavior change). MCP merges layer fields into each tool's `inputSchema` and partitions inbound args at invocation time. HTTP merges layer fields into the route's request schema (query for reads, body for writes) and exposes new optional `HttpRouteDefinition.inputSchema` + `layerInputProjections` for surface adapters / OpenAPI generators. Collision rule matches TRL-473's: deterministic rename to a layer-prefixed camelCase name with the original captured in the routing table. Side fix: MCP and HTTP handlers now forward `topoLayers: graph.layers` + `surfaceLayers: layers` so topo-scope layers actually compose at runtime (previously the handlers used the deprecated `layers` alias and never read `graph.layers`).
+
+### Patch Changes
+
+- 6300f70: Refresh source comments and test labels for retired connector terminology as adapter guardrails become strict.
+- 20d7a5c: Enforce the shared safe error projection policy for public error bodies, diagnostics, serialized payloads, and CLI stderr.
+- 49c2e7d: Refresh published package README taxonomy to use adapter language instead of retired connector vocabulary.
+- Updated dependencies [73622ae]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [e898cc4]
+- Updated dependencies [3395234]
+- Updated dependencies [bcdc484]
+- Updated dependencies [331e3a9]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [10eae9a]
+- Updated dependencies [22c6c06]
+  - @ontrails/core@1.0.0-beta.16
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+
 ## 1.0.0-beta.14
 
 ### Minor Changes

package/README.md

@@ -1,58 +1,68 @@
 # @ontrails/mcp
 
-MCP trailhead connector. One `trailhead()` call turns a topo into an MCP server with tool definitions, annotations, and progress bridging -- all derived from the trail contracts.
+MCP surface adapter. One `surface()` call turns a topo into an MCP server with tool definitions, annotations, and progress bridging -- all derived from the trail contracts.
 
 ## Usage
 
 ```typescript
 import { trail, topo, Result } from '@ontrails/core';
-import { trailhead } from '@ontrails/mcp';
+import { surface } from '@ontrails/mcp';
 import { z } from 'zod';
 
 const greet = trail('greet', {
   input: z.object({ name: z.string().describe('Who to greet') }),
+  output: z.object({ greeting: z.string() }),
   intent: 'read',
-  blaze: (input) => Result.ok(`Hello, ${input.name}!`),
+  examples: [
+    {
+      expected: { greeting: 'Hello, Ada!' },
+      input: { name: 'Ada' },
+      name: 'Ada',
+    },
+  ],
+  blaze: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
 });
 
-const app = topo('myapp', { greet });
-await trailhead(app);
+const graph = topo('myapp', { greet });
+await surface(graph);
 ```
 
-This starts an MCP server over stdio with a `myapp_greet` tool. The tool gets `readOnlyHint: true` and a JSON Schema input -- both derived from the trail definition.
+This starts an MCP server over stdio with a `myapp_greet` tool. The tool gets `readOnlyHint: true`, JSON Schema input, JSON Schema output, and structured examples -- all derived from the trail definition.
 
 For more control, build the tools yourself:
 
 ```typescript
-import { buildMcpTools } from '@ontrails/mcp';
+import { deriveMcpTools } from '@ontrails/mcp';
 
-const result = buildMcpTools(app);
+const result = deriveMcpTools(graph);
 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,
+    outputSchema: tool.outputSchema,
     annotations: tool.annotations,
+    _meta: tool._meta,
   });
 }
 ```
 
-`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.
+`deriveMcpTools` 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 |
 | --- | --- |
-| `trailhead(app, options?)` | Start an MCP server with all trails as tools |
-| `buildMcpTools(app, options?)` | Build tool definitions without starting a server |
+| `surface(graph, options?)` | Start an MCP server with all trails as tools |
+| `deriveMcpTools(graph, 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 intent and metadata |
+| `deriveAnnotations(trail)` | Extract MCP annotations from trail intent, idempotency, and description |
 | `createMcpProgressCallback(server)` | Bridge `ctx.progress` to MCP `notifications/progress` |
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
 ## Annotations
 
-Trail intent and metadata map directly to MCP annotations:
+Trail intent, idempotency, and description map directly to MCP annotations:
 
 | Trail field | MCP annotation |
 | --- | --- |
@@ -63,13 +73,19 @@ Trail intent and metadata map directly to MCP annotations:
 
 No manual annotation definitions. The contract is the source of truth.
 
+## Schemas and Examples
+
+MCP tool definitions include the trail's input schema, and trails with an `output` schema also project that schema into MCP `outputSchema`. Non-object trail outputs are wrapped in a `{ data: ... }` object because MCP structured tool results are object-shaped.
+
+Trail examples are projected as structured metadata under `_meta["ontrails/examples"]`. Each projected example preserves its input, expected output or error, a success/error kind, and provenance pointing back to the authored `trail.examples` field.
+
 ## Tool naming
 
 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.
 
-## Provision resolution
+## Resource resolution
 
-Declared provisions on each trail are resolved into the context before the implementation runs.
+Declared resources on each trail are resolved into the context before the implementation runs.
 
 ## Progress bridge
 
@@ -90,10 +106,13 @@ const importTrail = trail('data.import', {
 ## Filtering
 
 ```typescript
-await trailhead(app, { includeTrails: ['entity.show', 'search'] });
-await trailhead(app, { excludeTrails: ['internal.debug'] });
+await surface(graph, { include: ['entity.**', 'search'] });
+await surface(graph, { exclude: ['internal.debug'] });
 ```
 
+`*` matches one dotted segment and `**` matches any depth. Trails declared with
+`visibility: 'internal'` stay hidden unless you include their exact trail ID.
+
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@ontrails/mcp",
-  "version": "1.0.0-beta.14",
+  "version": "1.0.0-beta.16",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,10 +22,10 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.13"
+    "@ontrails/core": "^1.0.0-beta.15"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.28.0",
     "zod": "^4.3.5"
   }
 }

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> = {};