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

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @ontrails/mcp
 
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- 61497c5: Add v1-minimum public API examples for shipped surface entrypoints.
+- Updated dependencies [3dc8254]
+  - @ontrails/core@1.0.0-beta.17
+
+## 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

package/README.md

@@ -1,6 +1,6 @@
 # @ontrails/mcp
 
-MCP surface connector. One `surface()` 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
 
@@ -11,15 +11,23 @@ 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 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:
 
@@ -31,7 +39,9 @@ if (result.isErr()) throw result.error; // ValidationError on tool-name collisio
 for (const tool of result.value) {
   server.registerTool(tool.name, tool.handler, {
     inputSchema: tool.inputSchema,
+    outputSchema: tool.outputSchema,
     annotations: tool.annotations,
+    _meta: tool._meta,
   });
 }
 ```
@@ -63,6 +73,12 @@ Trail intent, idempotency, and description 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.

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@ontrails/mcp",
-  "version": "1.0.0-beta.15",
+  "version": "1.0.0-beta.17",
+  "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.14"
+    "@ontrails/core": "^1.0.0-beta.16"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.28.0",
     "zod": "^4.3.5"
   }
 }