@writedocs/generator 0.7.4 → 0.8.1

package/src/lib/link-check.js

@@ -33,7 +33,7 @@ import { pathToFileURL } from 'node:url';
 import matter from 'gray-matter';
 import { visit } from 'unist-util-visit';
 import { findAllPages } from './pages.js';
-import { createJsonLocator } from './config-schema.js';
+import { createJsonLocator, contextMenuOptions } from './config-schema.js';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
 
 // The same github-slugger Astro builds page URLs and heading ids with -
@@ -423,7 +423,7 @@ export async function checkLinks(contentDir, configText) {
     // A link to a page's source file (docs/setup.mdx) instead of its URL.
     if (extension === '.mdx' || extension === '.md') {
       const bare = pathname.replace(/\.mdx?$/i, '').replace(/\/?$/, '/');
-      if (extension === '.md' && config.contextMenu && pages.has(bare)) return; // the page's Markdown copy
+      if (extension === '.md' && contextMenuOptions(config.contextMenu).length && pages.has(bare)) return; // the page's Markdown copy (on unless "contextMenu": false)
       // Written as a file path, so look it up as one: from the file's own
       // folder when relative.
       const filePath = isRelative && fileAbs ? path.resolve(path.dirname(fileAbs), decodeURI(value.split(/[?#]/)[0])) : path.join(contentDir, pathname);

package/src/lib/llms-index.ts

@@ -6,7 +6,7 @@
 import { getCollection, type CollectionEntry } from 'astro:content';
 import fs from 'node:fs';
 import path from 'node:path';
-import { loadDocsConfig, normalizeEntryId, findAllPages, resolveSiteUrl, fileIdForEntry } from './config';
+import { loadDocsConfig, normalizeEntryId, findAllPages, resolveSiteUrl, fileIdForEntry, contextMenuOptions } from './config';
 import { buildLlmsTree, renderLlmsFiles } from './llms.js';
 import { navigationPageOrder } from './pages.js';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
@@ -59,10 +59,10 @@ export async function llmsIndexFiles(): Promise<Map<string, string> | null> {
     // page (Mintlify's external link) has no content of its own.
     if (entry.data.seo?.noindex || entry.data.url) continue;
     const slug = normalizeEntryId(entry.id);
-    // The .md route when it exists ([...slug].md.ts - with `contextMenu`,
+    // The .md route when it exists ([...slug].md.ts - unless `contextMenu` is off,
     // and never for an OpenAPI page, which renders from the spec), else the
     // HTML page.
-    const hasMarkdownRoute = config.contextMenu && !entry.data.openapi;
+    const hasMarkdownRoute = contextMenuOptions(config.contextMenu).length > 0 && !entry.data.openapi;
     const href = (siteUrl ?? '') + (hasMarkdownRoute ? `/${slug}.md` : slug === 'index' ? '/' : `/${slug}/`);
     let description = truncateDescription(entry.data.description);
     // Mirrors Mintlify: an OpenAPI operation page's description gets its

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/lib/mintlify-convert.js

@@ -530,13 +530,16 @@ export function convertMintlifyConfig(docs) {
   if (docs.seo?.indexing === 'all') notes.add('seo.indexing', ['seo', 'indexing'], '`seo.indexing: "all"` has no equivalent - writedocs indexes every page that isn\'t marked noindex.');
 
   // context menu
+  // Mintlify's option names are writedocs' own for the five both have, so the
+  // list carries over as is. No `contextual` leaves the field out - the menu
+  // is on by default, with every option.
   const options = docs.contextual?.options;
   if (Array.isArray(options) && options.length) {
-    const openIn = options.filter((o) => ['chatgpt', 'claude', 'perplexity'].includes(o));
-    out.contextMenu = { openIn };
-    const other = options.filter((o) => typeof o !== 'string' || !['copy', 'view', 'chatgpt', 'claude', 'perplexity'].includes(o));
+    const known = ['copy', 'view', 'chatgpt', 'claude', 'perplexity'];
+    out.contextMenu = known.filter((o) => options.includes(o));
+    const other = options.filter((o) => typeof o !== 'string' || !known.includes(o));
     if (other.length) {
-      notes.add('contextual', ['contextual', 'options'], `Context menu options writedocs doesn't have were dropped: ${other.map((o) => (typeof o === 'string' ? o : o.title ?? 'custom')).join(', ')}.`, 'writedocs\' page menu always has copy and view-as-Markdown, plus open in ChatGPT, Claude and Perplexity.');
+      notes.add('contextual', ['contextual', 'options'], `Context menu options writedocs doesn't have were dropped: ${other.map((o) => (typeof o === 'string' ? o : o.title ?? 'custom')).join(', ')}.`, 'writedocs\' page menu offers copy, view as Markdown, and open in ChatGPT, Claude and Perplexity.');
     }
   }
 

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/[...slug].astro

@@ -16,6 +16,7 @@ import {
   flattenNav,
   firstSlugOfNavigation,
   mergeSeo,
+  contextMenuOptions,
   resolveSiteUrl,
   findAllPages,
 } from "../lib/config";
@@ -414,8 +415,9 @@ const showToc = pageMode === "default";
 // branch on separately.
 const isCanvasMode = pageMode === "custom" || pageMode === "blank";
 
-// The "Copy page" dropdown (CopyPageMenu.astro) - opt-in via writedocs.json's
-// `contextMenu` field (see contextMenuSchema in lib/config.ts), and only
+// The "Copy page" menu (CopyPageMenu.astro) - on by default, with the
+// options writedocs.json's `contextMenu` leaves on (contextMenuOptions() in
+// lib/config-schema.ts; `false` turns it off), and only
 // shown where there's a real auto-rendered <h1> to sit next to: canvas
 // mode pages (custom/blank) have no such header (a hand-built landing
 // page controls its own layout, there's nothing standard to anchor the
@@ -423,7 +425,8 @@ const isCanvasMode = pageMode === "custom" || pageMode === "blank";
 // spec rather than prose - see [...slug].md.ts's own comment on why
 // those are excluded from the .md route this menu links to in the first
 // place, which this mirrors on the UI side.
-const showCopyPageMenu = Boolean(config.contextMenu) && !isCanvasMode && !entry.data.openapi;
+const contextMenuItems = contextMenuOptions(config.contextMenu);
+const showCopyPageMenu = contextMenuItems.length > 0 && !isCanvasMode && !entry.data.openapi;
 const siteUrl = resolveSiteUrl(config);
 
 const components = {
@@ -513,7 +516,7 @@ const components = {
             )
           }
           {showCopyPageMenu && (
-            <CopyPageMenu currentPath={currentPath} siteUrl={siteUrl} contextMenu={config.contextMenu!} />
+            <CopyPageMenu currentPath={currentPath} siteUrl={siteUrl} options={contextMenuItems} />
           )}
         </div>
         <Content components={components} />
@@ -672,6 +675,19 @@ const components = {
   initCopyPageMenu(document);
   document.addEventListener("astro:page-load", () => initCopyPageMenu(document));
 
+  // "Open in ChatGPT/Claude/Perplexity" on a site with no writedocs.json
+  // `domain`: the page's absolute .md URL isn't known at build time, so the
+  // link is completed here from the address the page is served from (see
+  // CopyPageMenu.astro) - same prompt the build writes when it does know.
+  function initAskLinks(root: ParentNode) {
+    root.querySelectorAll<HTMLAnchorElement>("a[data-ask-base][data-md-path]").forEach((link) => {
+      const url = new URL(link.dataset.mdPath ?? "/", window.location.origin).href;
+      link.href = link.dataset.askBase + encodeURIComponent(`Read ${url} so you can answer questions about it.`);
+    });
+  }
+  initAskLinks(document);
+  document.addEventListener("astro:page-load", () => initAskLinks(document));
+
   // Show more/less toggle for ```js expandable code blocks - same
   // build-time-emitted-button + client-wired-click pattern as the copy
   // button above; codeBlockTransformer only adds this button when the
@@ -845,7 +861,7 @@ const components = {
     width: 100%;
   }
   /* Wraps the auto-rendered <h1> together with CopyPageMenu (only
-     rendered when writedocs.json's `contextMenu` is set - see
+     rendered when writedocs.json's `contextMenu` isn't off - see
      showCopyPageMenu above) so the two sit on one row, menu pinned to
      the right. Always present (even with no menu) rather than only
      wrapping the <h1> conditionally, so the <h1>'s own top/bottom

package/src/pages/[...slug].md.ts

@@ -2,7 +2,7 @@ import { getCollection, type CollectionEntry } from 'astro:content';
 import fs from 'node:fs';
 import path from 'node:path';
 import type { APIRoute } from 'astro';
-import { loadDocsConfig, normalizeEntryId, findAllPages } from '../lib/config';
+import { loadDocsConfig, normalizeEntryId, findAllPages, contextMenuOptions } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
 import { markdownForAgents } from '../lib/agent-markdown.js';
 
@@ -11,10 +11,10 @@ import { markdownForAgents } from '../lib/agent-markdown.js';
 // /guides/foo/ -> /guides/foo.md), serving its untouched MDX/Markdown
 // source instead of rendered HTML - what the "Copy page"/"View as
 // Markdown" menu (CopyPageMenu.astro, wired in from [...slug].astro)
-// links to, and what an LLM fetching that URL directly gets. Gated
-// entirely behind writedocs.json's `contextMenu` field being present (see
-// contextMenuSchema in lib/config.ts) - a site that hasn't opted in gets
-// no .md routes at all, not just a hidden menu.
+// links to, and what an LLM fetching that URL directly gets. On by
+// default, like the menu; writedocs.json `"contextMenu": false` (see
+// contextMenuOptions() in lib/config-schema.ts) leaves out the .md routes
+// too, not just the menu.
 //
 // A literal ".md" filename suffix rather than a `[...slug]` capture
 // covering it: naming the file `[...slug].md.ts` makes Astro treat ".md"
@@ -33,9 +33,9 @@ type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
 export async function getStaticPaths() {
   const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
   const config = loadDocsConfig(contentDir);
-  // No writedocs.json `contextMenu` - feature is off entirely, including these
-  // routes (not just the menu UI - see the file-level comment above).
-  if (!config.contextMenu) return [];
+  // `"contextMenu": false` - the feature is off entirely, these routes
+  // included (not just the menu UI - see the file-level comment above).
+  if (contextMenuOptions(config.contextMenu).length === 0) return [];
 
   const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
   const hasPages = findAllPages(contentDir).length > 0;

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' },
+  });