@ontrails/mcp 1.0.0-beta.18 → 1.0.0-beta.19

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @ontrails/mcp
 
+## 1.0.0-beta.19
+
+### Patch Changes
+
+- e41c382: Document beta-channel install guidance in package and adapter README install snippets so consumers use explicit `@beta` (or pinned `1.0.0-beta.N`) tags instead of accidental `latest` resolution during the prerelease line. Adds the policy doc at `docs/releases/beta-channel-policy.md`, prints both `latest` and `beta` dist-tags in `bun run publish:registry-check`, and aligns plugin/skill install snippets.
+- 1eb5bdc: Rename first-class trail composition from the `cross` API family to the `compose` family across core contracts, testing helpers, topo projections, Warden rules, CLI scaffolds, and docs. `composes`, `ctx.compose`, `composeInput`, and `Compose*` type names are now the public authoring vocabulary; topo persistence migrates legacy composition rows and graph keys forward.
+- 8638dae: Add a public API example for MCP `deriveAnnotations` annotation derivation.
+- 8638dae: Add public API examples for the MCP tool metadata keys.
+- 8638dae: Add a public API example for the MCP progress callback bridge.
+- 84f56a5: Project live trail-version metadata on CLI, HTTP, and MCP surfaces and thread explicit surface version selection into shared trail execution.
+- 5d88104: Polish Trails blaze terminology across package docs and Warden guidance.
+- Updated dependencies [e41c382]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [846a597]
+- Updated dependencies [223aaad]
+- Updated dependencies [3125f4d]
+- Updated dependencies [2494dc6]
+- Updated dependencies [2d53717]
+- Updated dependencies [16cb740]
+- Updated dependencies [8894ecb]
+- Updated dependencies [fdf7ec9]
+- Updated dependencies [d76be13]
+- Updated dependencies [84f56a5]
+- Updated dependencies [431b04c]
+- Updated dependencies [5d88104]
+- Updated dependencies [f04a9ef]
+  - @ontrails/core@1.0.0-beta.19
+
 ## 1.0.0-beta.18
 
 ### Patch Changes

package/README.md

