@writedocs/generator 0.7.4 → 0.8.0

package/astro.config.mjs

@@ -36,6 +36,7 @@ import { remarkUnknownComponentFallback } from './src/lib/mdx-unknown-components
 import { remarkExtractInlineReactComponents } from './src/lib/mdx-inline-react.js';
 import { writedocsTempDir, writedocsBuildStagingDir } from './src/lib/writedocs-temp-dir.js';
 import { stylesAssetFallback } from './src/lib/styles-asset-integration.js';
+import { mcpDevServer } from './src/lib/mcp-dev-integration.js';
 import { report } from './src/lib/cli-report.js';
 import {
   loadDocsConfig,
@@ -309,6 +310,9 @@ export default defineConfig({
     // field list and styles-asset-integration.js for how it's actually
     // served/copied.
     stylesAssetFallback(contentDir),
+    // /mcp in `writedocs dev`, as the build's dist/_worker.js serves it -
+    // see src/lib/mcp-dev-integration.js.
+    mcpDevServer({ version: JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8')).version }),
   ],
   output: 'static',
   // Dual Shiki themes for fenced code blocks (```) in MDX content, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "exports": {
     "./components": "./src/components/index.ts",
     "./config-schema": "./src/lib/config-schema.js",
-    "./writedocs.schema.json": "./writedocs.schema.json"
+    "./writedocs.schema.json": "./writedocs.schema.json",
+    "./mcp": "./src/mcp/server.js"
   },
   "files": [
     "bin",

package/src/cli/build.js

@@ -5,6 +5,7 @@ import { runPagefind } from './run-pagefind.js';
 import { preflightCheck, sameDriveCheck, writableInstallCheck } from './preflight.js';
 import { generateApiPages } from './generate-api-pages.js';
 import { writeRedirectsFile } from './write-redirects-file.js';
+import { writeMcpFiles } from './write-mcp-files.js';
 import { writedocsBuildStagingDir } from '../lib/writedocs-temp-dir.js';
 import { log, step, plural, duration, displayPath, formatProblems, color, CliExit } from './output.js';
 import { describeError, builtRoute, authorWarning, verboseLine } from './astro-output.js';
@@ -112,6 +113,13 @@ export async function runBuild({ contentDir, packageRoot, verbose = false }) {
   // - this turns those into real instant edge redirects on hosts that read
   // a `_redirects` file (Cloudflare Pages, Netlify), purely additively.
   writeRedirectsFile(distDir, contentDir);
+  // The site's MCP server at /mcp: mcp-index.json is already in dist/ (an
+  // Astro route); this adds the Cloudflare _worker.js that serves it - see
+  // write-mcp-files.js for every host.
+  const { version: writedocsVersion } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+  const mcp = writeMcpFiles(distDir, contentDir, writedocsVersion);
+  if (mcp.written.length) notes.push('MCP server at /mcp - dist/_worker.js runs it on Cloudflare; mcp-index.json holds the pages.');
+  if (mcp.skipped) addWarning(null, `No _worker.js for the MCP server: ${mcp.skipped}.`);
 
   const indexing = step('Indexing search');
   try {

package/src/cli/write-mcp-files.js

@@ -0,0 +1,96 @@
+// After `writedocs build`: the files that make dist/ serve the site's MCP
+// server at /mcp on Cloudflare, with no setup of the host's own - next to
+// mcp-index.json, which the build itself writes (src/pages/[mcpIndex].json.ts).
+//
+//   _worker.js     the MCP server (src/mcp/server.js, inlined - no imports)
+//                  plus a small fetch handler: /mcp goes to the server,
+//                  everything else to the static files (env.ASSETS).
+//                  - Cloudflare Pages runs it on its own ("advanced mode").
+//                  - Cloudflare Workers with static assets: point `main` at
+//                    dist/_worker.js, assets at dist/ with an ASSETS binding.
+//   _routes.json   Pages: only /mcp runs the worker; every other path stays a
+//                  plain static file (and `_redirects` keeps applying).
+//   .assetsignore  Workers: don't publish _worker.js / _routes.json as files.
+//
+// Anywhere else - Netlify, Vercel, the WriteDocs platform's serving Worker -
+// import handleMcpHttp from `@writedocs/generator/mcp` and give it
+// mcp-index.json; a purely static host (GitHub Pages, S3) can't run /mcp.
+//
+// A project that brings its own _worker.js or _routes.json (in public/), or a
+// Pages `functions/` folder (which Pages ignores once a _worker.js exists),
+// keeps them: the worker isn't written, and the build says so.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SERVER_SOURCE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'mcp', 'server.js');
+const IGNORED_BY_WORKERS = ['_worker.js', '_routes.json'];
+
+/** The `_worker.js` source: server.js without its `export`s, and the fetch
+ *  handler. `version` is the writedocs version, reported by the server. */
+export function mcpWorkerSource(version) {
+  const server = fs.readFileSync(SERVER_SOURCE, 'utf-8').replace(/^export (?=(?:const|let|async function|function) )/gm, '');
+  return `// Generated by writedocs ${version} - the site's MCP server at /mcp.
+// Cloudflare Pages runs this file on its own; on Cloudflare Workers, use it as
+// \`main\` with dist/ as the static assets (binding ASSETS). See
+// https://github.com/writedocs/writedocs (src/cli/write-mcp-files.js).
+
+${server}
+const WRITEDOCS_VERSION = ${JSON.stringify(version)};
+
+// The page index, read once per isolate from the site's own static files.
+let indexPromise = null;
+function loadIndex(request, env) {
+  if (!indexPromise) {
+    indexPromise = env.ASSETS.fetch(new URL('/mcp-index.json', request.url))
+      .then((res) => {
+        if (!res.ok) throw new Error('mcp-index.json: HTTP ' + res.status);
+        return res.json();
+      })
+      .catch((err) => {
+        indexPromise = null;
+        throw err;
+      });
+  }
+  return indexPromise;
+}
+
+export default {
+  async fetch(request, env) {
+    const { pathname } = new URL(request.url);
+    if (pathname === '/mcp' || pathname === '/mcp/') {
+      return handleMcpHttp(request, { loadIndex: () => loadIndex(request, env), version: WRITEDOCS_VERSION });
+    }
+    return env.ASSETS.fetch(request);
+  },
+};
+`;
+}
+
+/** Writes the files into `distDir`. Returns { written: [names], skipped:
+ *  reason or null } - nothing at all when there's no mcp-index.json
+ *  (writedocs.json `"mcp": false`). */
+export function writeMcpFiles(distDir, contentDir, version) {
+  if (!fs.existsSync(path.join(distDir, 'mcp-index.json'))) return { written: [], skipped: null };
+
+  const own = ['_worker.js', '_routes.json'].filter((name) => fs.existsSync(path.join(distDir, name)));
+  if (own.length) {
+    return { written: [], skipped: `the project has its own ${own.join(' and ')} - /mcp needs its handler added there (see @writedocs/generator/mcp)` };
+  }
+  if (fs.existsSync(path.join(contentDir, 'functions'))) {
+    return { written: [], skipped: 'the project has a Cloudflare Pages functions/ folder, which a _worker.js would switch off - add /mcp there with @writedocs/generator/mcp' };
+  }
+
+  fs.writeFileSync(path.join(distDir, '_worker.js'), mcpWorkerSource(version));
+  fs.writeFileSync(path.join(distDir, '_routes.json'), JSON.stringify({ version: 1, include: ['/mcp', '/mcp/'], exclude: [] }, null, 2) + '\n');
+
+  const ignorePath = path.join(distDir, '.assetsignore');
+  const existing = fs.existsSync(ignorePath) ? fs.readFileSync(ignorePath, 'utf-8') : '';
+  const lines = existing.split(/\r?\n/).map((l) => l.trim());
+  const missing = IGNORED_BY_WORKERS.filter((name) => !lines.includes(name));
+  if (missing.length) {
+    const prefix = existing && !existing.endsWith('\n') ? `${existing}\n` : existing;
+    fs.writeFileSync(ignorePath, `${prefix}${missing.join('\n')}\n`);
+  }
+  return { written: ['_worker.js', '_routes.json', '.assetsignore'], skipped: null };
+}

package/src/lib/agent-markdown.js

@@ -54,9 +54,11 @@ function mapOutsideInlineCode(text, transform) {
 }
 
 const PLACEHOLDER = /\[\[\s*([\w.-]+)\s*\]\]/g;
-// A standalone `{key}` expression - not an attribute value (`prop={key}`),
-// which the build leaves alone too.
-const MINTLIFY_PLACEHOLDER = /(?<!=\s*)\{\s*([A-Za-z_$][\w$]*)\s*\}/g;
+// A standalone `{key}` or `{{key}}` expression (Mintlify writes the latter;
+// MDX reads it as `{key}` inside an expression) - not an attribute value
+// (`prop={key}`), which the build leaves alone too. The double form first,
+// or its outer braces would be left around the value.
+const MINTLIFY_PLACEHOLDER = /(?<!=\s*)\{\s*\{\s*([A-Za-z_$][\w$]*)\s*\}\s*\}|(?<!=\s*)\{\s*([A-Za-z_$][\w$]*)\s*\}/g;
 
 /** writedocs.json `variables` - `[[key]]`, and Mintlify's `{key}` - replaced
  *  the way the build replaces them (lib/mdx-substitute-variables.js): outside
@@ -67,7 +69,10 @@ export function substituteVariables(text, variables) {
   return mapOutsideCode(text, (prose) =>
     prose
       .replace(PLACEHOLDER, (match, key) => (has(key) ? String(variables[key]) : match))
-      .replace(MINTLIFY_PLACEHOLDER, (match, key) => (has(key) ? String(variables[key]) : match))
+      .replace(MINTLIFY_PLACEHOLDER, (match, doubled, single) => {
+        const key = doubled ?? single;
+        return has(key) ? String(variables[key]) : match;
+      })
   );
 }
 

package/src/lib/config-schema.js

@@ -522,6 +522,11 @@ const docsConfigSchema = z.object({
   // The "Copy page" dropdown - see contextMenuSchema above. Absent by
   // default (no menu, no .md routes).
   contextMenu: contextMenuSchema.optional(),
+  // The site's MCP server - an AI tool connects to `/mcp` and searches and
+  // reads the docs. On by default: `writedocs build` writes the page index
+  // (mcp-index.json) and a Cloudflare-ready `_worker.js` into dist/ (see
+  // src/cli/write-mcp-files.js). `false` leaves all of it out.
+  mcp: z.boolean().default(true),
   // See redirectSchema above. Wired directly into Astro's own `redirects`
   // config option in astro.config.mjs.
   redirects: z.array(redirectSchema).default([]),

package/src/lib/config-schema.ts

@@ -999,6 +999,11 @@ export const docsConfigSchema = z.object({
   // The "Copy page" dropdown - see contextMenuSchema above. Absent by
   // default (no menu, no .md routes).
   contextMenu: contextMenuSchema.optional(),
+  // The site's MCP server - an AI tool connects to `/mcp` and searches and
+  // reads the docs. On by default: `writedocs build` writes the page index
+  // (mcp-index.json) and a Cloudflare-ready `_worker.js` into dist/ (see
+  // src/cli/write-mcp-files.js). `false` leaves all of it out.
+  mcp: z.boolean().default(true),
   // See redirectSchema above. Wired directly into Astro's own `redirects`
   // config option in astro.config.mjs.
   redirects: z.array(redirectSchema).default([]),

package/src/lib/json-schema-descriptions.js

@@ -166,6 +166,7 @@ export const DESCRIPTIONS = {
   'seo.noindex': 'Ask search engines not to index pages, and leave them out of sitemap.xml.',
   contextMenu: 'Adds a "Copy page" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + ".md".',
   'contextMenu.openIn': 'Which AI assistants the menu offers. Default: all three.',
+  mcp: 'An MCP server at /mcp, so AI tools can search and read the docs. The build adds its index and a Cloudflare-ready _worker.js to dist/. Default true; false leaves them out.',
   redirects: 'Redirects from old addresses. Each matches one exact path.',
   'redirects[].source': 'The old path, like "/old-page".',
   'redirects[].destination': 'Where to send it, like "/docs/new-page/".',

package/src/lib/mcp-dev-integration.js

@@ -0,0 +1,60 @@
+// `writedocs dev`: the site's MCP server at /mcp, as the build serves it - the
+// same handler (src/mcp/server.js), answering from the dev server's own
+// /mcp-index.json, so an edit shows up on the next request. Lets an author
+// point an MCP client at http://localhost:4321/mcp before deploying.
+import { handleMcpHttp } from '../mcp/server.js';
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+export function mcpDevServer({ version }) {
+  return {
+    name: 'writedocs-mcp-dev',
+    hooks: {
+      'astro:server:setup': ({ server }) => {
+        server.middlewares.use(async (req, res, next) => {
+          const pathname = (req.url ?? '').split('?')[0];
+          if (pathname !== '/mcp' && pathname !== '/mcp/') return next();
+          try {
+            const origin = `http://${req.headers.host}`;
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(req.headers)) {
+              if (typeof value === 'string') headers.set(key, value);
+            }
+            const body = req.method === 'POST' ? await readBody(req) : undefined;
+            const request = new Request(origin + req.url, { method: req.method, headers, body });
+            let missing = false;
+            const response = await handleMcpHttp(request, {
+              version,
+              loadIndex: async () => {
+                const index = await fetch(`${origin}/mcp-index.json`);
+                if (!index.ok) {
+                  missing = true;
+                  return { meta: {}, docs: [] };
+                }
+                return index.json();
+              },
+            });
+            if (missing) {
+              res.statusCode = 404;
+              res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+              res.end('No MCP server: writedocs.json has "mcp": false.');
+              return;
+            }
+            res.statusCode = response.status;
+            response.headers.forEach((value, key) => res.setHeader(key, value));
+            res.end(Buffer.from(await response.arrayBuffer()));
+          } catch (err) {
+            next(err);
+          }
+        });
+      },
+    },
+  };
+}

package/src/lib/mcp-index.ts

@@ -0,0 +1,101 @@
+// mcp-index.json - everything the site's MCP server (src/mcp/server.js)
+// answers from: every page an agent may read, as it should read it. Built
+// from the same pipeline as llms-full.txt (markdownForAgents(): snippets
+// inlined, `variables` filled in, <Visibility> for agents), in navigation
+// order, with each page's real URL and the version/language it sits under in
+// the navigation - what search_docs filters on.
+import { getCollection, type CollectionEntry } from 'astro:content';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  loadDocsConfig,
+  normalizeEntryId,
+  findAllPages,
+  resolveSiteUrl,
+  fileIdForEntry,
+  resolveSections,
+  flattenNav,
+} from './config';
+import { markdownForAgents } from './agent-markdown.js';
+import { orderByNavigation } from './llms.js';
+import { writedocsTempDir } from './writedocs-temp-dir.js';
+
+type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
+
+export interface McpDoc {
+  path: string;
+  url: string;
+  title: string;
+  description: string;
+  content: string;
+  version: string;
+  language: string;
+}
+
+export interface McpIndex {
+  meta: { name: string; description: string; siteUrl: string; generator: 'writedocs' };
+  docs: McpDoc[];
+}
+
+export async function mcpIndex(): Promise<McpIndex> {
+  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+  const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT || process.cwd();
+  const config = loadDocsConfig(contentDir);
+  const siteUrl = resolveSiteUrl(config) ?? '';
+
+  const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
+  const hasPages = findAllPages(contentDir).length > 0;
+  const [pagesEntries, generatedDocsEntries] = await Promise.all([
+    hasPages ? getCollection('pages') : Promise.resolve([]),
+    hasGeneratedDocs ? getCollection('generatedDocs') : Promise.resolve([]),
+  ]);
+  const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
+
+  // The version and language each page sits under, from its section's path
+  // through the navigation (tabs > versions > languages > ...).
+  const sections = resolveSections(config.navigation);
+  const placeOf = (fileId: string) => {
+    const section = sections.find((s) => flattenNav(s.pages).some((e) => e.slug === fileId));
+    const place = { version: '', language: '' };
+    for (const segment of section?.path ?? []) {
+      const item = segment.items[segment.index] as { version?: string; language?: string };
+      if (segment.kind === 'version' && item.version) place.version = item.version;
+      if (segment.kind === 'language' && item.language) place.language = item.language;
+    }
+    return place;
+  };
+
+  const docs = entries
+    // Same pages llms.txt lists: not `noindex`, not a frontmatter `url`
+    // (an external link, with no content of its own).
+    .filter((entry) => !entry.data.seo?.noindex && !entry.data.url)
+    .map((entry) => {
+      const slug = normalizeEntryId(entry.id);
+      const fileId = fileIdForEntry(contentDir, packageRoot, entry);
+      let content = markdownForAgents(entry.body ?? '', {
+        file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
+        contentDir,
+        variables: config.variables,
+      }).trim();
+      // An OpenAPI operation page renders from the spec, so its source body
+      // is near-empty - name the operation, at least.
+      if (entry.data.openapi) content = [`Operation: ${entry.data.openapi}`, content].filter(Boolean).join('\n\n');
+      return {
+        slug,
+        fileId,
+        doc: {
+          path: fileId,
+          url: `${siteUrl}${slug === 'index' ? '/' : `/${slug}/`}`,
+          title: entry.data.title,
+          description: entry.data.description ?? '',
+          content,
+          ...placeOf(fileId),
+        },
+      };
+    });
+
+  return {
+    meta: { name: config.name, description: config.description ?? '', siteUrl, generator: 'writedocs' },
+    docs: orderByNavigation(docs, config.navigation).map((d) => d.doc),
+  };
+}

package/src/mcp/server.js

@@ -0,0 +1,262 @@
+// The site's MCP server - lets an AI tool (Claude, Cursor, ...) list, search
+// and read the docs over the Model Context Protocol, at /mcp.
+//
+// Dependency-free and Web-standard (Request in, Response out), so the same
+// code runs wherever the site does: the Cloudflare `_worker.js` that
+// `writedocs build` writes into dist/ (src/cli/write-mcp-files.js - this file
+// is inlined into it), and any other host or serving Worker that imports
+// `@writedocs/generator/mcp` and calls handleMcpHttp() for /mcp. The docs
+// themselves come from the site's mcp-index.json (src/lib/mcp-index.ts),
+// which the build writes next to the pages.
+//
+// Streamable HTTP transport, JSON responses only (no server-sent events),
+// which every protocol version below allows. Keep this file free of imports:
+// the Cloudflare worker inlines its source as-is.
+
+// MCP protocol versions this server speaks, newest first.
+export const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+export const TOOLS = [
+  {
+    name: 'list_docs',
+    description: 'List every documentation page with its title, path, URL and description.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'get_doc',
+    description:
+      'Get the full content of one or more documentation pages, as Markdown. Pass a path or URL from list_docs or search_docs (the page URL works with or without its site address), or an array of them for a batch read.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          oneOf: [
+            { type: 'string', description: 'A page path or URL, e.g. "docs/quickstart" or "/docs/quickstart/"' },
+            { type: 'array', items: { type: 'string' }, description: 'Several page paths or URLs' },
+          ],
+        },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'search_docs',
+    description:
+      'Search the documentation by keywords, returning the best-matching pages with a snippet each. Follow up with get_doc to read a page in full.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search terms' },
+        limit: { type: 'number', description: 'Max results (default 5, max 20)' },
+        version: { type: 'string', description: 'Only pages of this docs version' },
+        language: { type: 'string', description: 'Only pages in this language' },
+      },
+      required: ['query'],
+    },
+  },
+];
+
+const CORS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization, Mcp-Protocol-Version, Mcp-Session-Id',
+};
+
+const json = (body, status = 200, headers = {}) =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json', ...CORS, ...headers } });
+
+/**
+ * Handles one HTTP request to /mcp. `loadIndex()` returns (or resolves to) the
+ * site's mcp-index.json, parsed; `version` is reported as the server's.
+ *
+ *   POST     JSON-RPC - one message or a batch
+ *   GET      an MCP client asking for an event stream (Accept:
+ *            text/event-stream) gets 405, as the spec says; anyone else (a
+ *            browser) gets a description of the server
+ *   OPTIONS  CORS preflight
+ */
+export async function handleMcpHttp(request, { loadIndex, version = '' } = {}) {
+  if (request.method === 'OPTIONS') return new Response(null, { status: 204, headers: CORS });
+  if (request.method === 'GET') {
+    if ((request.headers.get('accept') ?? '').includes('text/event-stream')) {
+      return new Response(null, { status: 405, headers: { Allow: 'POST, OPTIONS', ...CORS } });
+    }
+    const index = await loadIndex();
+    return json({
+      name: index.meta?.name ?? 'docs',
+      description: 'An MCP server for these docs. Connect an MCP client to this URL (Streamable HTTP).',
+      server: { name: 'writedocs', version },
+      protocolVersions: PROTOCOL_VERSIONS,
+      pages: index.docs?.length ?? 0,
+      tools: TOOLS.map((t) => ({ name: t.name, description: t.description })),
+    });
+  }
+  if (request.method !== 'POST') return new Response(null, { status: 405, headers: { Allow: 'GET, POST, OPTIONS', ...CORS } });
+
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }, 400);
+  }
+  const index = await loadIndex();
+  if (Array.isArray(body)) {
+    const responses = body.map((message) => handleMcpMessage(message, index, { version })).filter(Boolean);
+    return responses.length ? json(responses) : new Response(null, { status: 202, headers: CORS });
+  }
+  const response = handleMcpMessage(body, index, { version });
+  return response ? json(response) : new Response(null, { status: 202, headers: CORS });
+}
+
+/** One JSON-RPC message -> its response, or null for a notification. */
+export function handleMcpMessage(message, index, { version = '' } = {}) {
+  if (!message || typeof message !== 'object') {
+    return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid request' } };
+  }
+  const id = message.id ?? null;
+  if (message.id === undefined && String(message.method ?? '').startsWith('notifications/')) return null;
+
+  switch (message.method) {
+    case 'initialize': {
+      // The client's version when this server speaks it, else the newest one
+      // it does - the client then decides whether it can go on.
+      const requested = message.params?.protocolVersion;
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: {} },
+          serverInfo: { name: 'writedocs', title: index.meta?.name, version },
+          instructions: index.meta?.name
+            ? `Documentation for ${index.meta.name}. Use search_docs to find pages, get_doc to read them.`
+            : undefined,
+        },
+      };
+    }
+    case 'ping':
+      return { jsonrpc: '2.0', id, result: {} };
+    case 'tools/list':
+      return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+    case 'tools/call': {
+      const { name, arguments: args = {} } = message.params ?? {};
+      return { jsonrpc: '2.0', id, result: callTool(name, args ?? {}, index) };
+    }
+    default:
+      return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${message.method}` } };
+  }
+}
+
+const text = (value, isError = false) => ({ content: [{ type: 'text', text: value }], ...(isError ? { isError: true } : {}) });
+
+function callTool(name, args, index) {
+  const docs = index.docs ?? [];
+  switch (name) {
+    case 'list_docs': {
+      if (!docs.length) return text('This site has no pages.');
+      return text(
+        docs
+          .map((d) => {
+            let line = `${d.path}  -  ${d.title}  (${d.url})`;
+            if (d.description) line += `\n  ${d.description}`;
+            const meta = [d.version, d.language].filter(Boolean).join(', ');
+            if (meta) line += `\n  [${meta}]`;
+            return line;
+          })
+          .join('\n')
+      );
+    }
+
+    case 'get_doc': {
+      const paths = Array.isArray(args.path) ? args.path : [args.path];
+      const found = [];
+      const missing = [];
+      for (const p of paths) {
+        const doc = findDoc(docs, p);
+        if (!doc) {
+          missing.push(String(p ?? ''));
+          continue;
+        }
+        const parts = [`# ${doc.title}`, '', `URL: ${doc.url}`];
+        if (doc.description) parts.push('', `> ${doc.description}`);
+        parts.push('', doc.content);
+        found.push(parts.join('\n'));
+      }
+      const quoted = missing.map((p) => `"${p}"`).join(', ');
+      if (!found.length) return text(`No page found for ${quoted}. Use list_docs or search_docs to find page paths.`, true);
+      if (missing.length) found.push(`> No page found for ${quoted}.`);
+      return text(found.join('\n\n---\n\n'));
+    }
+
+    case 'search_docs': {
+      const query = String(args.query ?? '').trim();
+      if (!query) return text('The query is empty.', true);
+      // A limit that isn't a positive number (a model sent "abc", 0) falls
+      // back to the default instead of returning nothing.
+      const requested = Number(args.limit);
+      const limit = Number.isFinite(requested) && requested >= 1 ? Math.min(Math.floor(requested), 20) : 5;
+      let pool = docs;
+      if (args.version) pool = pool.filter((d) => d.version === String(args.version));
+      if (args.language) pool = pool.filter((d) => d.language === String(args.language));
+      const results = search(pool, query).slice(0, limit);
+      if (!results.length) return text(`No pages match "${query}".`);
+      return text(
+        results
+          .map((d) => {
+            const meta = [d.version, d.language].filter(Boolean).join(', ');
+            return `**${d.title}** (\`${d.path}\`) ${d.url}${meta ? ` [${meta}]` : ''}\n${d.description || snippet(d.content, query)}`;
+          })
+          .join('\n\n')
+      );
+    }
+
+    default:
+      return text(`Unknown tool: ${name}`, true);
+  }
+}
+
+/** The page a path points at, however it's written: its path ("docs/setup"),
+ *  its URL with or without slashes, the full site URL, a ".md" address, or
+ *  "/" for the home page. */
+export function findDoc(docs, value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return undefined;
+  const exact = docs.find((d) => d.path === raw || d.url === raw);
+  if (exact) return exact;
+  const key = (s) => {
+    const p = String(s)
+      .replace(/^https?:\/\/[^/]+/i, '')
+      .replace(/[?#].*$/, '')
+      .replace(/\.mdx?$/i, '')
+      .replace(/^\/+|\/+$/g, '')
+      .replace(/(^|\/)index$/, '');
+    return p || 'index';
+  };
+  const wanted = key(raw);
+  return docs.find((d) => key(d.url) === wanted || key(d.path) === wanted);
+}
+
+/** Pages scored by how often the query's words occur - title matches count
+ *  most - best first. */
+function search(docs, query) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const count = (haystack, word) => haystack.split(word).length - 1;
+  return docs
+    .map((doc) => {
+      const title = doc.title.toLowerCase();
+      const body = `${doc.description ?? ''} ${doc.content}`.toLowerCase();
+      const score = words.reduce((s, w) => s + count(title, w) * 5 + count(body, w), 0);
+      return { doc, score };
+    })
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .map((r) => r.doc);
+}
+
+function snippet(content, query) {
+  const word = query.toLowerCase().split(/\s+/)[0];
+  const at = content.toLowerCase().indexOf(word);
+  const start = Math.max(0, at - 60);
+  const end = Math.min(content.length, (at < 0 ? 0 : at) + 180);
+  return (start > 0 ? '...' : '') + content.slice(start, end).replace(/\s+/g, ' ').trim() + (end < content.length ? '...' : '');
+}

package/src/pages/[mcpIndex].json.ts

@@ -0,0 +1,16 @@
+import type { APIRoute } from 'astro';
+import { loadDocsConfig } from '../lib/config';
+import { mcpIndex } from '../lib/mcp-index';
+
+// /mcp-index.json - the pages the site's MCP server answers from (see
+// lib/mcp-index.ts and src/mcp/server.js). A dynamic route only so it can be
+// left out: writedocs.json `"mcp": false` gives no paths, so no file.
+export async function getStaticPaths() {
+  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+  return loadDocsConfig(contentDir).mcp ? [{ params: { mcpIndex: 'mcp-index' } }] : [];
+}
+
+export const GET: APIRoute = async () =>
+  new Response(JSON.stringify(await mcpIndex()), {
+    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+  });

package/writedocs.schema.json

@@ -772,6 +772,12 @@
       "description": "Adds a \"Copy page\" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + \".md\".",
       "markdownDescription": "Adds a \"Copy page\" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + \".md\"."
     },
+    "mcp": {
+      "default": true,
+      "type": "boolean",
+      "description": "An MCP server at /mcp, so AI tools can search and read the docs. The build adds its index and a Cloudflare-ready _worker.js to dist/. Default true; false leaves them out.",
+      "markdownDescription": "An MCP server at /mcp, so AI tools can search and read the docs. The build adds its index and a Cloudflare-ready _worker.js to dist/. Default true; false leaves them out."
+    },
     "redirects": {
       "default": [],
       "type": "array",