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

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @ontrails/mcp
 
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- Updated dependencies [99523f2]
+  - @ontrails/core@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Minor Changes
+
+- accb9ec: Add MCP surface facets, MCP resource projection for cold context, and deferred-loading metadata hints.
+
+### Patch Changes
+
+- 9bec01c: Document MCP resource projection and deferred-loading options for cold surface context.
+- Updated dependencies [851a2a3]
+  - @ontrails/core@1.0.0-beta.20
+
 ## 1.0.0-beta.19
 
 ### Patch Changes

package/README.md

@@ -54,6 +54,7 @@ for (const tool of result.value) {
 | --- | --- |
 | `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` |
@@ -79,6 +80,29 @@ MCP tool definitions include the trail's input schema, and trails with an `outpu
 
 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.
 
+## MCP resources and deferred loading
+
+Cold context is projected 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 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.
+
+Disable resource projection 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, surfaceMap: true },
+});
+```
+
+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
 
 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,6 @@
 {
   "name": "@ontrails/mcp",
-  "version": "1.0.0-beta.19",
+  "version": "1.0.0-beta.21",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,7 +22,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.19"
+    "@ontrails/core": "^1.0.0-beta.21"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",

package/src/build.ts

@@ -18,6 +18,7 @@ import {
   isBlobRef,
   isTrailsError,
   LAYER_FIELD_RESERVED_NAMES,
+  matchesTrailPattern,
   projectLayerFieldName,
   projectPublicSurfaceError,
   toBlobRefDescriptor,
@@ -69,6 +70,31 @@ export const MCP_TOOL_EXAMPLES_META_KEY = 'ontrails/examples';
  */
 export const MCP_TOOL_ERROR_META_KEY = 'ontrails/error';
 
+/**
+ * Metadata key used to identify MCP tools derived from surface facets.
+ *
+ * @example
+ * ```ts
+ * import { MCP_TOOL_FACET_META_KEY } from '@ontrails/mcp';
+ *
+ * const facet = tool._meta?.[MCP_TOOL_FACET_META_KEY];
+ * ```
+ */
+export const MCP_TOOL_FACET_META_KEY = 'ontrails/facet';
+
+/**
+ * Metadata key used as a compatibility hint for clients that support
+ * deferred MCP tool loading.
+ *
+ * @example
+ * ```ts
+ * import { MCP_TOOL_DEFERRED_META_KEY } from '@ontrails/mcp';
+ *
+ * const isDeferred = tool._meta?.[MCP_TOOL_DEFERRED_META_KEY] === true;
+ * ```
+ */
+export const MCP_TOOL_DEFERRED_META_KEY = 'ontrails/deferred';
+
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
@@ -77,11 +103,31 @@ export interface DeriveMcpToolsOptions extends BaseSurfaceOptions {
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
+  readonly facets?: McpSurfaceFacetMap | undefined;
   readonly layers?: readonly Layer[] | undefined;
   readonly resources?: ResourceOverrideMap | undefined;
   readonly resolvePermit?: ResolveMcpPermit | undefined;
 }
 
+export type McpSurfaceFacetTrailSelector = string | readonly string[];
+
+export interface McpSurfaceFacetDefinition {
+  readonly trails: McpSurfaceFacetTrailSelector;
+  readonly description: string;
+  readonly visibility?: 'public' | 'internal' | undefined;
+  readonly descriptionStableThrough?: string | undefined;
+  readonly visibilityWideningAccepted?: true | undefined;
+  readonly mcp?:
+    | {
+        readonly loading?: 'deferred' | undefined;
+      }
+    | undefined;
+}
+
+export type McpSurfaceFacetMap = Readonly<
+  Record<string, McpSurfaceFacetDefinition>
+>;
+
 export interface ResolveMcpPermitInput {
   readonly authorization?: string | undefined;
   readonly bearerToken?: string | undefined;
@@ -98,15 +144,17 @@ export interface McpToolDefinition {
   readonly _meta?: Record<string, unknown> | undefined;
   readonly annotations: McpAnnotations | undefined;
   readonly description: string | undefined;
+  readonly facetId?: string | undefined;
   readonly handler: (
     args: Record<string, unknown>,
     extra: McpExtra
   ) => Promise<McpToolResult>;
   readonly inputSchema: Record<string, unknown>;
+  readonly memberTrailIds?: readonly string[] | undefined;
   readonly name: string;
   readonly outputSchema?: Record<string, unknown> | undefined;
   /** The trail ID this tool was derived from. */
-  readonly trailId: string;
+  readonly trailId?: string | undefined;
   readonly versions?: readonly SurfaceTrailVersionProjection[] | undefined;
 }
 
@@ -923,6 +971,16 @@ const buildMeta = (
   return { [MCP_TOOL_EXAMPLES_META_KEY]: examples };
 };
 
+const mergeMeta = (
+  ...entries: readonly (Record<string, unknown> | undefined)[]
+): Record<string, unknown> | undefined => {
+  const merged = Object.assign(
+    {},
+    ...(entries.filter(Boolean) as Record<string, unknown>[])
+  );
+  return Object.keys(merged).length > 0 ? merged : undefined;
+};
+
 /** Build a single MCP tool definition from a trail. */
 const buildToolDefinition = (
   graph: Topo,
@@ -962,25 +1020,217 @@ const buildToolDefinition = (
   };
 };
 
+const facetSelectors = (
+  selector: McpSurfaceFacetTrailSelector
+): readonly string[] => (typeof selector === 'string' ? [selector] : selector);
+
+const matchesFacetSelector = (
+  trailId: string,
+  selector: McpSurfaceFacetTrailSelector
+): boolean =>
+  facetSelectors(selector).some((pattern) =>
+    matchesTrailPattern(trailId, pattern)
+  );
+
+interface FacetMemberTool {
+  readonly tool: McpToolDefinition;
+  readonly trail: Trail<unknown, unknown, unknown>;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const buildFacetInputSchema = (
+  members: readonly FacetMemberTool[]
+): Record<string, unknown> => ({
+  anyOf: members.map(({ tool, trail }) => ({
+    properties: {
+      input: tool.inputSchema,
+      trail: { const: trail.id },
+    },
+    required: ['trail', 'input'],
+    type: 'object',
+  })),
+  properties: {
+    input: { type: 'object' },
+    trail: {
+      enum: members.map(({ trail }) => trail.id),
+      type: 'string',
+    },
+  },
+  required: ['trail', 'input'],
+  type: 'object',
+});
+
+const buildFacetOutputSchema = (
+  members: readonly FacetMemberTool[]
+): Record<string, unknown> => {
+  const outputSchemas = members.map(({ tool }) => tool.outputSchema ?? {});
+  return {
+    properties: {
+      output:
+        outputSchemas.length === 1
+          ? (outputSchemas[0] ?? {})
+          : { anyOf: outputSchemas },
+      trail: {
+        enum: members.map(({ trail }) => trail.id),
+        type: 'string',
+      },
+    },
+    required: ['trail', 'output'],
+    type: 'object',
+  };
+};
+
+const parseJsonTextContent = (
+  content: readonly McpContent[]
+): unknown | undefined => {
+  const text = content.find((item) => item.type === 'text')?.text;
+  if (text === undefined) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+};
+
+const wrapFacetResult = (
+  trailId: string,
+  result: McpToolResult
+): McpToolResult => {
+  if (result.isError === true) {
+    return result;
+  }
+  const output =
+    result.structuredContent ?? parseJsonTextContent(result.content) ?? null;
+  const envelope = { output, trail: trailId };
+  return {
+    ...(result._meta === undefined ? {} : { _meta: result._meta }),
+    content: [
+      { text: JSON.stringify(envelope), type: 'text' },
+      ...result.content.filter((item) => item.type !== 'text'),
+    ],
+    structuredContent: envelope,
+  };
+};
+
+const createFacetHandler = (
+  facetId: string,
+  members: readonly FacetMemberTool[]
+): McpToolDefinition['handler'] => {
+  const byTrailId = new Map(
+    members.map((member) => [member.trail.id, member.tool])
+  );
+
+  return async (args, extra): Promise<McpToolResult> => {
+    const trailId = typeof args['trail'] === 'string' ? args['trail'] : '';
+    const tool = byTrailId.get(trailId);
+    if (tool === undefined) {
+      return mcpError(
+        new ValidationError(
+          `MCP facet "${facetId}" received unknown trail selector "${trailId || '(missing)'}"`
+        )
+      );
+    }
+
+    const { input } = args;
+    if (!isRecord(input)) {
+      return mcpError(
+        new ValidationError(
+          `MCP facet "${facetId}" expects an object input for trail "${trailId}"`
+        )
+      );
+    }
+
+    return wrapFacetResult(trailId, await tool.handler(input, extra));
+  };
+};
+
+const deriveFacetIntent = (
+  members: readonly FacetMemberTool[]
+): Pick<Trail<unknown, unknown, unknown>, 'intent'>['intent'] => {
+  if (members.every(({ trail }) => trail.intent === 'read')) {
+    return 'read';
+  }
+  if (members.some(({ trail }) => trail.intent === 'destroy')) {
+    return 'destroy';
+  }
+  return 'write';
+};
+
+const deriveFacetAnnotations = (
+  definition: McpSurfaceFacetDefinition,
+  members: readonly FacetMemberTool[]
+): McpAnnotations | undefined => {
+  const annotations = deriveAnnotations({
+    description: definition.description,
+    idempotent: false,
+    intent: deriveFacetIntent(members),
+  } as Pick<
+    Trail<unknown, unknown, unknown>,
+    'description' | 'idempotent' | 'intent'
+  >);
+  return Object.keys(annotations).length > 0 ? annotations : undefined;
+};
+
+const buildFacetMeta = (
+  facetId: string,
+  definition: McpSurfaceFacetDefinition,
+  memberTrailIds: readonly string[]
+): Record<string, unknown> | undefined =>
+  mergeMeta(
+    {
+      [MCP_TOOL_FACET_META_KEY]: {
+        id: facetId,
+        memberTrailIds,
+      },
+    },
+    definition.mcp?.loading === 'deferred'
+      ? { [MCP_TOOL_DEFERRED_META_KEY]: true }
+      : undefined
+  );
+
+const buildFacetToolDefinition = (
+  graph: Topo,
+  facetId: string,
+  definition: McpSurfaceFacetDefinition,
+  members: readonly FacetMemberTool[]
+): McpToolDefinition => {
+  const memberTrailIds = members.map(({ trail }) => trail.id);
+  return {
+    _meta: buildFacetMeta(facetId, definition, memberTrailIds),
+    annotations: deriveFacetAnnotations(definition, members),
+    description: definition.description,
+    facetId,
+    handler: createFacetHandler(facetId, members),
+    inputSchema: buildFacetInputSchema(members),
+    memberTrailIds,
+    name: deriveToolName(graph.name, facetId),
+    outputSchema: buildFacetOutputSchema(members),
+  };
+};
+
 /** Register a trail as an MCP tool, checking for name collisions. */
 const registerTool = (
   graph: Topo,
   trailItem: Trail<unknown, unknown, unknown>,
   layers: readonly Layer[],
   options: DeriveMcpToolsOptions,
-  nameToTrailId: Map<string, string>,
+  nameToSourceId: Map<string, string>,
   tools: McpToolDefinition[]
 ): Result<void, Error> => {
   const toolName = deriveToolName(graph.name, trailItem.id);
-  const existingId = nameToTrailId.get(toolName);
+  const existingId = nameToSourceId.get(toolName);
   if (existingId !== undefined) {
     return Result.err(
       new ValidationError(
-        `MCP tool-name collision: trails "${existingId}" and "${trailItem.id}" both derive the tool name "${toolName}"`
+        `MCP tool-name collision: "${existingId}" and "trail:${trailItem.id}" both derive the tool name "${toolName}"`
       )
     );
   }
-  nameToTrailId.set(toolName, trailItem.id);
+  nameToSourceId.set(toolName, `trail:${trailItem.id}`);
   tools.push(buildToolDefinition(graph, trailItem, layers, options));
   return Result.ok();
 };
@@ -1001,21 +1251,137 @@ const validateToolBuild = (
   options: DeriveMcpToolsOptions
 ): Result<void, Error> => validateSurfaceTopo(graph, options);
 
+const collectFacetMembers = (
+  graph: Topo,
+  definition: McpSurfaceFacetDefinition,
+  availableTrails: readonly Trail<unknown, unknown, unknown>[],
+  layers: readonly Layer[],
+  options: DeriveMcpToolsOptions
+): readonly FacetMemberTool[] =>
+  availableTrails
+    .filter((trailItem) =>
+      matchesFacetSelector(trailItem.id, definition.trails)
+    )
+    .map((trailItem) => ({
+      tool: buildToolDefinition(graph, trailItem, layers, options),
+      trail: trailItem,
+    }));
+
+const registerFacet = (
+  graph: Topo,
+  facetId: string,
+  definition: McpSurfaceFacetDefinition,
+  members: readonly FacetMemberTool[],
+  nameToSourceId: Map<string, string>,
+  tools: McpToolDefinition[]
+): Result<void, Error> => {
+  if (members.length === 0) {
+    return Result.err(
+      new ValidationError(
+        `MCP facet "${facetId}" did not match any surface-eligible trails`
+      )
+    );
+  }
+
+  const toolName = deriveToolName(graph.name, facetId);
+  const existingId = nameToSourceId.get(toolName);
+  if (existingId !== undefined) {
+    return Result.err(
+      new ValidationError(
+        `MCP tool-name collision: "${existingId}" and "facet:${facetId}" both derive the tool name "${toolName}"`
+      )
+    );
+  }
+
+  nameToSourceId.set(toolName, `facet:${facetId}`);
+  tools.push(buildFacetToolDefinition(graph, facetId, definition, members));
+  return Result.ok();
+};
+
+const registerFacets = (
+  graph: Topo,
+  options: DeriveMcpToolsOptions,
+  layers: readonly Layer[],
+  availableTrails: readonly Trail<unknown, unknown, unknown>[],
+  nameToSourceId: Map<string, string>,
+  tools: McpToolDefinition[]
+): Result<ReadonlySet<string>, Error> => {
+  const { facets } = options;
+  const consumedTrailIds = new Set<string>();
+  const ownerByTrailId = new Map<string, string>();
+
+  if (facets === undefined || Object.keys(facets).length === 0) {
+    return Result.ok(consumedTrailIds);
+  }
+
+  for (const [facetId, definition] of Object.entries(facets).toSorted()) {
+    const members = collectFacetMembers(
+      graph,
+      definition,
+      availableTrails,
+      layers,
+      options
+    );
+    for (const { trail: memberTrail } of members) {
+      const previous = ownerByTrailId.get(memberTrail.id);
+      if (previous !== undefined) {
+        return Result.err(
+          new ValidationError(
+            `MCP facet overlap: trail "${memberTrail.id}" is selected by facets "${previous}" and "${facetId}"`
+          )
+        );
+      }
+      ownerByTrailId.set(memberTrail.id, facetId);
+      consumedTrailIds.add(memberTrail.id);
+    }
+
+    const registered = registerFacet(
+      graph,
+      facetId,
+      definition,
+      members,
+      nameToSourceId,
+      tools
+    );
+    if (registered.isErr()) {
+      return registered;
+    }
+  }
+
+  return Result.ok(consumedTrailIds);
+};
+
 const registerTools = (
   graph: Topo,
   options: DeriveMcpToolsOptions,
   layers: readonly Layer[]
 ): Result<McpToolDefinition[], Error> => {
   const tools: McpToolDefinition[] = [];
-  const nameToTrailId = new Map<string, string>();
+  const nameToSourceId = new Map<string, string>();
+  const availableTrails = eligibleTrails(graph, options);
+  const registeredFacets = registerFacets(
+    graph,
+    options,
+    layers,
+    availableTrails,
+    nameToSourceId,
+    tools
+  );
+  if (registeredFacets.isErr()) {
+    return registeredFacets;
+  }
+  const consumedTrailIds = registeredFacets.value;
 
-  for (const trailItem of eligibleTrails(graph, options)) {
+  for (const trailItem of availableTrails) {
+    if (consumedTrailIds.has(trailItem.id)) {
+      continue;
+    }
     const registered = registerTool(
       graph,
       trailItem,
       layers,
       options,
-      nameToTrailId,
+      nameToSourceId,
       tools
     );
     if (registered.isErr()) {

package/src/index.ts

@@ -2,8 +2,13 @@
 export {
   MCP_TOOL_ERROR_META_KEY,
   MCP_TOOL_EXAMPLES_META_KEY,
+  MCP_TOOL_DEFERRED_META_KEY,
+  MCP_TOOL_FACET_META_KEY,
   deriveMcpTools,
   type DeriveMcpToolsOptions,
+  type McpSurfaceFacetDefinition,
+  type McpSurfaceFacetMap,
+  type McpSurfaceFacetTrailSelector,
   type McpToolDefinition,
   type McpToolResult,
   type McpToolErrorMeta,
@@ -13,6 +18,18 @@ export {
   type ResolveMcpPermitInput,
 } from './build.js';
 
+// MCP resources
+export {
+  MCP_EXAMPLES_RESOURCE_PREFIX,
+  MCP_SURFACE_MAP_RESOURCE_URI,
+  buildMcpResources,
+  isMcpFacetTool,
+  type BuiltMcpResources,
+  type McpResourceContent,
+  type McpResourceDefinition,
+  type McpResourcesConfig,
+} from './resources.js';
+
 // Tool naming
 export { deriveToolName } from './tool-name.js';
 

package/src/resources.ts

@@ -0,0 +1,228 @@
+/**
+ * MCP resource projection for cold Trails context.
+ */
+
+import { deriveStructuredTrailExamples } from '@ontrails/core';
+import type { Topo, Trail } from '@ontrails/core';
+
+import {
+  MCP_TOOL_DEFERRED_META_KEY,
+  MCP_TOOL_FACET_META_KEY,
+} from './build.js';
+import type { McpToolDefinition } from './build.js';
+
+/**
+ * Resource URI used for the resolved MCP surface map.
+ *
+ * @example
+ * ```ts
+ * import { MCP_SURFACE_MAP_RESOURCE_URI } from '@ontrails/mcp';
+ *
+ * const surfaceMap = resources.read(MCP_SURFACE_MAP_RESOURCE_URI);
+ * ```
+ */
+export const MCP_SURFACE_MAP_RESOURCE_URI = 'trails://surface-map';
+
+/**
+ * Prefix used for trail example resources exposed through MCP.
+ *
+ * @example
+ * ```ts
+ * import { MCP_EXAMPLES_RESOURCE_PREFIX } from '@ontrails/mcp';
+ *
+ * const uri = `${MCP_EXAMPLES_RESOURCE_PREFIX}${encodeURIComponent('tasks.create')}`;
+ * ```
+ */
+export const MCP_EXAMPLES_RESOURCE_PREFIX = 'trails://examples/';
+
+export interface McpResourceDefinition {
+  readonly uri: string;
+  readonly mimeType: string;
+  readonly name: string;
+  readonly description?: string | undefined;
+}
+
+export interface McpResourceContent {
+  readonly uri: string;
+  readonly mimeType: string;
+  readonly text: string;
+}
+
+export interface McpResourcesConfig {
+  readonly surfaceMap?: boolean | undefined;
+  readonly examples?: boolean | undefined;
+}
+
+export interface BuiltMcpResources {
+  readonly list: readonly McpResourceDefinition[];
+  readonly read: (uri: string) => McpResourceContent | undefined;
+}
+
+interface McpSurfaceMapTool {
+  readonly annotations: McpToolDefinition['annotations'];
+  readonly description: string | undefined;
+  readonly facetId?: string | undefined;
+  readonly inputSchema: Record<string, unknown>;
+  readonly memberTrailIds?: readonly string[] | undefined;
+  readonly name: string;
+  readonly outputSchema?: Record<string, unknown> | undefined;
+  readonly trailId?: string | undefined;
+  readonly versions?: McpToolDefinition['versions'];
+  readonly deferred?: true | undefined;
+}
+
+interface McpSurfaceMap {
+  readonly surface: 'mcp';
+  readonly tools: readonly McpSurfaceMapTool[];
+}
+
+const asJson = (value: unknown): string =>
+  `${JSON.stringify(value, null, 2)}\n`;
+
+const projectSurfaceMapTool = (tool: McpToolDefinition): McpSurfaceMapTool => ({
+  annotations: tool.annotations,
+  description: tool.description,
+  inputSchema: tool.inputSchema,
+  name: tool.name,
+  ...(tool.facetId === undefined ? {} : { facetId: tool.facetId }),
+  ...(tool.memberTrailIds === undefined
+    ? {}
+    : { memberTrailIds: tool.memberTrailIds }),
+  ...(tool.outputSchema === undefined
+    ? {}
+    : { outputSchema: tool.outputSchema }),
+  ...(tool.trailId === undefined ? {} : { trailId: tool.trailId }),
+  ...(tool.versions === undefined ? {} : { versions: tool.versions }),
+  ...(tool._meta?.[MCP_TOOL_DEFERRED_META_KEY] === true
+    ? { deferred: true }
+    : {}),
+});
+
+const buildSurfaceMap = (
+  tools: readonly McpToolDefinition[]
+): McpSurfaceMap => ({
+  surface: 'mcp',
+  tools: tools.map(projectSurfaceMapTool),
+});
+
+const exposedTrailIds = (
+  tools: readonly McpToolDefinition[]
+): ReadonlySet<string> =>
+  new Set(
+    tools.flatMap((tool) => [
+      ...(tool.trailId === undefined ? [] : [tool.trailId]),
+      ...(tool.memberTrailIds ?? []),
+    ])
+  );
+
+const examplesUriForTrail = (trailId: string): string =>
+  `${MCP_EXAMPLES_RESOURCE_PREFIX}${encodeURIComponent(trailId)}`;
+
+const buildExampleResource = (
+  trailItem: Trail<unknown, unknown, unknown>
+):
+  | {
+      readonly content: McpResourceContent;
+      readonly listing: McpResourceDefinition;
+    }
+  | undefined => {
+  const examples = deriveStructuredTrailExamples(trailItem.examples);
+  if (examples === undefined) {
+    return undefined;
+  }
+
+  const uri = examplesUriForTrail(trailItem.id);
+  return {
+    content: {
+      mimeType: 'application/json',
+      text: asJson({
+        examples,
+        trailId: trailItem.id,
+      }),
+      uri,
+    },
+    listing: {
+      description: `Structured examples for trail "${trailItem.id}".`,
+      mimeType: 'application/json',
+      name: `Trail examples: ${trailItem.id}`,
+      uri,
+    },
+  };
+};
+
+const buildExampleResources = (
+  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) =>
+      buildExampleResource(trailItem as Trail<unknown, unknown, unknown>)
+    )
+    .filter((resource) => resource !== undefined);
+};
+
+/**
+ * Build the cold-context MCP resources for a Trails graph and tool set.
+ *
+ * @example
+ * ```ts
+ * import { buildMcpResources, deriveMcpTools } from '@ontrails/mcp';
+ *
+ * const tools = deriveMcpTools(app).value;
+ * const resources = buildMcpResources(app, tools);
+ * ```
+ */
+export const buildMcpResources = (
+  graph: Topo,
+  tools: readonly McpToolDefinition[],
+  config: McpResourcesConfig = {}
+): BuiltMcpResources => {
+  const listings: McpResourceDefinition[] = [];
+  const contents = new Map<string, McpResourceContent>();
+
+  if (config.surfaceMap !== false) {
+    const surfaceMapListing = {
+      description: 'Resolved MCP surface projection for this Trails app.',
+      mimeType: 'application/json',
+      name: 'Trails MCP surface map',
+      uri: MCP_SURFACE_MAP_RESOURCE_URI,
+    };
+    listings.push(surfaceMapListing);
+    contents.set(MCP_SURFACE_MAP_RESOURCE_URI, {
+      mimeType: 'application/json',
+      text: asJson(buildSurfaceMap(tools)),
+      uri: MCP_SURFACE_MAP_RESOURCE_URI,
+    });
+  }
+
+  if (config.examples !== false) {
+    for (const resource of buildExampleResources(graph, tools)) {
+      listings.push(resource.listing);
+      contents.set(resource.content.uri, resource.content);
+    }
+  }
+
+  return {
+    list: listings,
+    read: (uri) => contents.get(uri),
+  };
+};
+
+/**
+ * Return whether an MCP tool was projected from a surface facet.
+ *
+ * @example
+ * ```ts
+ * import { isMcpFacetTool } from '@ontrails/mcp';
+ *
+ * const facetTools = tools.filter(isMcpFacetTool);
+ * ```
+ */
+export const isMcpFacetTool = (tool: McpToolDefinition): boolean =>
+  tool._meta?.[MCP_TOOL_FACET_META_KEY] !== undefined;

package/src/surface.ts

@@ -5,7 +5,9 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import {
   CallToolRequestSchema,
+  ListResourcesRequestSchema,
   ListToolsRequestSchema,
+  ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import type {
   BaseSurfaceOptions,
@@ -15,8 +17,14 @@ import type {
   TrailContextInit,
 } from '@ontrails/core';
 
-import type { McpToolDefinition, ResolveMcpPermit } from './build.js';
+import type {
+  McpSurfaceFacetMap,
+  McpToolDefinition,
+  ResolveMcpPermit,
+} from './build.js';
 import { deriveMcpTools } from './build.js';
+import { buildMcpResources } from './resources.js';
+import type { BuiltMcpResources, McpResourcesConfig } from './resources.js';
 import { connectStdio } from './stdio.js';
 
 // ---------------------------------------------------------------------------
@@ -28,7 +36,9 @@ export interface CreateServerOptions extends BaseSurfaceOptions {
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
   readonly description?: string | undefined;
+  readonly facets?: McpSurfaceFacetMap | undefined;
   readonly layers?: readonly Layer[] | undefined;
+  readonly mcpResources?: McpResourcesConfig | false | undefined;
   readonly name?: string | undefined;
   readonly resources?: ResourceOverrideMap | undefined;
   readonly resolvePermit?: ResolveMcpPermit | undefined;
@@ -56,12 +66,16 @@ const createMcpServer = (
     readonly name: string;
     readonly version: string;
     readonly description?: string | undefined;
-  }
+  },
+  mcpResources?: BuiltMcpResources | undefined
 ): Server => {
   const server = new Server(
     { name: info.name, version: info.version },
     {
-      capabilities: { tools: {} },
+      capabilities: {
+        ...(mcpResources === undefined ? {} : { resources: {} }),
+        tools: {},
+      },
       ...(info.description === undefined
         ? {}
         : { instructions: info.description }),
@@ -149,6 +163,31 @@ const createMcpServer = (
     }
   );
 
+  if (mcpResources !== undefined) {
+    // oxlint-disable-next-line require-await -- MCP SDK requires async handler
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+      resources: mcpResources.list.map((resource) => ({
+        description: resource.description,
+        mimeType: resource.mimeType,
+        name: resource.name,
+        uri: resource.uri,
+      })),
+    }));
+
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const content = mcpResources.read(request.params.uri);
+      return {
+        contents: [
+          content ?? {
+            mimeType: 'text/plain',
+            text: `Unknown MCP resource: ${request.params.uri}`,
+            uri: request.params.uri,
+          },
+        ],
+      };
+    });
+  }
+
   return server;
 };
 
@@ -179,6 +218,7 @@ export const createServer = (
     configValues: options.configValues,
     createContext: options.createContext,
     exclude: options.exclude,
+    facets: options.facets,
     include: options.include,
     intent: options.intent,
     layers: options.layers,
@@ -191,11 +231,20 @@ export const createServer = (
     throw toolsResult.error;
   }
 
-  return createMcpServer(toolsResult.value, {
-    description: options.description ?? graph.description,
-    name: options.name ?? graph.name,
-    version: options.version ?? graph.version ?? '0.1.0',
-  });
+  const mcpResources =
+    options.mcpResources === false
+      ? undefined
+      : buildMcpResources(graph, toolsResult.value, options.mcpResources);
+
+  return createMcpServer(
+    toolsResult.value,
+    {
+      description: options.description ?? graph.description,
+      name: options.name ?? graph.name,
+      version: options.version ?? graph.version ?? '0.1.0',
+    },
+    mcpResources
+  );
 };
 
 // ---------------------------------------------------------------------------