@@ -85,11 +85,11 @@ Trail IDs become MCP tool names with the app prefix: `entity.show` in app `myapp
 
 ## Resource resolution
 
-Declared resources on each trail are resolved into the context before the implementation runs.
+Declared resources on each trail are resolved into the context before the blaze receives input.
 
 ## Progress bridge
 
-Implementations report progress through `ctx.progress`. On MCP, these bridge to `notifications/progress` when the client sends a `progressToken`:
+Blazes report progress through `ctx.progress`. On MCP, these bridge to `notifications/progress` when the client sends a `progressToken`:
 
 ```typescript
 const importTrail = trail('data.import', {
@@ -110,11 +110,10 @@ 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.
+`*` matches one dotted segment and `**` matches any depth. Trails declared with `visibility: 'internal'` stay hidden unless you include their exact trail ID.
 
 ## Installation
 
 ```bash
-bun add @ontrails/mcp
+bun add @ontrails/mcp@beta
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/mcp",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,7 +22,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.17"
+    "@ontrails/core": "^1.0.0-beta.19"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",

package/src/annotations.ts

@@ -25,6 +25,26 @@ export interface McpAnnotations {
  *
  * 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<

package/src/build.ts

@@ -11,6 +11,7 @@ import {
   Result,
   ValidationError,
   collectAttachedTypedLayers,
+  deriveSurfaceTrailVersionProjections,
   deriveStructuredTrailExamples,
   executeTrail,
   filterSurfaceTrails,
@@ -32,9 +33,11 @@ import type {
   Layer,
   ResourceOverrideMap,
   SurfaceErrorProjection,
+  SurfaceTrailVersionProjection,
   Topo,
   Trail,
   TrailContextInit,
+  TrailVersionReference,
 } from '@ontrails/core';
 
 import type { McpAnnotations } from './annotations.js';
@@ -42,8 +45,28 @@ import { deriveAnnotations } from './annotations.js';
 import { createMcpProgressCallback } from './progress.js';
 import { deriveToolName } from './tool-name.js';
 
+/**
+ * Metadata key used for structured trail examples on derived MCP tools.
+ *
+ * @example
+ * ```ts
+ * import { MCP_TOOL_EXAMPLES_META_KEY } from '@ontrails/mcp';
+ *
+ * const examples = tool._meta?.[MCP_TOOL_EXAMPLES_META_KEY];
+ * ```
+ */
 export const MCP_TOOL_EXAMPLES_META_KEY = 'ontrails/examples';
 
+/**
+ * Metadata key used for public Trails error projections on MCP tool errors.
+ *
+ * @example
+ * ```ts
+ * import { MCP_TOOL_ERROR_META_KEY } from '@ontrails/mcp';
+ *
+ * const error = result._meta?.[MCP_TOOL_ERROR_META_KEY];
+ * ```
+ */
 export const MCP_TOOL_ERROR_META_KEY = 'ontrails/error';
 
 // ---------------------------------------------------------------------------
@@ -84,6 +107,7 @@ export interface McpToolDefinition {
   readonly outputSchema?: Record<string, unknown> | undefined;
   /** The trail ID this tool was derived from. */
   readonly trailId: string;
+  readonly versions?: readonly SurfaceTrailVersionProjection[] | undefined;
 }
 
 export interface McpExtra {
@@ -602,6 +626,48 @@ const projectMcpInputSchema = (
   return { projections, schema: mergedSchema };
 };
 
+const TRAIL_VERSION_PARAM = 'trailVersion';
+
+const addMcpVersionInputSchema = (
+  trail: Trail<unknown, unknown, unknown>,
+  schema: Record<string, unknown>
+): Record<string, unknown> => {
+  if (trail.version === undefined) {
+    return schema;
+  }
+  const properties =
+    isJsonObjectSchema(schema) && schema.properties !== undefined
+      ? schema.properties
+      : undefined;
+  return {
+    ...schema,
+    properties: {
+      ...properties,
+      [TRAIL_VERSION_PARAM]: {
+        description: 'Live trail version number or marker prefix',
+        type: 'string',
+      },
+    },
+    type: 'object',
+  };
+};
+
+const splitMcpSurfaceVersion = (
+  args: Record<string, unknown>
+): {
+  readonly args: Record<string, unknown>;
+  readonly version: TrailVersionReference | undefined;
+} => {
+  const { [TRAIL_VERSION_PARAM]: rawVersion, ...rest } = args;
+  return {
+    args: rest,
+    version:
+      typeof rawVersion === 'string' || typeof rawVersion === 'number'
+        ? rawVersion
+        : undefined,
+  };
+};
+
 /**
  * Partition a parsed MCP `args` record into the trail input plus per-layer
  * inputs, using each layer's routing table.
@@ -750,8 +816,12 @@ const createHandler =
   ) => Promise<McpToolResult>) =>
   async (args, extra): Promise<McpToolResult> => {
     const progressCb = createMcpProgressCallback(extra);
+    const versionedArgs =
+      t.version === undefined
+        ? { args, version: undefined }
+        : splitMcpSurfaceVersion(args);
     const { trailInput, layerInputs } = partitionMcpArgs(
-      args,
+      versionedArgs.args,
       layerProjections
     );
     const permitResolution = await resolveMcpPermit(options, extra);
@@ -770,6 +840,9 @@ const createHandler =
       surfaceLayers: layers,
       topo: graph,
       topoLayers: graph.layers,
+      ...(versionedArgs.version === undefined
+        ? {}
+        : { version: versionedArgs.version }),
     });
     if (result.isOk()) {
       return {
@@ -867,6 +940,8 @@ const buildToolDefinition = (
     options.layers
   );
   const inputProjection = projectMcpInputSchema(trail, attachedLayers);
+  const inputSchema = addMcpVersionInputSchema(trail, inputProjection.schema);
+  const versions = deriveSurfaceTrailVersionProjections(trail);
   return {
     _meta: buildMeta(trail),
     annotations,
@@ -879,10 +954,11 @@ const buildToolDefinition = (
       projection?.wrapAsData ?? false,
       inputProjection.projections
     ),
-    inputSchema: inputProjection.schema,
+    inputSchema,
     name: deriveToolName(graph.name, trail.id),
     outputSchema: projection?.schema,
     trailId: trail.id,
+    ...(versions === undefined ? {} : { versions }),
   };
 };
 

package/src/progress.ts

@@ -54,6 +54,28 @@ const progressHandlers: Record<
  *
  * Returns `undefined` if the MCP client did not provide a progressToken
  * (meaning no progress reporting was requested).
+ *
+ * @example
+ * ```ts
+ * import { createMcpProgressCallback, type McpExtra } from '@ontrails/mcp';
+ *
+ * const extra: McpExtra = {
+ *   progressToken: 'token-123',
+ *   sendProgress: async (current, total) => {
+ *     console.log(`progress ${current}/${total}`);
+ *   },
+ * };
+ *
+ * const progress = createMcpProgressCallback(extra);
+ * if (progress !== undefined) {
+ *   progress({
+ *     current: 0,
+ *     ts: new Date().toISOString(),
+ *     total: 1,
+ *     type: 'start',
+ *   });
+ * }
+ * ```
  */
 export const createMcpProgressCallback = (
   extra: McpExtra