blume 1.1.3 → 1.2.0

package/dist/types/openapi/references.d.ts

@@ -31,6 +31,12 @@ export interface ReferenceSource {
      */
     basePath: string;
     label: string;
+    /** Whether generated pages are included in llms.txt/llms-full.txt. */
+    includeInLlms: boolean;
+    /** Whether generated pages are included in site search. */
+    includeInSearch: boolean;
+    /** Whether generated pages emit noindex metadata and stay out of the sitemap. */
+    noindex: boolean;
     /** Local path or `http(s)` URL, verbatim from config. */
     spec: string;
     /** Per-block Scalar theme name override, if any (Scalar renderer only). */

package/docs/advanced/api-reference.mdx

@@ -78,6 +78,33 @@ openapi: {
 
 `spec` is shorthand for a single-entry `sources`, so you only reach for `sources` when you have more than one.
 
+### Per-source indexing
+
+Generated pages participate in search, `llms.txt`, and crawler indexing by default. A secondary or overlapping spec can opt out of any surface without hiding its pages or removing it from navigation:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  sources: [
+    { label: "Public API", route: "/api", spec: "./public.json" },
+    {
+      label: "Platform API",
+      route: "/platform",
+      spec: "./platform.json",
+      includeInSearch: false,
+      includeInLlms: false,
+      noindex: true,
+    },
+  ],
+}
+```
+
+- `includeInSearch: false` keeps the source's overview and operations out of site search.
+- `includeInLlms: false` keeps them out of both `llms.txt` files.
+- `noindex: true` adds crawler noindex metadata and removes the pages from the sitemap.
+
+With the [Scalar renderer](#the-scalar-renderer), only `noindex` applies — a Scalar-rendered reference already sits outside Blume's search and `llms.txt`, so the two `include*` settings have nothing to act on there.
+
 ## Authorization
 
 Operations that declare [security requirements](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) render an **Authorization** section above their parameters, and the generated code samples send a placeholder credential (`Authorization: Bearer YOUR_TOKEN`, an API-key header, or a query key — whatever the scheme calls for). There's nothing to configure: Blume reads `security` from the spec, so the reference always matches what the API actually enforces.

package/docs/advanced/changelog.mdx

@@ -61,6 +61,16 @@ Once you have at least one `type: changelog` entry, Blume generates a **`/change
 
 The page appears only when nothing already occupies the `/changelog` route. To replace it with your own design, add a [custom page](/docs/advanced/custom-pages) at `pages/changelog.astro` — it takes over and Blume stops generating the default timeline.
 
+Because this page is generated rather than authored, it isn't part of the content tree — so a header [tab](/docs/content/navigation#tabs) pointing at `/changelog` resolves to the newest entry instead. Give the tab an `href` to land on the index itself:
+
+```ts blume.config.ts
+navigation: {
+  tabs: [
+    { label: "Changelog", path: "/changelog", href: "/changelog" },
+  ],
+}
+```
+
 ### Grouped by major version
 
 When your versions follow [semver](https://semver.org) and span more than one major, Blume paginates the timeline by major version. Only the newest major line is shown, with a **Show N.x releases** button at the bottom that reveals the next-oldest major one click at a time:

package/docs/configuration/ai.mdx

@@ -33,6 +33,18 @@ ai: {
 }
 ```
 
+To keep an individual page out of both files, set `ai.exclude` in its frontmatter:
+
+```mdx
+---
+title: Internal notes
+ai:
+  exclude: true
+---
+```
+
+The page still renders, stays in search, and keeps its place in the sitemap — only the `llms.txt` files skip it.
+
 To take full control of either file, add your own `llms.txt` or `llms-full.txt` to your `public/` folder. Like a custom favicon, it's picked up automatically and ships in place of the generated file — override one and Blume still generates the other.
 
 ## Raw Markdown
@@ -128,9 +140,33 @@ The page the reader is currently on is added to the context first and used to sc
 
 Grounding is on for every backend except **[Inkeep](#backends)**, which runs its own retrieval over the content you've indexed in its dashboard.
 
+### External endpoint
+
+Already have an API backend for AI? Point the panel at it and keep the docs build static:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    endpoint: "https://api.example.com/v1/docs/ask",
+  },
+}
+```
+
+Blume sends the same `POST` body as its built-in route:
+
+```json
+{
+  "messages": [{ "role": "user", "content": "How do I deploy?" }],
+  "page": { "path": "/deployment" }
+}
+```
+
+Return a successful response whose body is a plain UTF-8 text stream. If the endpoint is on another origin, allow the docs origin with CORS: accept `OPTIONS` and `POST`, permit the `content-type` request header, and return the CORS headers on both the preflight and streamed response. With `endpoint` set, Blume generates the chat UI but no server route, grounding snapshot, provider dependency, or provider-secret warning; your backend owns retrieval, authentication, rate limiting, model access, and citations.
+
 ### Server output required
 
-Ask AI is a server route (`POST /api/ask`), so it can't run on a static build. Switch to server output and pick an adapter:
+Blume's built-in Ask AI backend is a server route (`POST /api/ask`), so it can't run on a static build. Switch to server output and pick an adapter:
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -139,7 +175,7 @@ deployment: {
 }
 ```
 
-A static build with Ask AI enabled fails fast with a message telling you to set `deployment.output` to `server`. See [Deployment](/docs/deployment) for the adapters.
+A static build with Ask AI enabled and no external `endpoint` fails fast with a message telling you to set `deployment.output` to `server`. See [Deployment](/docs/deployment) for the adapters.
 
 ### Backends
 

package/docs/configuration/customization.mdx

@@ -145,6 +145,33 @@ blume add pagination
 
 The copy imports the rest of the framework from `blume/*`, so it renders exactly like the built-in until you change it. `blume add` prints the `defineComponents` snippet to register it — content components under `mdx`, layout pieces under `layout`.
 
+## Astro integrations
+
+Add any Astro integration from the top-level `integrations` array in `blume.config.ts`. Install the integration in your site first; Blume does not add it to the generated runtime's dependencies or manage its Astro compatibility.
+
+```bash
+npm install @astrojs/sitemap
+```
+
+```ts blume.config.ts lineNumbers
+import sitemap from "@astrojs/sitemap";
+import { defineConfig } from "blume";
+
+export default defineConfig({
+  integrations: [
+    sitemap({
+      filter: (page) => !page.includes("/drafts/"),
+    }),
+  ],
+});
+```
+
+Blume keeps its built-in integrations in their existing order, then appends your entries in declaration order. It does not sort or deduplicate them, so two integrations with the same `name` both run. Blume validates that `integrations` is an array, while Astro validates each entry and reports invalid integrations.
+
+Because Blume loads your integrations by re-importing `blume.config.ts` from the generated Astro config rather than copying the instances, the config module evaluates twice per run — once when Blume reads your config and once when Astro loads it. Keep integration factories side-effect free (return the integration; don't write files or open connections at construction) so the second evaluation is harmless.
+
+The same integrations run in `blume dev` and `blume build`. Editing `blume.config.ts` during `blume dev` regenerates the hidden Astro config and triggers a config restart; if you don't see an edited integration take effect, restart `blume dev`. Blume can't tell which config edits affect integrations, so once `integrations` is non-empty, every edit to `blume.config.ts` — even to an unrelated field — restarts the dev server rather than hot-applying. Blume only tracks the contents of `blume.config.ts`, so editing a separate file it imports won't trigger that regeneration on its own — restart `blume dev` after such edits. If you eject, the owned `astro.config.mjs` keeps a relative bridge to `blume.config.ts`, so the configured integrations continue to run; you can later move them directly into the Astro config as part of taking full ownership.
+
 ## Eject
 
 When you want full control, eject the generated runtime into a standalone Astro project:

package/docs/configuration/index.mdx

@@ -21,6 +21,7 @@ export default defineConfig({
 A broader example touching the most common options (see each feature's guide for the rest):
 
 ```ts blume.config.ts lineNumbers
+import sitemap from "@astrojs/sitemap";
 import { defineConfig } from "blume";
 
 export default defineConfig({
@@ -29,6 +30,9 @@ export default defineConfig({
   description: "Documentation for my project.",
   logo: "/logo.svg",
 
+  // Astro integrations — installed and versioned by this site
+  integrations: [sitemap()],
+
   // Content
   content: {
     root: "docs",
@@ -338,6 +342,7 @@ Each of these has its own guide. The config field is the entry point:
 | `seo` | Metadata, OG images, feeds, structured data | [SEO](/docs/configuration/seo) |
 | `deployment` | Output mode, adapter, and site URL | [Deployment](/docs/deployment) |
 | `redirects` | Permanent and temporary redirects | [Deployment](/docs/deployment#redirects) |
+| `integrations` | Astro integrations appended after Blume's built-ins | [Customization](/docs/configuration/customization#astro-integrations) |
 
 ## Precedence
 

package/docs/content/navigation.mdx

@@ -123,6 +123,18 @@ navigation: {
 }
 ```
 
+A tab's `path` is its section prefix, and it doubles as the link target. A section whose `path` isn't a page of its own — a folder with no `index.mdx` — would link to a 404, so the tab falls back to the first page in the section instead. Set `href` when you want it to land somewhere else:
+
+```ts blume.config.ts
+navigation: {
+  tabs: [
+    { label: "Changelog", path: "/changelog", href: "/changelog" },
+  ],
+}
+```
+
+This matters for routes that aren't part of the content tree, since the fallback can't see them: the generated [changelog](/docs/advanced/changelog) index, or a [custom page](/docs/advanced/custom-pages) you added under `pages/`. Without `href`, a `/changelog` tab lands on the newest entry rather than the index. Tabs that don't set `href` are unaffected.
+
 Tabs also **scope the sidebar**: when the current route falls under a tab's `path`, the sidebar shows only that section's pages — so `/adapters/*` lists the adapters and nothing else. The folder at a tab's `path` becomes the section, so this needs no extra config beyond the tabs themselves; structure your content into a folder per tab and point each tab at it.
 
 On a route under no tab (or a tab whose `path` is `/`), the sidebar shows the pages that _don't_ belong to a tab — each tab's folder is hidden from it, since that section already has its own tab in the header. So a root landing page lists your loose top-level pages while the sectioned content stays behind its tab, mirroring Fumadocs' root folders. If a route has no pages of its own to show this way, the full tree is shown instead, so the sidebar is never left blank.

package/docs/reference/cli.mdx

@@ -9,19 +9,20 @@ blume <command> [options]
 
 ## Commands
 
-| Command            | Description                                      |
-| ------------------ | ------------------------------------------------ |
-| `blume init [dir]` | Scaffold a project (interactive by default).     |
-| `blume dev`        | Start the dev server with hot reload.            |
-| `blume build`      | Build the static (or server) site.               |
-| `blume preview`    | Preview the last build.                          |
-| `blume add <item>` | Install a source component from the registry.    |
-| `blume sync`       | Re-fetch remote content sources and regenerate.  |
-| `blume eject`      | Promote the runtime into a standalone Astro app. |
-| `blume check`      | Type-check the site with `astro check`.          |
-| `blume doctor`     | Diagnose config and content problems.            |
-| `blume validate`   | Validate links across your content.              |
-| `blume audit`      | Audit the built site for SEO and health issues.  |
+| Command | Description |
+| --- | --- |
+| `blume init [dir]` | Scaffold a project (interactive by default). |
+| `blume dev` | Start the dev server with hot reload. |
+| `blume build` | Build the static (or server) site. |
+| `blume preview` | Preview the last build. |
+| `blume add <item>` | Install a source component from the registry. |
+| `blume sync` | Re-fetch remote content sources and regenerate. |
+| `blume eject` | Promote the runtime into a standalone Astro app. |
+| `blume check` | Type-check the site with `astro check`. |
+| `blume doctor` | Diagnose config and content problems. |
+| `blume validate` | Validate links across your content. |
+| `blume audit` | Audit the built site for SEO and health issues. |
+| `blume eval` | Test the docs: an agent answers your questions using only the documentation. |
 
 ## Common flags
 
@@ -58,6 +59,9 @@ blume <command> [options]
 - `blume audit --verbose` — list every affected page instead of the first few.
 - `blume audit --json` — emit the report as JSON on stdout.
 - `blume audit --claude` / `--codex` — hand the findings to Claude Code or Codex to fix interactively.
+- `blume eval` — run the questions in `evals.yaml` through an agent that reads only your docs; see [Evals](/docs/reference/eval).
+- `blume eval init` — have the agent draft a starter `evals.yaml` from your docs.
+- `blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose` — see [Evals](/docs/reference/eval) for each flag.
 
 ## Verifying while the dev server runs
 

package/docs/reference/eval.mdx

@@ -0,0 +1,106 @@
+---
+title: Evals
+description: blume eval gives your docs a test suite — an AI agent answers your users' questions using only the documentation, a judge grades the answers, and CI fails when the docs can't answer.
+---
+
+`blume audit` tells you whether crawlers can find your docs. `blume eval` tells you whether anyone can actually _use_ them: an AI agent reads your documentation the way a stranger would and tries to answer real user questions from it. When the docs don't state the answer, the run fails and names the page that should.
+
+```bash
+blume eval
+```
+
+```
+blume eval  3 question(s) · Claude Code
+
+  ✔ install-node-version         pass  1.00  14.2s  $0.14
+  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
+      missing: the adapter is auto-detected
+  ⊘ search-providers             skipped
+
+  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: the adapter is auto-detected
+
+  2 passed · 1 failed · 1 skipped · 1m 42s · $0.45
+```
+
+## How it works
+
+Each question runs through two agent sessions, using an agent CLI you already have installed — [Claude Code](https://claude.com/claude-code) by default, or [Codex](https://developers.openai.com/codex/cli) with `--agent codex`. Blume holds no API keys and calls no model itself.
+
+1. **The reader** answers the question using _only_ your documentation. It runs in an empty directory with its file, shell, and web tools disabled, connected to a private [MCP server](/docs/configuration/ai) that serves your docs — the same `search_docs`/`get_page` tools a real agent uses against your deployed site. It cannot read your repo, so it experiences the docs exactly like a fresh user: what isn't written doesn't exist.
+2. **The judge** grades the answer against the facts you listed, with no tools at all. Paraphrase passes; a missing or contradicted fact fails — and so does "the documentation doesn't say."
+
+The MCP snapshot is built from your content sources directly, so there is no need to run `blume build` first, and nothing is deployed or uploaded anywhere.
+
+An answer the docs _can't_ support fails even when the agent's prior knowledge happens to be right — that's the point. Your docs are the only source that ships.
+
+## Writing evals
+
+Questions live in `evals.yaml` at the project root. To have an agent draft a starter file from your existing docs:
+
+```bash
+blume eval init
+```
+
+Or write it by hand:
+
+```yaml
+questions:
+  - id: install-node-version
+    question: What is the minimum Node.js version required?
+    expected:
+      - Node 22.12 or newer
+    routes: /docs/quickstart
+  - id: deploy-vercel
+    question: How do I deploy to Vercel?
+    expected:
+      - run blume build
+      - the output directory is dist
+    routes:
+      - /docs/deployment
+  - id: search-providers
+    question: Which search providers are supported?
+    expected:
+      - pagefind is the default
+    severity: warning # a miss warns instead of failing CI
+    skip: true # temporarily excluded, reported as skipped
+```
+
+- `expected` lists the facts a correct answer must state, in substance — the judge accepts paraphrase and rejects contradiction.
+- `routes` names the page(s) that should answer the question. A failure is then anchored to that page's source file in the report; a hint that no longer matches a page is warned about rather than silently dropped.
+- `severity: warning` keeps a question in the report without failing CI; `skip: true` sits a question out entirely.
+
+Write questions your users actually ask — the ones from support threads, GitHub issues, and onboarding calls. The best evals encode a promise your docs make ("zero-config deploys") as a question that breaks when a PR breaks the promise.
+
+## Failing CI
+
+The exit code is the contract: any failed question exits non-zero. `--threshold` relaxes the gate to a passing fraction when you're digging out of a backlog:
+
+```bash
+blume eval                    # every question must pass
+blume eval --threshold 0.8    # at least 80% must pass
+blume eval --json             # machine-readable report on stdout
+```
+
+The JSON report carries the same `diagnostics` + `summary` shape as `blume validate --json` and `blume audit --json`, with the per-question results (answer, score, missing facts, cost) alongside.
+
+Because each question is two model sessions, an eval run costs real money and minutes — the per-question spend is printed as it runs. A sensible CI setup runs `blume eval` on docs changes rather than every push.
+
+## Fixing the findings
+
+Each failure names the missing facts and the page that should state them. To hand the whole report to the agent instead:
+
+```bash
+blume eval --fix
+```
+
+This writes the full JSON report to a file and opens the agent interactively with a prompt that walks it through each failed question: read the named page, add the missing facts in the page's voice, and rerun `blume eval` until everything passes. The session is interactive by design — you review the edits through the agent's own permission flow — and the agent is told never to delete questions or weaken expected facts to get to green.
+
+## Flags
+
+- `--agent claude|codex` — which agent CLI runs the reader and judge. Defaults to `claude`.
+- `--file <path>` — the evals file. Defaults to `evals.yaml`.
+- `--threshold <0..1>` — minimum passing fraction before the run exits non-zero. Defaults to `1`.
+- `--timeout <seconds>` — reader time limit per question. Defaults to `180`.
+- `--json` — emit the report as JSON on stdout.
+- `--fix` — after a failing run, hand the report to the agent to fix the docs interactively.
+- `--verbose` — include the reader's full answer under each failure.

package/docs/reference/meta.ts

@@ -2,6 +2,6 @@ import { defineMeta } from "blume";
 
 export default defineMeta({
   order: 6,
-  pages: ["frontmatter", "cli"],
+  pages: ["frontmatter", "cli", "eval"],
   title: "Reference",
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/ai/agent-readability.ts

@@ -27,6 +27,24 @@ const usagePolicy = (
   );
 };
 
+/**
+ * The advertised Ask AI URL. An external endpoint is not served under
+ * `deployment.base`, so a root-relative one absolutizes against the site
+ * origin alone; the built-in route gets site and base via `abs`.
+ */
+const askApiUrl = (
+  endpoint: string | undefined,
+  site: string | null,
+  abs: (path: string) => string
+): string => {
+  if (!endpoint) {
+    return abs("/api/ask");
+  }
+  return site && endpoint.startsWith("/")
+    ? `${site.replace(/\/+$/u, "")}${endpoint}`
+    : endpoint;
+};
+
 /**
  * Build `agent-readability.json`: a root manifest that indexes the project's
  * agent-facing surface — llms.txt, the raw-Markdown mirrors, the MCP server,
@@ -69,7 +87,7 @@ export const buildAgentReadability = (
     };
   }
   if (config.ai.ask?.enabled) {
-    artifacts.askApi = abs("/api/ask");
+    artifacts.askApi = askApiUrl(config.ai.ask.endpoint, site, abs);
   }
   if (site && config.seo.sitemap) {
     artifacts.sitemap = abs("/sitemap.xml");

package/src/ai/llms.ts

@@ -19,13 +19,18 @@ const pageUrl = (route: string, site?: string, base = ""): string => {
   return encodeURI(site ? `${site.replace(/\/$/u, "")}${path}` : path);
 };
 
-// Drafts, hidden, and `noindex` pages are excluded, matching the sitemap.
-// Generated API reference pages are excluded when `ai.llmsTxt.openapi` is off
-// (they arrive through the internal staged "openapi" source).
+// 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.
 const eligiblePages = (project: BlumeProject): PageRecord[] =>
   project.graph.pages.filter(
     (page) =>
-      !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex) &&
+      !(
+        page.meta.ai.exclude ||
+        page.meta.draft ||
+        page.meta.sidebar.hidden ||
+        (page.meta.seo.noindex && page.source.name !== "openapi")
+      ) &&
       (project.config.ai.llmsTxt.openapi || page.source.name !== "openapi")
   );
 

package/src/ai/mcp/server.ts

@@ -5,7 +5,7 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
-import { withBasePath } from "../../core/base-path.ts";
+import { stripBasePath, withBasePath } from "../../core/base-path.ts";
 import { buildOramaIndex, queryOramaIndex } from "../../search/orama-index.ts";
 import type { OramaDoc } from "../../search/orama-index.ts";
 import type { McpData } from "./data.ts";
@@ -81,12 +81,32 @@ const asLimit = (value: unknown): number => {
   return Math.min(Math.max(Math.trunc(num), 1), MAX_SEARCH_LIMIT);
 };
 
-/** Normalize a user-supplied route to a `pages` key (`/`, `/a/b`, no suffix). */
-const normalizeRoute = (input: string): string => {
-  const noTrailing = input.trim().replace(/\/+$/u, "");
+/**
+ * Normalize a user-supplied route to a `pages` key (`/`, `/a/b`, no suffix).
+ * Accepts a full URL too — `search_docs` hits and llms.txt entries carry
+ * `site` + `deployment.base`, and an agent following "pass a route from
+ * `search_docs`" will hand one straight back — reducing it to its base-less,
+ * percent-decoded path.
+ */
+const normalizeRoute = (input: string, data: McpData): string => {
+  let value = input.trim();
+  if (/^https?:\/\//iu.test(value)) {
+    try {
+      value = new URL(value).pathname;
+    } catch {
+      // Not parseable as a URL after all; treat it as a path.
+    }
+  }
+  try {
+    value = decodeURI(value);
+  } catch {
+    // Malformed percent sequence — compare it as written.
+  }
+  const noTrailing = value.replace(/\/+$/u, "");
   const noSuffix = noTrailing.replace(/\.mdx?$/u, "");
   const withSlash = noSuffix.startsWith("/") ? noSuffix : `/${noSuffix}`;
-  return withSlash === "" ? "/" : withSlash;
+  const based = stripBasePath(data.base, withSlash);
+  return based === "" ? "/" : based;
 };
 
 /** Build the absolute (or root-relative) URL for a route. */
@@ -114,10 +134,26 @@ const text = (value: string, isError = false) => ({
   ...(isError ? { isError: true } : {}),
 });
 
+/** Lazily builds the Orama index over a snapshot's documents, once. */
+export type OramaIndexProvider = () => Promise<
+  Awaited<ReturnType<typeof buildOramaIndex>>
+>;
+
+/** Memoize the search index so every server built from a snapshot shares it. */
+export const createIndexProvider = (
+  documents: OramaDoc[]
+): OramaIndexProvider => {
+  let dbPromise: ReturnType<OramaIndexProvider> | null = null;
+  return () => {
+    dbPromise ??= buildOramaIndex(documents);
+    return dbPromise;
+  };
+};
+
 /** Construct a fresh MCP server with Blume's read-only docs tools registered. */
-const buildServer = (
+export const buildServer = (
   data: McpData,
-  index: () => Promise<Awaited<ReturnType<typeof buildOramaIndex>>>
+  index: OramaIndexProvider
 ): Server => {
   const server = new Server(
     { name: data.name, version: data.version },
@@ -141,8 +177,11 @@ const buildServer = (
         asString(args.query),
         asLimit(args.limit)
       );
+      // `route` is the key `get_page` takes (the tool descriptions promise
+      // it); `url` is where the page is served.
       const results = hits.map((doc: OramaDoc) => ({
         excerpt: excerptFor(doc),
+        route: doc.route,
         title: doc.title,
         url: urlFor(doc.route, data),
       }));
@@ -150,7 +189,7 @@ const buildServer = (
     }
 
     if (name === "get_page") {
-      const key = normalizeRoute(asString(args.route));
+      const key = normalizeRoute(asString(args.route), data);
       const markdown = data.pages[key];
       if (markdown === undefined) {
         return text(
@@ -201,12 +240,7 @@ const buildServer = (
 export const createMcpFetchHandler = (
   data: McpData
 ): ((request: Request) => Promise<Response>) => {
-  let dbPromise: Promise<Awaited<ReturnType<typeof buildOramaIndex>>> | null =
-    null;
-  const index = () => {
-    dbPromise ??= buildOramaIndex(data.documents);
-    return dbPromise;
-  };
+  const index = createIndexProvider(data.documents);
 
   return async (request: Request): Promise<Response> => {
     if (request.method === "OPTIONS") {

package/src/ai/mcp/stdio.ts

@@ -0,0 +1,35 @@
+import { once } from "node:events";
+import type { Readable, Writable } from "node:stream";
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import type { McpData } from "./data.ts";
+import { buildServer, createIndexProvider } from "./server.ts";
+
+/** Streams for `serveMcpStdio`, injectable so tests can use in-memory pipes. */
+export interface McpStdioStreams {
+  stdin?: Readable;
+  stdout?: Writable;
+}
+
+/**
+ * Serve a precomputed MCP data snapshot over a stdio transport until the
+ * client hangs up.
+ *
+ * The SDK transport reads its input stream but never watches for its end, so
+ * a client that simply closes the pipe — which is how every MCP host shuts a
+ * stdio server down — would leave the process running forever. EOF on the
+ * input stream therefore ends the serve loop explicitly.
+ */
+export const serveMcpStdio = async (
+  data: McpData,
+  streams: McpStdioStreams = {}
+): Promise<void> => {
+  const stdin = streams.stdin ?? process.stdin;
+  const stdout = streams.stdout ?? process.stdout;
+  const transport = new StdioServerTransport(stdin, stdout);
+  const server = buildServer(data, createIndexProvider(data.documents));
+  await server.connect(transport);
+  await once(stdin, "end");
+  await transport.close();
+};