starlight-mcp
Give your Astro or Starlight docs site an MCP 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.
npm install starlight-mcp
Live demo: the discountkit docs serve theirs at https://discountkit.app/mcp —
claude mcp add --transport http discountkit-docs https://discountkit.app/mcp
How it works
- 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 yourllms.txt)
- Runtime — a dependency-free handler speaks stateless streamable HTTP: plain JSON-RPC over POST. It loads the corpus once per isolate and answers
initialize,tools/listandtools/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
// 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
// worker/index.ts
import { createStaticMcpWorker } from "starlight-mcp/cloudflare";
export default createStaticMcpWorker({
serverName: "my-docs",
siteLabel: "My Product",
docsRedirect: "/docs/ai-tools/",
});
// 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:
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
# Claude Code
claude mcp add --transport http my-docs https://your-site.com/mcp
// Cursor — .cursor/mcp.json
{
"mcpServers": {
"my-docs": { "url": "https://your-site.com/mcp" }
}
}
Clients that only speak stdio can bridge with mcp-remote:
{
"mcpServers": {
"my-docs": {
"command": "npx",
"args": ["mcp-remote", "https://your-site.com/mcp"]
}
}
}
Tools
Options
All options are optional.
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
docsRedirectat it so people who open/mcpin 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
.tsnatively. Plainnodewithout a bundler needs a transpile step (compiled dist is on the roadmap). - Protocol — implements stateless streamable HTTP for protocol versions
2025-06-18and2025-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.tsfor bundler-free Node consumers - Optional MiniSearch-backed index for large doc sets
extraToolsescape hatch for site-specific tools- Custom
cleanfunction for exotic MDX - Conformance tests against the official MCP SDK client
llms.txt/llms-full.txtgeneration from the same corpus
Prior art
- Varity's docs — the
/mcp-schema.json+ llms.txt recruiting pattern - mcpdoc — llms.txt-driven docs MCP as a local stdio server
- Built for (and proven on) the discountkit docs
License
MIT © bkspace
