@ontrails/mcp 1.0.0-beta.23 → 1.0.0-beta.29

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @ontrails/mcp
 
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- Updated dependencies [1307568]
+- Updated dependencies [371d19e]
+  - @ontrails/core@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- a9fdbc7: Clarify surface accommodation doctrine in MCP surface facet metadata and Warden trail-fork coaching guidance.
+- 2c08afe: Expose MCP trail graph fact resources and enable them for the Trails operator MCP surface.
+- f1e6efa: Document the Wayfinder MCP resource surface and polish Wayfinder filter dogfood coverage for unified navigation.
+- df13faf: Tighten Wayfinder navigation review findings: carry adapter filters into included adapter facts, keep live-source outline off the operator MCP surface until host-root binding exists, make unknown MCP resources protocol errors, route secondary Wayfinder graph populations through unified flags, and keep undeclared string `ctx.compose()` calls as Warden errors.
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+  - @ontrails/core@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.24
+
 ## 1.0.0-beta.23
 
 ### Patch Changes

package/README.md

@@ -86,6 +86,7 @@ Cold context is projected through MCP resources, not extra Trails resources. `su
 
 - `trails://surface-map` lists the resolved MCP tool projection, including ordinary tools, facet 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 projection only when the host needs a minimal MCP capability surface:
 
@@ -97,10 +98,12 @@ Or choose a narrower resource set:
 
 ```typescript
 await surface(graph, {
-  mcpResources: { examples: false, surfaceMap: true },
+  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.
+
 Facet 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

package/package.json

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

package/src/build.ts

@@ -73,6 +73,10 @@ export const MCP_TOOL_ERROR_META_KEY = 'ontrails/error';
 /**
  * Metadata key used to identify MCP tools derived from surface facets.
  *
+ * Surface facets preserve member trail identity rather than merging member
+ * contracts. The metadata names the facet and its member trail IDs so clients
+ * can inspect the grouped entry before choosing a selected trail.
+ *
  * @example
  * ```ts
  * import { MCP_TOOL_FACET_META_KEY } from '@ontrails/mcp';
