starlight-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bkspace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# starlight-mcp
+
+Give your [Astro](https://astro.build) or [Starlight](https://starlight.astro.build) docs site an [MCP](https://modelcontextprotocol.io) server.
+
+Agents connect to `https://your-site.com/mcp` and get three tools — `search_docs`, `get_doc`, `list_docs` — answered straight from your docs content collection. No database, no embeddings, no separate service: the corpus is a JSON file emitted at build time, and the server is a stateless JSON-RPC handler small enough to read in one sitting.
+
+```bash
+npm install starlight-mcp
+```
+
+**Live demo**: the discountkit docs serve theirs at `https://next.discountkit.app/mcp` —
+
+```bash
+claude mcp add --transport http discountkit-docs https://next.discountkit.app/mcp
+```
+
+## How it works
+
+1. **Build time** — the Astro integration injects two prerendered routes into your site:
+   - `/mcp/docs-index.json` — every page of your docs collection (title, description, URL, cleaned markdown body)
+   - `/mcp-schema.json` — a machine-readable tool catalog agents can discover before connecting (link it from your `llms.txt`)
+2. **Runtime** — a dependency-free handler speaks stateless [streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http): plain JSON-RPC over POST. It loads the corpus once per isolate and answers `initialize`, `tools/list` and `tools/call`. On SSR sites the integration injects this for you; on static sites you add one tiny shim on your host (Cloudflare recipe below).
+
+Because the transport is stateless HTTP, it works from Claude Code, Cursor, VS Code, Windsurf and anything else that speaks MCP — no SSE, no sessions, no sticky routing.
+
+## Quickstart
+
+### 1. Add the integration
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import starlightMcp from "starlight-mcp";
+
+export default defineConfig({
+  site: "https://your-site.com", // required — URLs in results are absolute
+  integrations: [
+    starlight({ title: "My Docs" }),
+    starlightMcp({
+      serverName: "my-docs",
+      siteLabel: "My Product",
+      docsRedirect: "/docs/ai-tools/", // where humans land if they open /mcp in a browser
+    }),
+  ],
+});
+```
+
+That's the whole setup for **SSR sites** (`output: "server"`): the live endpoint is injected at `/mcp`.
+
+For **static sites** the build emits the corpus and schema, and you serve the endpoint with a few lines of host glue:
+
+### 2. Static sites on Cloudflare Workers
+
+```ts
+// worker/index.ts
+import { createStaticMcpWorker } from "starlight-mcp/cloudflare";
+
+export default createStaticMcpWorker({
+  serverName: "my-docs",
+  siteLabel: "My Product",
+  docsRedirect: "/docs/ai-tools/",
+});
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "my-docs-site",
+  "main": "worker/index.ts",
+  "compatibility_date": "2025-06-01",
+  "assets": {
+    "directory": "./dist",
+    "binding": "ASSETS",
+    "run_worker_first": ["/mcp"] // script wakes up ONLY for /mcp
+  }
+}
+```
+
+Every other request is served from the static assets layer without invoking the Worker — you pay for script execution only on MCP traffic.
+
+### 3. Any other host
+
+`starlight-mcp/handler` is a pure `(Request) => Promise<Response>` with zero dependencies — wire it into whatever speaks fetch:
+
+```ts
+import { createMcpHandler } from "starlight-mcp/handler";
+
+const handler = createMcpHandler({
+  serverInfo: { name: "my-docs", version: "1.0.0" },
+  siteLabel: "My Product",
+  loadIndex: async () => {
+    // return DocEntry[] from wherever your build put docs-index.json
+    const res = await fetch("https://your-site.com/mcp/docs-index.json");
+    return res.json();
+  },
+});
+```
+
+## Connecting clients
+
+```bash
+# Claude Code
+claude mcp add --transport http my-docs https://your-site.com/mcp
+```
+
+```jsonc
+// Cursor — .cursor/mcp.json
+{
+  "mcpServers": {
+    "my-docs": { "url": "https://your-site.com/mcp" }
+  }
+}
+```
+
+Clients that only speak stdio can bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
+
+```jsonc
+{
+  "mcpServers": {
+    "my-docs": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://your-site.com/mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Arguments | Returns |
+| --- | --- | --- |
+| `search_docs` | `query` | Top 5 pages by weighted term match (title ×6, description ×3, body occurrences), each with URL, description and a snippet around the first hit |
+| `get_doc` | `path` (doc id or URL) | One full page as markdown with its source URL |
+| `list_docs` | — | Every page with title, description and URL |
+
+## Options
+
+All options are optional.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `serverName` | `<site-host>-docs` | MCP server name reported to clients |
+| `serverVersion` | `"0.1.0"` | Version reported to clients |
+| `path` | `"/mcp"` | Endpoint path; corpus lands at `${path}/docs-index.json`, catalog at `${path}-schema.json` |
+| `collection` | `"docs"` | Which content collection to index (Starlight's is `docs`) |
+| `siteLabel` | site host | Human-readable product name used in tool descriptions and `initialize` instructions |
+| `instructions` | generated | The `instructions` string agents see on connect |
+| `include` | all | Only index docs whose id starts with one of these prefixes |
+| `exclude` | none | Drop docs whose id starts with one of these prefixes |
+| `docsRedirect` | — | 302 humans who open the endpoint in a browser to this page (otherwise: a polite 405 JSON explainer) |
+| `toolDescriptions` | generated | Replace the description of any tool, e.g. `{ search_docs: "Search the Acme docs (billing, webhooks, SDKs)…" }` — worth hand-tuning so agents know when to reach for it |
+
+MDX noise (import statements, standalone `<Component>` tag lines) is stripped from indexed bodies automatically.
+
+## Make it discoverable
+
+Two cheap tricks that make agents actually find the server:
+
+- **llms.txt** — lead with the MCP endpoint before your page list, e.g.
+  ```
+  ## MCP server
+  Connect for structured search instead of scraping:
+  claude mcp add --transport http my-docs https://your-site.com/mcp
+  Tool catalog: https://your-site.com/mcp-schema.json
+  ```
+- **A docs page for humans** — an "AI tools" page with per-editor install snippets, and point `docsRedirect` at it so people who open `/mcp` in a browser land somewhere useful.
+
+## Notes
+
+- **Ships TypeScript source.** The package is consumed through bundlers — Astro/Vite, wrangler's esbuild, Bun, tsx — which all eat `.ts` natively. Plain `node` without a bundler needs a transpile step (compiled dist is on the roadmap).
+- **Protocol** — implements stateless streamable HTTP for protocol versions `2025-06-18` and `2025-03-26`: `initialize`, `ping`, `notifications/*` (202), `tools/list`, `tools/call`; CORS is open so browser-based clients work.
+- **State** — none. No sessions, no KV, no cookies. The corpus is cached per isolate/process and refreshes on deploy.
+
+## Roadmap
+
+- Compiled `dist/` + `.d.ts` for bundler-free Node consumers
+- Optional MiniSearch-backed index for large doc sets
+- `extraTools` escape hatch for site-specific tools
+- Custom `clean` function for exotic MDX
+- Conformance tests against the official MCP SDK client
+- `llms.txt` / `llms-full.txt` generation from the same corpus
+
+## Prior art
+
+- [Varity's docs](https://github.com/varity-labs/varity-docs) — the `/mcp-schema.json` + llms.txt recruiting pattern
+- [mcpdoc](https://github.com/langchain-ai/mcpdoc) — llms.txt-driven docs MCP as a local stdio server
+- Built for (and proven on) the [discountkit](https://next.discountkit.app) docs
+
+## License
+
+MIT © bkspace

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "starlight-mcp",
+  "version": "0.1.0",
+  "description": "Give your Astro or Starlight docs site an MCP server — search_docs, get_doc and list_docs over stateless streamable HTTP. Astro integration, pure fetch handler, and Cloudflare static-assets glue included.",
+  "type": "module",
+  "license": "MIT",
+  "author": "bkspace",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bkspace/starlight-mcp.git"
+  },
+  "homepage": "https://github.com/bkspace/starlight-mcp#readme",
+  "bugs": "https://github.com/bkspace/starlight-mcp/issues",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "withastro",
+    "starlight",
+    "starlight-plugin",
+    "mcp",
+    "model-context-protocol",
+    "documentation",
+    "llm",
+    "cloudflare-workers"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./handler": "./src/handler.ts",
+    "./cloudflare": "./src/cloudflare.ts",
+    "./routes/docs-index": "./src/routes/docs-index.ts",
+    "./routes/schema": "./src/routes/schema.ts",
+    "./routes/endpoint": "./src/routes/endpoint.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "vitest run",
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "astro": ">=4.14.0"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "astro": "^5.10.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  }
+}

package/src/clean.ts

@@ -0,0 +1,14 @@
+/**
+ * Strip the MDX noise agents shouldn't see: import statements and standalone
+ * JSX component tag lines (`<Tabs>`, `</CardGrid>`, …). Markdown prose,
+ * headings, code fences and inline HTML all survive.
+ */
+export function cleanMdxBody(body: string): string {
+  return body
+    .split("\n")
+    .filter((line) => !/^import\s.+from\s/.test(line.trim()))
+    .filter((line) => !/^<\/?[A-Z][\w]*(\s[^>]*)?>?\s*$/.test(line.trim()))
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}

package/src/cloudflare.ts

@@ -0,0 +1,79 @@
+/**
+ * Glue for static sites on Cloudflare Workers with static assets: the
+ * whole site stays on the assets layer, the script wakes up only for the
+ * MCP endpoint and reads the build-time corpus back through the ASSETS
+ * binding. Pair with `run_worker_first: ["/mcp"]` in wrangler.jsonc.
+ */
+import { createMcpHandler, type DocEntry } from "./handler";
+import type { ToolDescriptions } from "./tools";
+
+export interface StaticMcpWorkerOptions {
+  /** MCP server name reported to clients. Default: `"docs"`. */
+  serverName?: string;
+  /** Version string reported to clients. Default: `"0.1.0"`. */
+  serverVersion?: string;
+  /** Human-readable site name used inside tool descriptions. */
+  siteLabel?: string;
+  /** `instructions` string returned from `initialize`. */
+  instructions?: string;
+  /** Where to 302 humans who open the endpoint in a browser. */
+  docsRedirect?: string;
+  /** Replace the generated description of any tool. */
+  toolDescriptions?: ToolDescriptions;
+  /** Endpoint path — must match the integration's `path`. Default: `"/mcp"`. */
+  path?: string;
+}
+
+interface AssetsBinding {
+  fetch(input: URL | Request | string, init?: RequestInit): Promise<Response>;
+}
+
+export interface McpWorkerEnv {
+  ASSETS: AssetsBinding;
+}
+
+/**
+ * Returns a complete Worker export: `/mcp` (or `options.path`) is served by
+ * the MCP handler, everything else falls through to static assets.
+ *
+ * ```ts
+ * import { createStaticMcpWorker } from "starlight-mcp/cloudflare";
+ * export default createStaticMcpWorker({ serverName: "my-docs" });
+ * ```
+ */
+export function createStaticMcpWorker(options: StaticMcpWorkerOptions = {}) {
+  const path = options.path ?? "/mcp";
+  let corpus: DocEntry[] | null = null; // per-isolate cache
+
+  return {
+    async fetch(request: Request, env: McpWorkerEnv): Promise<Response> {
+      const { pathname, origin } = new URL(request.url);
+      if (pathname !== path && pathname !== `${path}/`)
+        return env.ASSETS.fetch(request);
+
+      const handler = createMcpHandler({
+        serverInfo: {
+          name: options.serverName ?? "docs",
+          version: options.serverVersion ?? "0.1.0",
+        },
+        siteLabel: options.siteLabel,
+        instructions: options.instructions,
+        docsRedirect: options.docsRedirect,
+        toolDescriptions: options.toolDescriptions,
+        loadIndex: async () => {
+          if (corpus) return corpus;
+          const res = await env.ASSETS.fetch(
+            new URL(`${path}/docs-index.json`, origin),
+          );
+          if (!res.ok)
+            throw new Error(
+              `${path}/docs-index.json missing (HTTP ${res.status}) — is the starlight-mcp integration in your astro config?`,
+            );
+          corpus = (await res.json()) as DocEntry[];
+          return corpus;
+        },
+      });
+      return handler(request);
+    },
+  };
+}

package/src/config.ts

@@ -0,0 +1,76 @@
+/**
+ * Options and normalization. The resolved config must stay JSON-serializable:
+ * it is inlined into a virtual module (`virtual:starlight-mcp/config`) and
+ * read back by the injected routes at build time.
+ */
+import type { ToolDescriptions } from "./tools";
+
+export interface StarlightMcpOptions {
+  /** MCP server name reported to clients. Default: derived from your site URL (`<host>-docs`). */
+  serverName?: string;
+  /** Version string reported to clients. Default: `"0.1.0"`. */
+  serverVersion?: string;
+  /**
+   * URL path of the MCP endpoint. The corpus is emitted at
+   * `${path}/docs-index.json` and the tool catalog at `${path}-schema.json`.
+   * Default: `"/mcp"`.
+   */
+  path?: string;
+  /** Content collection to index. Default: `"docs"` (Starlight's collection). */
+  collection?: string;
+  /** Human-readable site name used inside tool descriptions. Default: your site host, else `"this site"`. */
+  siteLabel?: string;
+  /** `instructions` string returned from `initialize`, shown to connecting agents. */
+  instructions?: string;
+  /** Only index docs whose id starts with one of these prefixes. */
+  include?: string[];
+  /** Drop docs whose id starts with one of these prefixes. Applied after `include`. */
+  exclude?: string[];
+  /**
+   * Where to 302 humans who open the endpoint in a browser
+   * (e.g. `"/docs/ai-tools/"`). Default: a plain 405 JSON explainer.
+   */
+  docsRedirect?: string;
+  /**
+   * Replace the generated description of any tool — worth hand-tuning:
+   * mention your product's actual topics so agents know when to search.
+   */
+  toolDescriptions?: ToolDescriptions;
+}
+
+export interface ResolvedMcpConfig {
+  serverName: string;
+  serverVersion: string;
+  path: string;
+  collection: string;
+  siteLabel: string;
+  instructions?: string;
+  include?: string[];
+  exclude?: string[];
+  docsRedirect?: string;
+  toolDescriptions?: ToolDescriptions;
+}
+
+export function normalizeOptions(
+  options: StarlightMcpOptions = {},
+  site?: string,
+): ResolvedMcpConfig {
+  const host = site ? new URL(site).hostname : undefined;
+  let path = options.path ?? "/mcp";
+  path = path.replace(/\/+$/, "");
+  if (!path.startsWith("/")) path = `/${path}`;
+  return {
+    serverName:
+      options.serverName ??
+      (host ? `${host.replace(/[^a-zA-Z0-9]+/g, "-")}-docs` : "docs"),
+    serverVersion: options.serverVersion ?? "0.1.0",
+    path,
+    collection: options.collection ?? "docs",
+    siteLabel: options.siteLabel ?? host ?? "this site",
+    instructions: options.instructions,
+    include: options.include,
+    exclude: options.exclude,
+    docsRedirect: options.docsRedirect,
+    toolDescriptions: options.toolDescriptions,
+  };
+}

package/src/corpus.ts

@@ -0,0 +1,30 @@
+/**
+ * Build the docs corpus from an Astro content collection. Only route
+ * modules may import this — `astro:content` exists solely inside an
+ * Astro build. The pure handler never touches it.
+ */
+import { getCollection } from "astro:content";
+import { cleanMdxBody } from "./clean";
+import type { ResolvedMcpConfig } from "./config";
+import type { DocEntry } from "./handler";
+
+export async function buildIndex(
+  config: ResolvedMcpConfig,
+  siteHref?: string,
+): Promise<DocEntry[]> {
+  const base = siteHref?.replace(/\/$/, "") ?? "";
+  const docs = await getCollection(config.collection);
+  const keep = (id: string) =>
+    (!config.include || config.include.some((p) => id.startsWith(p))) &&
+    !(config.exclude ?? []).some((p) => id.startsWith(p));
+  return docs
+    .filter((d) => keep(d.id))
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((d) => ({
+      path: d.id,
+      title: (d.data.title as string) ?? d.id,
+      description: (d.data.description as string) ?? "",
+      url: `${base}/${d.id}/`,
+      body: cleanMdxBody(d.body ?? ""),
+    }));
+}

package/src/env.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Ambient shims for this package's own typecheck only. Consumers never see
+ * these: inside an Astro project the real `astro:content` types and the
+ * injected virtual module take over.
+ */
+declare module "astro:content" {
+  export function getCollection(collection: string): Promise<
+    Array<{
+      id: string;
+      body?: string;
+      data: Record<string, unknown>;
+    }>
+  >;
+}
+
+declare module "virtual:starlight-mcp/config" {
+  const config: import("./config").ResolvedMcpConfig;
+  export default config;
+}

package/src/handler.ts

@@ -0,0 +1,184 @@
+/**
+ * The MCP server itself: a pure `(Request) => Promise<Response>` speaking
+ * stateless streamable HTTP — plain JSON-RPC over POST. No SDK, no
+ * sessions, no state, no dependencies. Runs on any WinterCG runtime
+ * (Cloudflare Workers, Deno, Bun, Node 18+, Vercel Edge, …).
+ */
+import { makeTools, type McpTool, type ToolDescriptions } from "./tools";
+
+export interface DocEntry {
+  /** Stable id, e.g. `docs/components/volume-picker` — what `get_doc` looks up. */
+  path: string;
+  title: string;
+  description: string;
+  /** Absolute URL of the page. */
+  url: string;
+  /** Cleaned markdown body. */
+  body: string;
+}
+
+export interface McpHandlerOptions {
+  serverInfo: { name: string; version: string };
+  /** Human-readable site name used inside tool descriptions. Default: `serverInfo.name`. */
+  siteLabel?: string;
+  /** `instructions` string returned from `initialize`. */
+  instructions?: string;
+  /** Where to 302 humans who open the endpoint in a browser. Default: 405 JSON explainer. */
+  docsRedirect?: string;
+  /** Replace the generated description of any tool. */
+  toolDescriptions?: ToolDescriptions;
+  /** Supply the corpus. Called on every tools/call — memoize inside if loading is expensive. */
+  loadIndex: () => Promise<DocEntry[]>;
+}
+
+export type McpRequestHandler = (request: Request) => Promise<Response>;
+
+const PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26"];
+
+const CORS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "POST, GET, OPTIONS, DELETE",
+  "Access-Control-Allow-Headers":
+    "content-type, mcp-session-id, mcp-protocol-version, authorization",
+};
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", ...CORS },
+  });
+
+const rpcResult = (id: unknown, result: unknown) =>
+  json({ jsonrpc: "2.0", id, result });
+const rpcError = (id: unknown, code: number, message: string) =>
+  json({ jsonrpc: "2.0", id, error: { code, message } });
+
+function snippet(body: string, query: string, radius = 180): string {
+  const i = body.toLowerCase().indexOf(query.toLowerCase());
+  if (i === -1) return body.slice(0, radius * 2).trim() + "…";
+  const start = Math.max(0, i - radius);
+  return (start > 0 ? "…" : "") + body.slice(start, i + radius).trim() + "…";
+}
+
+function searchDocs(index: DocEntry[], query: string): string {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const scored = index
+    .map((d) => {
+      const title = d.title.toLowerCase();
+      const desc = d.description.toLowerCase();
+      const body = d.body.toLowerCase();
+      let score = 0;
+      for (const t of terms) {
+        if (title.includes(t)) score += 6;
+        if (desc.includes(t)) score += 3;
+        const matches = body.split(t).length - 1;
+        score += Math.min(matches, 10);
+      }
+      return { d, score };
+    })
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 5);
+  if (!scored.length) return `No documentation pages matched "${query}".`;
+  return scored
+    .map(
+      ({ d }) =>
+        `## ${d.title}\n${d.url}\n${d.description}\n\n> ${snippet(d.body, terms[0] ?? query)}`,
+    )
+    .join("\n\n---\n\n");
+}
+
+function getDoc(index: DocEntry[], path: string): string {
+  const clean = path.replace(/^https?:\/\/[^/]+/, "").replace(/^\/|\/$/g, "");
+  const doc =
+    index.find((d) => d.path === clean) ??
+    index.find((d) => d.url.endsWith(`/${clean}/`)) ??
+    index.find((d) => d.path.endsWith(clean));
+  if (!doc)
+    return `No documentation page found for "${path}". Use list_docs or search_docs to find valid paths.`;
+  return `# ${doc.title}\n\nSource: ${doc.url}\n\n${doc.body}`;
+}
+
+function listDocs(index: DocEntry[]): string {
+  return index
+    .map(
+      (d) =>
+        `- ${d.title} — ${d.url}${d.description ? `\n  ${d.description}` : ""}`,
+    )
+    .join("\n");
+}
+
+export function createMcpHandler(options: McpHandlerOptions): McpRequestHandler {
+  const { serverInfo, loadIndex } = options;
+  const siteLabel = options.siteLabel ?? serverInfo.name;
+  const tools: McpTool[] = makeTools(siteLabel, options.toolDescriptions);
+  const instructions =
+    options.instructions ??
+    `Documentation server for ${siteLabel}. Use search_docs to find pages, get_doc to read one in full.`;
+
+  return async function handleMcp(request: Request): Promise<Response> {
+    if (request.method === "OPTIONS")
+      return new Response(null, { status: 204, headers: CORS });
+    if (request.method !== "POST") {
+      // a human in a browser: send them to the setup page instead of a 405
+      if (
+        options.docsRedirect &&
+        request.method === "GET" &&
+        (request.headers.get("accept") ?? "").includes("text/html")
+      ) {
+        return Response.redirect(
+          new URL(options.docsRedirect, request.url),
+          302,
+        );
+      }
+      return json(
+        { error: "This MCP server is stateless; POST JSON-RPC to this endpoint." },
+        405,
+      );
+    }
+
+    let msg: any;
+    try {
+      msg = await request.json();
+    } catch {
+      return rpcError(null, -32700, "Parse error");
+    }
+    const { id, method, params } = msg ?? {};
+
+    if (method === "initialize") {
+      const requested = params?.protocolVersion;
+      const version = PROTOCOL_VERSIONS.includes(requested)
+        ? requested
+        : PROTOCOL_VERSIONS[0];
+      return rpcResult(id, {
+        protocolVersion: version,
+        capabilities: { tools: {} },
+        serverInfo,
+        instructions,
+      });
+    }
+    if (String(method ?? "").startsWith("notifications/"))
+      return new Response(null, { status: 202, headers: CORS });
+    if (method === "ping") return rpcResult(id, {});
+    if (method === "tools/list") return rpcResult(id, { tools });
+
+    if (method === "tools/call") {
+      const name = params?.name;
+      const args = params?.arguments ?? {};
+      let index: DocEntry[];
+      try {
+        index = await loadIndex();
+      } catch (err) {
+        return rpcError(id, -32603, `Failed to load the docs corpus: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      let text: string;
+      if (name === "search_docs") text = searchDocs(index, String(args.query ?? ""));
+      else if (name === "get_doc") text = getDoc(index, String(args.path ?? ""));
+      else if (name === "list_docs") text = listDocs(index);
+      else return rpcError(id, -32602, `Unknown tool: ${name}`);
+      return rpcResult(id, { content: [{ type: "text", text }] });
+    }
+
+    return rpcError(id, -32601, `Method not found: ${method}`);
+  };
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+/**
+ * The Astro integration. Injects two build-time routes into any Astro or
+ * Starlight project:
+ *
+ *   `${path}/docs-index.json` — the docs corpus the MCP server answers from
+ *   `${path}-schema.json`    — the machine-readable tool catalog
+ *
+ * On server output it also injects the live MCP endpoint at `${path}`.
+ * On static output, pair the emitted corpus with a tiny host shim — see
+ * `starlight-mcp/cloudflare` or `starlight-mcp/handler`.
+ */
+import type { AstroIntegration } from "astro";
+import {
+  normalizeOptions,
+  type ResolvedMcpConfig,
+  type StarlightMcpOptions,
+} from "./config";
+
+const VIRTUAL_ID = "virtual:starlight-mcp/config";
+const RESOLVED_ID = "\0" + VIRTUAL_ID;
+
+export default function starlightMcp(
+  options: StarlightMcpOptions = {},
+): AstroIntegration {
+  return {
+    name: "starlight-mcp",
+    hooks: {
+      "astro:config:setup": ({ config, injectRoute, updateConfig, logger }) => {
+        const resolved = normalizeOptions(options, config.site);
+
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "starlight-mcp/config",
+                resolveId(id: string) {
+                  if (id === VIRTUAL_ID) return RESOLVED_ID;
+                },
+                load(id: string) {
+                  if (id === RESOLVED_ID)
+                    return `export default ${JSON.stringify(resolved)};`;
+                },
+              },
+            ],
+          },
+        });
+
+        injectRoute({
+          pattern: `${resolved.path}/docs-index.json`,
+          entrypoint: "starlight-mcp/routes/docs-index",
+          prerender: true,
+        });
+        injectRoute({
+          pattern: `${resolved.path}-schema.json`,
+          entrypoint: "starlight-mcp/routes/schema",
+          prerender: true,
+        });
+
+        if (config.output === "server") {
+          injectRoute({
+            pattern: resolved.path,
+            entrypoint: "starlight-mcp/routes/endpoint",
+            prerender: false,
+          });
+          logger.info(`live MCP endpoint at ${resolved.path}`);
+        } else {
+          logger.info(
+            `corpus at ${resolved.path}/docs-index.json — serve ${resolved.path} with starlight-mcp/cloudflare (or starlight-mcp/handler on any WinterCG host)`,
+          );
+        }
+      },
+    },
+  };
+}
+
+export { starlightMcp };
+export { normalizeOptions } from "./config";
+export type { StarlightMcpOptions, ResolvedMcpConfig } from "./config";
+export type { DocEntry, McpHandlerOptions, McpRequestHandler } from "./handler";
+export type { McpTool, ToolDescriptions } from "./tools";

package/src/routes/docs-index.ts

@@ -0,0 +1,16 @@
+/**
+ * `${path}/docs-index.json` — the documentation corpus, regenerated on
+ * every build from the content collection.
+ */
+import type { APIRoute } from "astro";
+import config from "virtual:starlight-mcp/config";
+import { buildIndex } from "../corpus";
+
+export const prerender = true;
+
+export const GET: APIRoute = async ({ site }) => {
+  const index = await buildIndex(config, site?.href);
+  return new Response(JSON.stringify(index), {
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+  });
+};

package/src/routes/endpoint.ts

@@ -0,0 +1,26 @@
+/**
+ * `${path}` — the live MCP endpoint, injected only on `output: "server"`.
+ * Static sites don't get this route; they serve the emitted corpus through
+ * a host shim instead (see starlight-mcp/cloudflare).
+ */
+import type { APIRoute } from "astro";
+import config from "virtual:starlight-mcp/config";
+import { buildIndex } from "../corpus";
+import { createMcpHandler, type McpRequestHandler } from "../handler";
+
+export const prerender = false;
+
+let handler: McpRequestHandler | null = null;
+let corpus: ReturnType<typeof buildIndex> | null = null;
+
+export const ALL: APIRoute = ({ request, site }) => {
+  handler ??= createMcpHandler({
+    serverInfo: { name: config.serverName, version: config.serverVersion },
+    siteLabel: config.siteLabel,
+    instructions: config.instructions,
+    docsRedirect: config.docsRedirect,
+    toolDescriptions: config.toolDescriptions,
+    loadIndex: () => (corpus ??= buildIndex(config, site?.href)),
+  });
+  return handler(request);
+};

package/src/routes/schema.ts

@@ -0,0 +1,28 @@
+/**
+ * `${path}-schema.json` — the MCP tool catalog as a machine-readable file
+ * (the Varity pattern), generated from the same definitions the server
+ * uses at runtime. Link it from llms.txt so agents can discover the
+ * endpoint without connecting first.
+ */
+import type { APIRoute } from "astro";
+import config from "virtual:starlight-mcp/config";
+import { makeTools } from "../tools";
+
+export const prerender = true;
+
+export const GET: APIRoute = ({ site }) => {
+  const base = site?.href.replace(/\/$/, "") ?? "";
+  return new Response(
+    JSON.stringify(
+      {
+        server: { name: config.serverName, version: config.serverVersion },
+        endpoint: `${base}${config.path}`,
+        transport: "streamable-http",
+        tools: makeTools(config.siteLabel, config.toolDescriptions),
+      },
+      null,
+      2,
+    ),
+    { headers: { "Content-Type": "application/json; charset=utf-8" } },
+  );
+};

package/src/tools.ts

@@ -0,0 +1,57 @@
+/**
+ * The MCP tool catalog — single source of truth, used by the runtime
+ * handler and by the published `${path}-schema.json` file.
+ */
+export interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export type ToolDescriptions = Partial<
+  Record<"search_docs" | "get_doc" | "list_docs", string>
+>;
+
+export function makeTools(
+  siteLabel: string,
+  overrides: ToolDescriptions = {},
+): McpTool[] {
+  return [
+    {
+      name: "search_docs",
+      description:
+        overrides.search_docs ??
+        `Search the ${siteLabel} documentation. Returns the best-matching pages with snippets and URLs.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "What to search for",
+          },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "get_doc",
+      description:
+        overrides.get_doc ??
+        "Fetch one documentation page as full markdown by its path (as returned by search_docs or list_docs).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "The doc path or URL" },
+        },
+        required: ["path"],
+      },
+    },
+    {
+      name: "list_docs",
+      description:
+        overrides.list_docs ??
+        "List every documentation page with its title, description and URL.",
+      inputSchema: { type: "object", properties: {} },
+    },
+  ];
+}