blume 1.5.2 → 1.6.0

package/src/ai/component-markdown.ts

@@ -3,6 +3,7 @@ import { mdxToMdast } from "satteri";
 
 import { parseYouTubeId } from "../components/content/youtube.ts";
 import type { ExampleLookup } from "../core/types.ts";
+import { MDX_FEATURES } from "../markdown/features.ts";
 
 /**
  * Downlevel Blume's MDX components to plain Markdown for agent-facing output
@@ -26,7 +27,8 @@ interface Offset {
   offset: number;
 }
 
-interface MdastNode {
+/** The structural slice of an mdast node the downlevel walk reads. */
+export interface MdastNode {
   attributes?: MdxAttribute[];
   children?: MdastNode[];
   name?: string;
@@ -80,8 +82,28 @@ export interface ComponentMarkdownChild extends EvaluatedProps {
   children: string;
 }
 
+/** One direct child of a component — a child component or prose — as Markdown. */
+export interface ComponentMarkdownBlock {
+  /**
+   * The child downleveled: a serializable component's rendering (through the
+   * registry, so a user override of that component applies), or — for prose,
+   * a component with no serializer, or one that declined — its source with
+   * any serializable descendants downleveled in place.
+   */
+  markdown: string;
+  /** The JSX name of a child component; `undefined` for prose. */
+  name?: string;
+}
+
 /** What a serializer receives for one component usage. */
 export interface ComponentMarkdownContext extends EvaluatedProps {
+  /**
+   * Every direct child of the element in document order, components and
+   * prose alike, each as a block of Markdown. For a container that is nothing
+   * but its contents — `<CardGroup>` — joining these with blank lines is the
+   * whole serializer.
+   */
+  childBlocks: () => ComponentMarkdownBlock[];
   /** Direct child components of `name`, each with evaluated props and body. */
   childComponents: (name: string) => ComponentMarkdownChild[];
   /** The element's body, downleveled and dedented (empty if self-closing). */
@@ -160,9 +182,10 @@ const readProps = (
   return { lossy, props };
 };
 
-const hasOffsets = (
-  node: MdastNode
-): node is MdastNode & { position: { end: Offset; start: Offset } } =>
+/** A node Satteri stamped with byte offsets. */
+type Positioned = MdastNode & { position: { end: Offset; start: Offset } };
+
+const hasOffsets = (node: MdastNode): node is Positioned =>
   typeof node.position?.start?.offset === "number" &&
   typeof node.position?.end?.offset === "number";
 
@@ -352,6 +375,80 @@ const tabs: ComponentMarkdown = ({ childComponents, children }) => {
     .join("\n\n");
 };
 
+/** Escape the brackets that would end a link's text early. */
+const linkText = (value: string): string =>
+  value.replaceAll(/[[\]]/gu, String.raw`\$&`);
+
+/**
+ * A link destination. Whitespace ends one, and a `)` ends one unless it is
+ * part of a balanced pair — so an href carrying either goes in the angle
+ * bracket form, where only `<` and `>` are special.
+ */
+const linkDestination = (href: string): string =>
+  /[\s()<>]/u.test(href)
+    ? `<${href.replaceAll(/[<>]/gu, String.raw`\$&`)}>`
+    : href;
+
+/** A text prop: a string, or a number stringified — `title={2024}` is a title. */
+const textProp = (value: EvaluatedValue): string => {
+  if (isString(value)) {
+    return value.trim();
+  }
+  return isNumber(value) ? String(value) : "";
+};
+
+/**
+ * A card is a link with a blurb, so that is what it becomes: the title as the
+ * link text, the body under it, and the call to action last — the order the
+ * card renders in. Shaped like {@link tabs}, a bold label over the body,
+ * rather than a heading: a card sits inside a page whose outline its author
+ * wrote, and a heading would add a level to it.
+ *
+ * The icon and image are presentation and drop out. A card with no title
+ * falls back to its `href`, and one with neither is just its body. `lossy`
+ * declines: a title or href recovered from an expression that would not
+ * evaluate is a link pointing somewhere wrong, which is worse than the
+ * visible JSX.
+ */
+const card: ComponentMarkdown = ({ children, lossy, props }) => {
+  if (lossy) {
+    return null;
+  }
+  const title = textProp(props.title);
+  const href = isString(props.href) ? props.href.trim() : "";
+  const body = children.trim();
+  const cta = textProp(props.cta);
+  const label = title || href;
+  if (label === "") {
+    // Nothing to head the card with, so it is whatever text it carries.
+    const rest = [body, cta].filter(Boolean).join("\n\n");
+    // Nothing but presentation left — keep the JSX rather than delete a card.
+    return rest === "" ? null : rest;
+  }
+  const head =
+    href === ""
+      ? `**${label}**`
+      : `**[${linkText(label)}](${linkDestination(href)})**`;
+  return [head, body, cta].filter(Boolean).join("\n\n");
+};
+
+/**
+ * `CardGroup` is the grid its cards sit in and carries no meaning of its own,
+ * so it becomes its contents: every direct child in order, each a block, a
+ * blank line between them. Built on `childBlocks` rather than extracting the
+ * cards so nothing the group holds is lost — a `Card` renders through the
+ * registry (a user override of `Card` applies in here too), a nested group
+ * recurses, prose between the cards stays, and a card that declines keeps its
+ * JSX as a block of its own instead of vanishing beside a rendered sibling.
+ * Passing the body slice through instead would leave each card's source
+ * indentation in the output and run one card's title straight on from the
+ * previous card's body as the same paragraph.
+ */
+const cardGroup: ComponentMarkdown = ({ childBlocks }) =>
+  childBlocks()
+    .map((block) => block.markdown)
+    .join("\n\n");
+
 const youtube: ComponentMarkdown = ({ props }) => {
   let input = "";
   if (isString(props.id)) {
@@ -407,6 +504,8 @@ export const exampleComponentSerializers = (examples: ExampleLookup) =>
  */
 const SERIALIZERS = {
   Callout: callout,
+  Card: card,
+  CardGroup: cardGroup,
   Steps: steps,
   Tabs: tabs,
   TypeTable: typeTable,
@@ -428,29 +527,37 @@ const componentHint = (registry: Record<string, ComponentMarkdown>): RegExp =>
 const BUILT_IN_HINT = componentHint(SERIALIZERS);
 
 /** One downlevel pass's inputs: the source, registry, and page metadata. */
-interface Walk {
+/** What a downlevel walk needs: the serializers, the page's front matter, and the source its nodes were parsed from. */
+export interface DownlevelWalk {
   frontmatter: Record<string, EvaluatedValue> | undefined;
   registry: Record<string, ComponentMarkdown>;
   source: string;
 }
+type Walk = DownlevelWalk;
+
+/** The serializer registry for a site: built-ins under a user's `ai.markdownComponents`. */
+export const componentRegistry = (
+  components?: Record<string, ComponentMarkdown>
+): Record<string, ComponentMarkdown> =>
+  components && Object.keys(components).length > 0
+    ? { ...SERIALIZERS, ...components }
+    : SERIALIZERS;
 
 /**
- * The element's body as Markdown: the verbatim source slice covering its
- * children, with any serializable descendant components downleveled in place.
- * Mutually recursive with {@link collectSplices} (a container's children may
- * hold further serializable components), hence the forward reference.
+ * A source slice as Markdown: the verbatim `[start, end)` range with any
+ * serializable component under `nodes` downleveled in place, dedented and
+ * trimmed. Mutually recursive with {@link collectSplices} (the nodes may hold
+ * further serializable components), hence the forward reference.
  */
-const renderChildren = (walk: Walk, node: MdastNode): string => {
-  const children = (node.children ?? []).filter(hasOffsets);
-  const [first] = children;
-  if (!first) {
-    return "";
-  }
-  const start = first.position.start.offset;
-  const end = children.at(-1)?.position.end.offset ?? start;
+const renderSlice = (
+  walk: Walk,
+  start: number,
+  end: number,
+  nodes: MdastNode[]
+): string => {
   const splices: Splice[] = [];
   // oxlint-disable-next-line no-use-before-define
-  collectSplices(walk, children, splices);
+  collectSplices(walk, nodes, splices);
   const spliced = applySplices(
     walk.source.slice(start, end),
     splices.map((splice) => ({
@@ -462,6 +569,45 @@ const renderChildren = (walk: Walk, node: MdastNode): string => {
   return dedent(spliced).trim();
 };
 
+/** The element's body as Markdown: the slice covering all of its children. */
+const renderChildren = (walk: Walk, node: MdastNode): string => {
+  const children = (node.children ?? []).filter(hasOffsets);
+  const [first] = children;
+  if (!first) {
+    return "";
+  }
+  const start = first.position.start.offset;
+  return renderSlice(
+    walk,
+    start,
+    children.at(-1)?.position.end.offset ?? start,
+    children
+  );
+};
+
+/**
+ * One direct child as a block of Markdown: a registered component's own
+ * rendering, else — prose, an unknown component, or one that declined — its
+ * source slice, the same choice {@link collectSplices} makes at the top level.
+ */
+const renderBlock = (walk: Walk, node: Positioned): string => {
+  const serializer =
+    isJsxElement(node) && node.name ? walk.registry[node.name] : undefined;
+  const text = serializer
+    ? // oxlint-disable-next-line no-use-before-define
+      serializeElement(serializer, walk, node)
+    : null;
+  return (
+    text ??
+    renderSlice(
+      walk,
+      node.position.start.offset,
+      node.position.end.offset,
+      node.children ?? []
+    )
+  );
+};
+
 /** Serialize one component usage, or `null` to keep its JSX verbatim. */
 const serializeElement = (
   serializer: ComponentMarkdown,
@@ -470,6 +616,11 @@ const serializeElement = (
 ): string | null =>
   serializer({
     ...readProps(node, walk.frontmatter),
+    childBlocks: () =>
+      (node.children ?? []).filter(hasOffsets).map((child) => ({
+        markdown: renderBlock(walk, child),
+        name: isJsxElement(child) ? child.name : undefined,
+      })),
     childComponents: (name) =>
       (node.children ?? [])
         .filter((child) => isJsxElement(child) && child.name === name)
@@ -487,26 +638,38 @@ const serializeElement = (
  * doesn't descend into it; when a serializer declines, the walk continues
  * inside so nested serializable components still convert.
  */
+/**
+ * Downlevel one parsed component to the Markdown its serializer emits, or
+ * `null` when the node isn't a component, has no serializer, or its
+ * serializer declines. `walk.source` must be the text `node` was parsed from.
+ */
+export const downlevelComponentNode = (
+  node: MdastNode,
+  walk: DownlevelWalk
+): string | null => {
+  const serializer =
+    node.type === "mdxJsxFlowElement" && node.name
+      ? walk.registry[node.name]
+      : undefined;
+  return serializer && hasOffsets(node)
+    ? serializeElement(serializer, walk, node)
+    : null;
+};
+
 const collectSplices = (
   walk: Walk,
   nodes: MdastNode[],
   out: Splice[]
 ): void => {
   for (const node of nodes) {
-    const serializer =
-      node.type === "mdxJsxFlowElement" && node.name
-        ? walk.registry[node.name]
-        : undefined;
-    if (serializer && hasOffsets(node)) {
-      const text = serializeElement(serializer, walk, node);
-      if (text !== null) {
-        out.push({
-          end: node.position.end.offset,
-          start: node.position.start.offset,
-          text,
-        });
-        continue;
-      }
+    const text = hasOffsets(node) ? downlevelComponentNode(node, walk) : null;
+    if (text !== null && hasOffsets(node)) {
+      out.push({
+        end: node.position.end.offset,
+        start: node.position.start.offset,
+        text,
+      });
+      continue;
     }
     collectSplices(walk, node.children ?? [], out);
   }
@@ -531,9 +694,9 @@ export const downlevelComponents = (
   components?: Record<string, ComponentMarkdown>,
   frontmatter?: Record<string, EvaluatedValue>
 ): string => {
-  const custom = components && Object.keys(components).length > 0;
-  const registry = custom ? { ...SERIALIZERS, ...components } : SERIALIZERS;
-  const hint = custom ? componentHint(registry) : BUILT_IN_HINT;
+  const registry = componentRegistry(components);
+  const hint =
+    registry === SERIALIZERS ? BUILT_IN_HINT : componentHint(registry);
   if (!hint.test(source)) {
     return source;
   }
@@ -541,7 +704,7 @@ export const downlevelComponents = (
   try {
     // SAFETY: MdastNode is a structural subset of Satteri's mdast output —
     // every node carries `type`, and the walk reads only optional fields.
-    tree = mdxToMdast(source) as MdastNode;
+    tree = mdxToMdast(source, { features: MDX_FEATURES }) as MdastNode;
   } catch {
     return source;
   }

package/src/ai/llms.ts

@@ -3,13 +3,16 @@ import { rewriteRelativeImages } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { absoluteUrl } from "../core/site-url.ts";
-import { readEntryText } from "../core/sources/read.ts";
+import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
+import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
 import {
   downlevelComponents,
   exampleComponentSerializers,
 } from "./component-markdown.ts";
+import { AGENT_SKILLS_DIR, AGENT_SKILLS_INDEX_PATH } from "./skills.ts";
+import type { SkillArtifact } from "./skills.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top —
@@ -21,6 +24,65 @@ const pageUrl = (route: string, site?: string, base = ""): string => {
   return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 
+/** Inputs only the build has: the published skills, collected once per build. */
+export interface LlmsIndexOptions {
+  /**
+   * The Agent Skills the build publishes under `/.well-known/agent-skills/`,
+   * listed in their own section with each skill's description — which is
+   * where a skill says when to use it. Absent (empty) for the homepage
+   * Markdown mirror, which is synthesized before the skills are collected.
+   */
+  skills?: readonly SkillArtifact[];
+}
+
+/** A skill description on one line — SKILL.md frontmatter may wrap it. */
+const oneLine = (text: string): string => text.replaceAll(/\s+/gu, " ").trim();
+
+/**
+ * The "Agent resources" section: every machine-readable artifact the site
+ * publishes, so an agent that only reads llms.txt still finds the full
+ * Markdown dump, the per-page Markdown mirrors, the MCP server, the skills
+ * index, the API catalog, the readability manifest, and the sitemap. The
+ * same artifact set `agent-readability.json` indexes, in prose an agent can
+ * act on without a second fetch.
+ */
+const agentResourceLines = (project: BlumeProject): string[] => {
+  const { config } = project;
+  const { site } = config.deployment;
+  const url = (path: string): string =>
+    pageUrl(path, site, normalizeBasePath(config.deployment.base));
+  const lines = [
+    `- [llms-full.txt](${url("/llms-full.txt")}): The full Markdown of every page in one file.`,
+    `- [Page Markdown](${url("/index.md")}): Append \`.md\` to any page URL to fetch that page as raw Markdown.`,
+  ];
+  if (config.ai.mcp.enabled) {
+    lines.push(
+      `- [MCP server](${url(config.ai.mcp.route)}): Streamable HTTP Model Context Protocol server with search_docs, get_page, list_pages, and get_navigation tools, plus every page as a resource. Discovery document: ${url("/.well-known/mcp.json")}`
+    );
+  }
+  if (config.ai.skills) {
+    lines.push(
+      `- [Agent skills](${url(AGENT_SKILLS_INDEX_PATH)}): Agent Skills discovery index of the skills this site publishes.`
+    );
+  }
+  if (hasApiCatalog(config)) {
+    lines.push(
+      `- [API catalog](${url(API_CATALOG_PATH)}): RFC 9727 linkset of the APIs documented here.`
+    );
+  }
+  if (config.seo.agentReadability) {
+    lines.push(
+      `- [agent-readability.json](${url("/agent-readability.json")}): Manifest of every agent-facing artifact on this site.`
+    );
+  }
+  if (site && config.seo.sitemap) {
+    lines.push(
+      `- [Sitemap](${url("/sitemap.xml")}): Every indexable page URL with its last-modified date.`
+    );
+  }
+  return lines;
+};
+
 // Drafts, hidden, and ordinary `noindex` pages are excluded. Generated API
 // references keep crawler visibility (`noindex`) separate from LLM visibility
 // (`ai.exclude`), and are excluded wholesale when `ai.llmsTxt.openapi` is off.
@@ -88,7 +150,10 @@ const indexedNavigations = (
  * Also serves as the homepage's synthesized Markdown mirror when the home
  * route is a landing page (see `buildRawMarkdown`).
  */
-export const buildLlmsIndex = (project: BlumeProject): string => {
+export const buildLlmsIndex = (
+  project: BlumeProject,
+  options: LlmsIndexOptions = {}
+): string => {
   const { config } = project;
   const { site } = config.deployment;
   const base = normalizeBasePath(config.deployment.base);
@@ -187,10 +252,31 @@ export const buildLlmsIndex = (project: BlumeProject): string => {
     );
   }
 
+  // The published skills, each with its description — the one place a skill
+  // states when an agent should reach for it.
+  const skills = options.skills ?? [];
+  if (skills.length > 0) {
+    blocks.push(
+      "## Agent skills",
+      skills
+        .map(
+          (skill) =>
+            `- [${skill.name}](${pageUrl(`${AGENT_SKILLS_DIR}/${skill.path}`, site, base)}): ${oneLine(skill.description)}`
+        )
+        .join("\n")
+    );
+  }
+
+  blocks.push("## Agent resources", agentResourceLines(project).join("\n"));
+
   const header = config.description
     ? `# ${config.title}\n\n> ${config.description}`
     : `# ${config.title}`;
-  return `${[header, ...blocks].join("\n\n")}\n`;
+  // `details` is the llms.txt spec's free-form block between the summary and
+  // the file sections — "when to use this" guidance in the site's own words.
+  const { details } = config.ai.llmsTxt;
+  const lead = details ? `${header}\n\n${details}` : header;
+  return `${[lead, ...blocks].join("\n\n")}\n`;
 };
 
 /** Build `llms-full.txt`: the full Markdown body of every current-docs page. */
@@ -208,7 +294,7 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
 
   const sections = await Promise.all(
     pages.map(async (page) => {
-      let raw = await readEntryText(project, page);
+      let raw = await readExpandedEntryText(project, page);
       // Colocated `./image.png` references resolve to nothing for a reader of
       // llms-full.txt; point them at the served originals instead.
       if (page.sourcePath) {
@@ -246,8 +332,9 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
 
 /** Build both LLM text artifacts for a project. */
 export const buildLlmsFiles = async (
-  project: BlumeProject
+  project: BlumeProject,
+  options: LlmsIndexOptions = {}
 ): Promise<{ index: string; full: string }> => ({
   full: await buildFull(project),
-  index: buildLlmsIndex(project),
+  index: buildLlmsIndex(project, options),
 });

package/src/ai/markdown.ts

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { rewriteRelativeImages } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
-import { readEntryText } from "../core/sources/read.ts";
+import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
 import {
   downlevelComponents,
@@ -65,7 +65,7 @@ export const buildRawMarkdown = async (
   const readRoute = async (route: RouteManifestEntry): Promise<string> => {
     const page = pageById.get(route.id);
     if (page) {
-      return await readEntryText(project, page);
+      return await readExpandedEntryText(project, page);
     }
     return route.sourcePath ? await readFile(route.sourcePath, "utf-8") : "";
   };

package/src/ai/mcp/discovery.ts

@@ -103,7 +103,10 @@ const HTTP_URL = /^https?:\/\//u;
  */
 export interface McpServerCard {
   $schema: string;
-  capabilities: { tools: { listChanged: boolean } };
+  capabilities: {
+    resources: { listChanged: boolean; subscribe: boolean };
+    tools: { listChanged: boolean };
+  };
   description: string;
   name: string;
   /** Absolute endpoints only — present when a `site` is configured. */
@@ -122,7 +125,12 @@ export const buildMcpServerCard = (input: McpDiscoveryInput): McpServerCard => {
   const url = serverUrl(input);
   const card: McpServerCard = {
     $schema: SERVER_CARD_SCHEMA,
-    capabilities: { tools: { listChanged: false } },
+    // Resources mirror the page list (one `text/markdown` resource per page);
+    // a rebuilt site replaces the server wholesale, so nothing changes live.
+    capabilities: {
+      resources: { listChanged: false, subscribe: false },
+      tools: { listChanged: false },
+    },
     description: truncate(
       `Model Context Protocol server for the ${input.name} documentation.`
     ),

package/src/ai/mcp/server.ts

@@ -3,7 +3,10 @@ import type { ServerOptions } from "@modelcontextprotocol/sdk/server/index.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import {
   CallToolRequestSchema,
+  ListResourcesRequestSchema,
   ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
@@ -33,6 +36,12 @@ const DEFAULT_SEARCH_LIMIT = 8;
 const MAX_SEARCH_LIMIT = 20;
 /** Excerpt length when a page has no description. */
 const EXCERPT_LENGTH = 200;
+/** Every page resource is the page's agent Markdown. */
+const RESOURCE_MIME_TYPE = "text/markdown";
+/** The MCP spec's JSON-RPC code for an unknown resource URI. */
+const RESOURCE_NOT_FOUND = -32_002;
+/** URI scheme for page resources when no `deployment.site` is configured. */
+const LOCAL_RESOURCE_SCHEME = "blume:";
 
 const CORS_HEADERS = {
   "Access-Control-Allow-Headers":
@@ -191,6 +200,15 @@ interface SearchHitPayload {
   version?: string;
 }
 
+/** One `resources/list` entry: a page served as `text/markdown`. */
+interface PageResource {
+  description?: string;
+  mimeType: string;
+  name: string;
+  title: string;
+  uri: string;
+}
+
 /** One `list_pages` entry; `version` only appears on versioned sites. */
 interface PageListingPayload {
   contentType: string;
@@ -288,6 +306,26 @@ const urlFor = (route: string, data: McpData): string => {
   return data.site ? absoluteUrl(data.site, path) : path;
 };
 
+/**
+ * A page's resource URI. Resource URIs must be absolute, so this is the page's
+ * served URL when a site is configured (the same URL `search_docs` and
+ * `list_pages` emit, so an agent can hand either back to `resources/read`),
+ * and a `blume:` URI carrying the based route otherwise.
+ */
+const resourceUri = (route: string, data: McpData): string =>
+  data.site
+    ? urlFor(route, data)
+    : `${LOCAL_RESOURCE_SCHEME}${withBasePath(data.base, route)}`;
+
+/** The `pages` key a resource URI (either form, or a bare route) names. */
+const resourceRoute = (uri: string, data: McpData): string =>
+  normalizeRoute(
+    uri.startsWith(LOCAL_RESOURCE_SCHEME)
+      ? uri.slice(LOCAL_RESOURCE_SCHEME.length)
+      : uri,
+    data
+  );
+
 /** A hit's excerpt: its description, else the head of its content with an
  * ellipsis only when something was actually cut off. */
 const excerptFor = (doc: OramaDoc): string => {
@@ -331,9 +369,10 @@ export const buildServer = (
   data: McpData,
   index: OramaIndexProvider
 ): Server => {
+  const capabilities = { resources: {}, tools: {} };
   const serverOptions: ServerOptions = data.instructions
-    ? { capabilities: { tools: {} }, instructions: data.instructions }
-    : { capabilities: { tools: {} } };
+    ? { capabilities, instructions: data.instructions }
+    : { capabilities };
   const server = new Server(
     { name: data.name, version: data.version },
     serverOptions
@@ -343,6 +382,39 @@ export const buildServer = (
     tools: TOOL_DEFINITIONS,
   }));
 
+  // Every page doubles as a resource, so a client that attaches context by
+  // URI (rather than calling tools) can browse and read the docs too. The
+  // list is the same route set `list_pages` returns; reading one serves the
+  // same agent Markdown `get_page` does.
+  server.setRequestHandler(ListResourcesRequestSchema, () => ({
+    resources: data.routes.map((route) => {
+      const resource: PageResource = {
+        mimeType: RESOURCE_MIME_TYPE,
+        name: route.title,
+        title: route.title,
+        uri: resourceUri(route.route, data),
+      };
+      if (route.description) {
+        resource.description = route.description;
+      }
+      return resource;
+    }),
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, (request) => {
+    const { uri } = request.params;
+    const markdown = data.pages[resourceRoute(uri, data)];
+    if (markdown === undefined) {
+      throw new McpError(
+        RESOURCE_NOT_FOUND,
+        `No page found at "${uri}". Use resources/list or list_pages to find valid URIs.`
+      );
+    }
+    return {
+      contents: [{ mimeType: RESOURCE_MIME_TYPE, text: markdown, uri }],
+    };
+  });
+
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { arguments: args = {}, name } = request.params;