@ontrails/mcp 0.2.0

package/README.md

@@ -0,0 +1,148 @@
+# @ontrails/mcp
+
+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 { 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',
+  examples: [
+    {
+      expected: { greeting: 'Hello, Ada!' },
+      input: { name: 'Ada' },
+      name: 'Ada',
+    },
+  ],
+  implementation: (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`, JSON Schema input, JSON Schema output, and structured examples -- all derived from the trail definition.
+
+For more control, build the tools yourself:
+
+```typescript
+import { deriveMcpTools } from '@ontrails/mcp';
+
+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,
+  });
+}
+```
+
+`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 |
+| --- | --- |
+| `surface(graph, options?)` | Start an MCP server with all trails as tools |
+| `deriveMcpTools(graph, options?)` | Build tool definitions without starting a server |
+| `buildMcpResources(graph, tools, config?)` | Build MCP resource listings and read handlers for cold context |
+| `deriveToolName(appName, trailId)` | Compute the MCP tool name from app and trail IDs |
+| `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, idempotency, and description map directly to MCP annotations:
+
+| Trail field | MCP annotation |
+| --- | --- |
+| `intent: 'read'` | `readOnlyHint: true` |
+| `intent: 'destroy'` | `destructiveHint: true` |
+| `idempotent: true` | `idempotentHint: true` |
+| `description` | `title` |
+
+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 render 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 rendered as structured metadata under `_meta["ontrails/examples"]`. Each rendered example preserves its input, expected output or error, a success/error kind, and provenance pointing back to the authored `trail.examples` field.
+
+## MCP resources and deferred loading
+
+Cold context is rendered through MCP resources, not extra Trails resources. `surface(graph)` and `createServer(graph)` expose MCP resources by default:
+
+- `trails://surface-map` lists the resolved MCP tool rendering, including ordinary tools, trailhead tools, schemas, versions, deferred hints, and member trail IDs.
+- `trails://examples/<trailId>` exposes structured examples for exposed trails that define examples.
+- `trails://trail/<trailId>` exposes MCP-visible graph facts for an exposed trail when graph resources are enabled.
+
+Disable resource rendering only when the host needs a minimal MCP capability surface:
+
+```typescript
+await surface(graph, { mcpResources: false });
+```
+
+Or choose a narrower resource set:
+
+```typescript
+await surface(graph, {
+  mcpResources: { examples: false, graph: true, surfaceMap: true },
+});
+```
+
+Graph resources are opt-in for general MCP hosts because they widen cold context for every exposed trail. The Trails operator enables them so agents can inspect high-signal graph facts without invoking another tool.
+
+Trailhead definitions may set `mcp: { loading: 'deferred' }`. In this release, deferred loading is a compatibility hint under `_meta["ontrails/deferred"]`; the MCP tool schema remains present so clients that do not understand deferred loading continue to work.
+
+## 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.
+
+## Resource resolution
+
+Declared resources on each trail are resolved into the context before the implementation receives input.
+
+## 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) => {
+    for (let i = 0; i < items.length; i++) {
+      await processItem(items[i]);
+      ctx.progress?.({ type: 'progress', current: i + 1, total: items.length });
+    }
+    return Result.ok({ imported: items.length });
+  },
+});
+```
+
+## Filtering
+
+```typescript
+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
+
+These commands target stable `0.2.0`. Run them after that version is published to npm.
+
+```bash
+bun add --exact @ontrails/mcp@0.2.0
+```

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ontrails/mcp",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "packages/mcp"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "zod": "^4.3.5"
+  }
+}

package/src/annotations.ts

@@ -0,0 +1,74 @@
+/**
+ * Derive MCP tool annotations from trail spec fields.
+ */
+
+import type { Intent, Trail } from '@ontrails/core';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface McpAnnotations {
+  readonly readOnlyHint?: boolean | undefined;
+  readonly destructiveHint?: boolean | undefined;
+  readonly idempotentHint?: boolean | undefined;
+  readonly openWorldHint?: boolean | undefined;
+  readonly title?: string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Map trail spec fields to MCP tool annotations.
+ *
+ * Only sets hints that are explicitly declared on the trail.
+ * Omitted hints let the MCP SDK use its defaults.
+ *
+ * @example
+ * ```ts
+ * import { deriveAnnotations } from '@ontrails/mcp';
+ *
+ * const annotations = deriveAnnotations({
+ *   intent: 'read',
+ *   idempotent: true,
+ *   description: 'Show account',
+ * });
+ *
+ * // read intent -> readOnlyHint, idempotent -> idempotentHint, description -> title.
+ * annotations.readOnlyHint === true;
+ * annotations.idempotentHint === true;
+ * annotations.title === 'Show account';
+ *
+ * // destroy intent -> destructiveHint.
+ * const destroyAnnotations = deriveAnnotations({ intent: 'destroy' });
+ * destroyAnnotations.destructiveHint === true;
+ * ```
+ */
+export const deriveAnnotations = (
+  trail: Pick<
+    Trail<unknown, unknown, unknown>,
+    'intent' | 'idempotent' | 'description'
+  >
+): McpAnnotations => {
+  const annotations: Record<string, unknown> = {};
+
+  const intentToHint: Partial<Record<Intent, string>> = {
+    destroy: 'destructiveHint',
+    read: 'readOnlyHint',
+  };
+
+  const hint = intentToHint[trail.intent];
+  if (hint) {
+    annotations[hint] = true;
+  }
+  if (trail.idempotent === true) {
+    annotations['idempotentHint'] = true;
+  }
+  if (trail.description !== undefined) {
+    annotations['title'] = trail.description;
+  }
+
+  return annotations as McpAnnotations;
+};