@stellayazilim/mcp-starlight

Give any Astro Starlight docs site an MCP server.

No hosting. The integration writes a catalog into your build; the server runs on the reader's machine via npx and fetches it. A static host only ever has to answer GET for a JSON file — which is the one thing it does. GitHub Pages, S3 and plain nginx all work unchanged.

Locale- and version-aware, and extensible with structured data of your own.

Install

npm install @stellayazilim/mcp-starlight

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightMcp from '@stellayazilim/mcp-starlight';

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    starlight({ title: 'My Docs' }),
    starlightMcp({ siteLabel: 'My Product' }),
  ],
});

Build the site. You now have dist/mcp-catalog.json, published with everything else.

Related MCP server: mdbook-mcp-server

Use

Point any MCP client at the published catalog — or at the site root, and the filename is appended for you:

{
  "mcpServers": {
    "my-docs": {
      "command": "npx",
      "args": ["-y", "@stellayazilim/mcp-starlight", "https://example.com"]
    }
  }
}

Claude Code:

claude mcp add my-docs -- npx -y @stellayazilim/mcp-starlight https://example.com

While writing docs, point it at a local build instead:

npx @stellayazilim/mcp-starlight ./dist/mcp-catalog.json

Tools

search_docs and list_docs take locale and version when your site has them, so an answer can be scoped to one language or one documentation line.

Options

starlightMcp({
  siteLabel: 'My Product',        // shown in tool descriptions
  versions: ['preview', 'v1'],    // route segments that denote a docs line
  exclude: ['api'],               // content directories to leave out
  filename: 'mcp-catalog.json',   // output name inside the build
  collections: { … },             // structured data — object or function
  revision: process.env.GITHUB_SHA, // identifies this build of the catalog
})

versions turns a path segment into a facet. With versions: ['preview'], /preview/guides/x is tagged preview and /guides/x is the default line, so a reader can ask about one without the other bleeding in.

exclude matches path prefixes after the locale and version segments are stripped, so exclude: ['api'] covers api/, tr/api/, preview/api/ and tr/preview/api/ in one entry instead of four.

locales need no configuration — they are read from the Astro i18n config that Starlight generates.

revision identifies this build of the catalog. Pass the commit it came from — process.env.GITHUB_SHA in Actions — and a served catalog is traceable to a source revision. Left unset it defaults to a hash of the catalog's contents, which changes only when the content does. Either way it drives staleness detection, below.

Staying current

Docs sites redeploy; long-lived MCP clients do not restart. A server that read its catalog once at startup will keep answering from it for days, and nothing in its replies says so — which is the kind of wrong that is worth preventing rather than documenting.

Each build writes a small sentinel beside the catalog:

/mcp-catalog.json           the catalog
/mcp-catalog.version.json   { "schema": 1, "revision": "…", "generatedAt": "…" }

Before answering a tool call the server compares the published revision against the one it loaded, and re-fetches the catalog only when they differ. The check costs one request of a few dozen bytes; the catalog itself — which for a documented API surface runs to hundreds of kilobytes — is pulled only when it actually changed.

The checks are throttled and opportunistic: at most one per minute, and only while tool calls are arriving, so an idle server makes no requests at all. Set MCP_STARLIGHT_TTL_MS to change the interval, or 0 to check on every call.

Failure is deliberately quiet. A sentinel that is missing (an older site) or unreachable (a blip) leaves the loaded catalog in place — being possibly one revision behind beats answering with an error.

One limit worth knowing: tool schemas are fixed when the client connects, because MCP clients cache the tool list. A refresh updates every answer, but a site that adds a whole new locale or documentation line mid-session needs a client restart before that facet appears as a filter.

Structured collections

Prose search cannot answer "what is the exact signature of this type". If your build already produces that information — a generated API surface, a schema, a changelog — hand it over and it becomes searchable alongside the pages:

starlightMcp({
  collections: () => ({
    api: {
      label: '.NET API reference',
      entries: types.map((t) => ({
        id: t.uid,
        title: t.name,
        signature: t.declaration,
        summary: t.summary,
        route: t.docPath,
      })),
    },
  }),
})

Entries need id and title; signature, summary, detail and route are used when present. The integration knows nothing about where they came from — it publishes them, and search_reference appears.

Pass a function when the data is produced by another build step, so it is read at build time rather than when the config is loaded.

Why not the Pagefind index?

Starlight already builds one, and reusing it is a fair instinct. It is the wrong shape: Pagefind indexes rendered pages for browser-side search and ships a WASM runtime that returns HTML excerpts. This catalog is Markdown with frontmatter intact, plus whatever structured data you added — which is what a model can actually use, and what makes locale and version filtering possible.

Why a process at all?

MCP is JSON-RPC. A client POSTs a body and expects an answer computed from it; a static host returns the same bytes for every request and rejects POST outright. So something must run — but it does not have to be hosted. Here it runs where the reader is:

your static host                  the reader's machine
────────────────                  ────────────────────
mcp-catalog.json   ──GET──►       npx …mcp-starlight   ──stdio──►   Claude, Cursor, …

License

MIT