@@ -111,6 +115,7 @@ export interface DeriveMcpToolsOptions extends BaseSurfaceOptions {
 
 export type McpSurfaceFacetTrailSelector = string | readonly string[];
 
+/** Surface-side grouped entry over existing trails. */
 export interface McpSurfaceFacetDefinition {
   readonly trails: McpSurfaceFacetTrailSelector;
   readonly description: string;

package/src/index.ts

@@ -22,6 +22,7 @@ export {
 export {
   MCP_EXAMPLES_RESOURCE_PREFIX,
   MCP_SURFACE_MAP_RESOURCE_URI,
+  MCP_TRAIL_RESOURCE_PREFIX,
   buildMcpResources,
   isMcpFacetTool,
   type BuiltMcpResources,

package/src/resources.ts

@@ -35,6 +35,18 @@ export const MCP_SURFACE_MAP_RESOURCE_URI = 'trails://surface-map';
  */
 export const MCP_EXAMPLES_RESOURCE_PREFIX = 'trails://examples/';
 
+/**
+ * Prefix used for trail graph fact resources exposed through MCP.
+ *
+ * @example
+ * ```ts
+ * import { MCP_TRAIL_RESOURCE_PREFIX } from '@ontrails/mcp';
+ *
+ * const uri = `${MCP_TRAIL_RESOURCE_PREFIX}${encodeURIComponent('tasks.create')}`;
+ * ```
+ */
+export const MCP_TRAIL_RESOURCE_PREFIX = 'trails://trail/';
+
 export interface McpResourceDefinition {
   readonly uri: string;
   readonly mimeType: string;
@@ -51,6 +63,7 @@ export interface McpResourceContent {
 export interface McpResourcesConfig {
   readonly surfaceMap?: boolean | undefined;
   readonly examples?: boolean | undefined;
+  readonly graph?: boolean | undefined;
 }
 
 export interface BuiltMcpResources {
@@ -76,6 +89,21 @@ interface McpSurfaceMap {
   readonly tools: readonly McpSurfaceMapTool[];
 }
 
+interface McpTrailResource {
+  readonly trailId: string;
+  readonly description?: string | undefined;
+  readonly intent: Trail<unknown, unknown, unknown>['intent'];
+  readonly visibility: Trail<unknown, unknown, unknown>['visibility'];
+  readonly composes: readonly string[];
+  readonly resources: readonly string[];
+  readonly signals: {
+    readonly fires: readonly string[];
+    readonly on: readonly string[];
+  };
+  readonly surface: 'mcp';
+  readonly tools: readonly McpSurfaceMapTool[];
+}
+
 const asJson = (value: unknown): string =>
   `${JSON.stringify(value, null, 2)}\n`;
 
@@ -118,6 +146,9 @@ const exposedTrailIds = (
 const examplesUriForTrail = (trailId: string): string =>
   `${MCP_EXAMPLES_RESOURCE_PREFIX}${encodeURIComponent(trailId)}`;
 
+const trailUriForTrail = (trailId: string): string =>
+  `${MCP_TRAIL_RESOURCE_PREFIX}${encodeURIComponent(trailId)}`;
+
 const buildExampleResource = (
   trailItem: Trail<unknown, unknown, unknown>
 ):
@@ -167,6 +198,76 @@ const buildExampleResources = (
     .filter((resource) => resource !== undefined);
 };
 
+const resourceId = (
+  resource: Trail<unknown, unknown, unknown>['resources'][number]
+) => resource.id;
+
+const buildTrailGraphResource = (
+  trailItem: Trail<unknown, unknown, unknown>,
+  tools: readonly McpToolDefinition[]
+): {
+  readonly content: McpResourceContent;
+  readonly listing: McpResourceDefinition;
+} => {
+  const uri = trailUriForTrail(trailItem.id);
+  const surfaceTools = tools
+    .filter(
+      (tool) =>
+        tool.trailId === trailItem.id ||
+        tool.memberTrailIds?.includes(trailItem.id) === true
+    )
+    .map(projectSurfaceMapTool);
+  const payload: McpTrailResource = {
+    composes: trailItem.composes,
+    ...(trailItem.description === undefined
+      ? {}
+      : { description: trailItem.description }),
+    intent: trailItem.intent,
+    resources: trailItem.resources.map(resourceId),
+    signals: {
+      fires: trailItem.fires,
+      on: trailItem.on,
+    },
+    surface: 'mcp',
+    tools: surfaceTools,
+    trailId: trailItem.id,
+    visibility: trailItem.visibility,
+  };
+
+  return {
+    content: {
+      mimeType: 'application/json',
+      text: asJson(payload),
+      uri,
+    },
+    listing: {
+      description: `MCP-visible graph facts for trail "${trailItem.id}".`,
+      mimeType: 'application/json',
+      name: `Trail graph fact: ${trailItem.id}`,
+      uri,
+    },
+  };
+};
+
+const buildTrailGraphResources = (
+  graph: Topo,
+  tools: readonly McpToolDefinition[]
+): readonly {
+  readonly content: McpResourceContent;
+  readonly listing: McpResourceDefinition;
+}[] => {
+  const visibleTrailIds = exposedTrailIds(tools);
+  return graph
+    .list()
+    .filter((trailItem) => visibleTrailIds.has(trailItem.id))
+    .map((trailItem) =>
+      buildTrailGraphResource(
+        trailItem as Trail<unknown, unknown, unknown>,
+        tools
+      )
+    );
+};
+
 /**
  * Build the cold-context MCP resources for a Trails graph and tool set.
  *
@@ -208,6 +309,13 @@ export const buildMcpResources = (
     }
   }
 
+  if (config.graph === true) {
+    for (const resource of buildTrailGraphResources(graph, tools)) {
+      listings.push(resource.listing);
+      contents.set(resource.content.uri, resource.content);
+    }
+  }
+
   return {
     list: listings,
     read: (uri) => contents.get(uri),

package/src/surface.ts

@@ -5,8 +5,10 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import {
   CallToolRequestSchema,
+  ErrorCode,
   ListResourcesRequestSchema,
   ListToolsRequestSchema,
+  McpError,
   ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import type {
@@ -176,14 +178,14 @@ const createMcpServer = (
 
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
       const content = mcpResources.read(request.params.uri);
+      if (content === undefined) {
+        throw new McpError(
+          ErrorCode.InvalidParams,
+          `Resource ${request.params.uri} not found`
+        );
+      }
       return {
-        contents: [
-          content ?? {
-            mimeType: 'text/plain',
-            text: `Unknown MCP resource: ${request.params.uri}`,
-            uri: request.params.uri,
-          },
-        ],
+        contents: [content],
       };
     });
   }