@writedocs/generator 0.7.4 → 0.8.1

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,
@@ -106,7 +107,10 @@ const contentPublicDir = path.join(contentDir, 'public');
 // document-relative URLs isn't meaningful anyway.
 const siteUrl = resolveSiteUrl(docsConfig);
 if (!siteUrl) {
-  report('info', 'No "domain" set in writedocs.json, so no sitemap.xml was generated.');
+  report(
+    'info',
+    'No "domain" set in writedocs.json, so no sitemap.xml was generated, and llms.txt, the MCP server\'s page URLs and the "Open in…" links in the page menu use relative addresses or the address the page is opened from. Set "domain" to the site\'s address, like "docs.example.com".'
+  );
 }
 
 /** Recursively lists every .md/.mdx file under `baseDir` (Node 20's
@@ -309,6 +313,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/bin/writedocs.js

@@ -61,12 +61,14 @@ program
   .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
   .option('-p, --port <port>', 'port to run on')
   .option('--verbose', "also print Astro's and Vite's own output")
+  .option('--no-open', "don't open the preview in the browser")
   .action(async (dir, opts) => {
     await runDev({
       contentDir: path.resolve(process.cwd(), dir),
       packageRoot,
       port: opts.port,
       verbose: Boolean(opts.verbose),
+      open: opts.open,
     });
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "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/convert.js

@@ -96,6 +96,9 @@ export async function runConvert({ source = 'mintlify', contentDir, force = fals
   // before the first build.
   const checking = step('Checking pages');
   const content = await checkContent(contentDir, text);
+  // The domain reminder comes once, at the end, with where the source tool
+  // kept that setting.
+  content.warnings = content.warnings.filter((w) => w.code !== 'no-domain');
   checking.stop();
   if (content.errors.length) {
     log.line();

package/src/cli/dev.js

@@ -6,13 +6,14 @@ import { describeError, requestLog, authorWarning, verboseLine, stripAnsi } from
 import { reportApiPages } from './api-pages-output.js';
 import { runningPreview, writeLock, removeLock } from './dev-lock.js';
 import { showUpdateNotice } from './update-check.js';
+import { shouldOpenBrowser, openBrowser } from './open-browser.js';
 
 // The same problem tends to arrive more than once in a row - Vite and
 // Astro each log a failed page, and a page compiles for more than one
 // environment. Within this window, a repeat is dropped.
 const REPEAT_WINDOW_MS = 2000;
 
-export async function runDev({ contentDir, packageRoot, port, verbose = false }) {
+export async function runDev({ contentDir, packageRoot, port, verbose = false, open = true }) {
   const started = Date.now();
   preflightCheck(contentDir);
   writableInstallCheck(packageRoot);
@@ -36,6 +37,7 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
 
   const starting = step('Starting local preview');
   let ready = false;
+  let browserOpened = false;
 
   const lastShown = new Map();
   const once = (key, print) => {
@@ -102,6 +104,12 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
           // `dev` runs until Ctrl+C - the notice goes under the ready screen,
           // not after the command like everywhere else.
           showUpdateNotice();
+          // The preview in the browser, at the address it actually got - once,
+          // not again if Astro restarts the server.
+          if (!browserOpened && shouldOpenBrowser({ open })) {
+            browserOpened = true;
+            openBrowser(local ?? `http://localhost:${wanted}/`);
+          }
           return;
         }
         case 'fatal':

package/src/cli/open-browser.js

@@ -0,0 +1,32 @@
+// `writedocs dev` opens the preview in the default browser once it's ready.
+import { spawn } from 'node:child_process';
+
+/** Whether to open the browser: not with `--no-open`, not with BROWSER=none
+ *  (the convention Vite and create-react-app follow), and not where nobody's
+ *  watching - CI, or output that isn't an interactive terminal. */
+export function shouldOpenBrowser({ open = true, env = process.env, isTTY = Boolean(process.stdout.isTTY) } = {}) {
+  if (!open || !isTTY || env.CI) return false;
+  return String(env.BROWSER ?? '').toLowerCase() !== 'none';
+}
+
+/** The command that opens `url` in the default browser on `platform`. On
+ *  Windows, `start`'s first quoted argument is a window title - hence the
+ *  empty one, which Node passes as "". */
+export function openCommand(url, platform = process.platform) {
+  if (platform === 'win32') return ['cmd', ['/c', 'start', '', url]];
+  if (platform === 'darwin') return ['open', [url]];
+  return ['xdg-open', [url]];
+}
+
+/** Opens `url`, best effort: a machine with no browser (or no xdg-open)
+ *  just doesn't get one - the URL is printed anyway. */
+export function openBrowser(url, { platform = process.platform, run = spawn } = {}) {
+  const [command, args] = openCommand(url, platform);
+  try {
+    const child = run(command, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.on?.('error', () => {});
+    child.unref?.();
+  } catch {
+    // no browser to open - fine
+  }
+}

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/components/CopyPageMenu.astro

@@ -1,6 +1,7 @@
 ---
-// The "Copy page" split button - opt-in via writedocs.json's `contextMenu`
-// field (see contextMenuSchema in lib/config.ts). A primary button
+// The "Copy page" split button - on by default, showing the options
+// writedocs.json's `contextMenu` leaves on (`options`, from
+// contextMenuOptions() in lib/config-schema.ts). With `copy`, a primary button
 // (always-visible "Copy page" action, copies this page's Markdown
 // straight to the clipboard on click - see initCopyPageMenu() in
 // [...slug].astro) plus a small caret-only button next to it that opens
@@ -19,19 +20,21 @@
 // Rendered from [...slug].astro (see its own comment on where/when),
 // which passes in everything needed to build both same-origin links (the
 // .md route from [...slug].md.ts) and the external "Open in X" links
-// (which need an absolute URL - siteUrl is null on sites with no
-// writedocs.json `domain` set, in which case those three are left out
-// entirely rather than linking a service at a URL it could never fetch).
+// (which need an absolute URL - from writedocs.json's `domain` when it's
+// set, else from the page's own address in the browser; see
+// enabledAssistants below).
+// Without `copy`, the dropdown gets a labeled trigger of its own; with only
+// `copy`, the primary button stands alone.
 import { Icon } from 'astro-icon/components';
-import type { ContextMenuConfig } from '../lib/config';
+import type { ContextMenuOption } from '../lib/config';
 
 interface Props {
   currentPath: string; // e.g. "/" or "/guides/foo/" - see hrefForSlug() in [...slug].astro
   siteUrl: string | null;
-  contextMenu: ContextMenuConfig;
+  options: ContextMenuOption[];
 }
 
-const { currentPath, siteUrl, contextMenu } = Astro.props as Props;
+const { currentPath, siteUrl, options } = Astro.props as Props;
 
 // The [...slug].md.ts route this page is also served at - same
 // normalizeEntryId()-driven convention that file uses to build its own
@@ -50,33 +53,49 @@ const mdAbsoluteUrl = siteUrl ? `${siteUrl}${mdPath}` : null;
 // a bookmarked/shared link.
 const promptFor = (url: string) => `Read ${url} so you can answer questions about it.`;
 
+// `base` + the URL-encoded prompt is the link; `home` is where it goes
+// before the page script has filled the prompt in (see below).
 const assistants = [
-  { id: 'chatgpt' as const, label: 'ChatGPT', icon: 'simple-icons:openai', buildHref: (q: string) => `https://chatgpt.com/?q=${q}` },
-  { id: 'claude' as const, label: 'Claude', icon: 'simple-icons:claude', buildHref: (q: string) => `https://claude.ai/new?q=${q}` },
-  { id: 'perplexity' as const, label: 'Perplexity', icon: 'simple-icons:perplexity', buildHref: (q: string) => `https://www.perplexity.ai/search?q=${q}` },
+  { id: 'chatgpt' as const, label: 'ChatGPT', icon: 'simple-icons:openai', base: 'https://chatgpt.com/?q=', home: 'https://chatgpt.com/' },
+  { id: 'claude' as const, label: 'Claude', icon: 'simple-icons:claude', base: 'https://claude.ai/new?q=', home: 'https://claude.ai/new' },
+  { id: 'perplexity' as const, label: 'Perplexity', icon: 'simple-icons:perplexity', base: 'https://www.perplexity.ai/search?q=', home: 'https://www.perplexity.ai/' },
 ];
 
-// No siteUrl at all -> mdAbsoluteUrl is null -> none of these render,
-// regardless of what contextMenu.openIn lists: a link these services
-// could never actually fetch (a bare relative path, meaningless once
-// it's opened on a different origin) is worse than not offering it.
-const enabledAssistants = mdAbsoluteUrl
-  ? assistants.filter((a) => contextMenu.openIn.includes(a.id))
-  : [];
+// The assistant needs the page's absolute URL to fetch it. With a `domain`
+// it's known at build time and the link is complete in the HTML. Without
+// one, the page script (initCopyPageMenu() in [...slug].astro) completes it
+// from the address the page is actually served from - `data-ask-base` +
+// the prompt for that URL, the same prompt promptFor() writes.
+const enabledAssistants = assistants.filter((a) => options.includes(a.id));
+const assistantHref = (a: (typeof assistants)[number]) => (mdAbsoluteUrl ? a.base + encodeURIComponent(promptFor(mdAbsoluteUrl)) : a.home);
+const showCopy = options.includes('copy');
+const showView = options.includes('view');
+const hasDropdown = showView || enabledAssistants.length > 0;
 ---
+{(showCopy || hasDropdown) && (
 <div class="wd-copy-page-split">
-  <button type="button" class="wd-copy-page-primary" data-md-path={mdPath} aria-label="Copy page as Markdown">
-    <Icon name="lucide:copy" class="wd-copy-page-icon" />
-    <span class="wd-copy-page-primary-label">Copy page</span>
-  </button>
+  {showCopy && (
+    <button type="button" class:list={['wd-copy-page-primary', { 'wd-copy-page-alone': !hasDropdown }]} data-md-path={mdPath} aria-label="Copy page as Markdown">
+      <Icon name="lucide:copy" class="wd-copy-page-icon" />
+      <span class="wd-copy-page-primary-label">Copy page</span>
+    </button>
+  )}
+  {hasDropdown && (
   <div class="wd-dropdown wd-copy-page">
-    <button type="button" class="wd-dropdown-trigger wd-copy-page-caret-trigger" aria-haspopup="true" aria-expanded="false" aria-label="More copy options">
+    <button type="button" class:list={['wd-dropdown-trigger', 'wd-copy-page-caret-trigger', { 'wd-copy-page-labeled-trigger': !showCopy }]} aria-haspopup="true" aria-expanded="false" aria-label={showCopy ? 'More copy options' : 'Page options'}>
+      {!showCopy && (
+        <>
+          <Icon name="lucide:sparkles" class="wd-copy-page-icon" />
+          <span class="wd-copy-page-primary-label">Page options</span>
+        </>
+      )}
       <svg class="wd-dropdown-caret" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
         <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
       </svg>
     </button>
     <div class="wd-dropdown-menu wd-copy-page-menu" role="menu">
       <div class="wd-dropdown-menu-panel wd-copy-page-menu-panel">
+        {showView && (
         <a class="wd-copy-page-item" href={mdPath} target="_blank" rel="noopener">
           <Icon name="lucide:external-link" class="wd-copy-page-icon" />
           <span class="wd-copy-page-item-text">
@@ -84,8 +103,9 @@ const enabledAssistants = mdAbsoluteUrl
             <span class="wd-copy-page-item-desc">View this page as plain text</span>
           </span>
         </a>
+        )}
         {enabledAssistants.map((a) => (
-          <a class="wd-copy-page-item" href={a.buildHref(encodeURIComponent(promptFor(mdAbsoluteUrl!)))} target="_blank" rel="noopener">
+          <a class="wd-copy-page-item" href={assistantHref(a)} data-ask-base={mdAbsoluteUrl ? undefined : a.base} data-md-path={mdAbsoluteUrl ? undefined : mdPath} target="_blank" rel="noopener">
             <Icon name={a.icon} class="wd-copy-page-icon" />
             <span class="wd-copy-page-item-text">
               <span class="wd-copy-page-item-title">Open in {a.label}</span>
@@ -96,7 +116,9 @@ const enabledAssistants = mdAbsoluteUrl
       </div>
     </div>
   </div>
+  )}
 </div>
+)}
 
 <style>
   /* The split button: a primary "Copy page" action (always visible,
@@ -174,6 +196,20 @@ const enabledAssistants = mdAbsoluteUrl
     border-left: 1px solid var(--wd-border);
     border-radius: 0 0.35rem 0.35rem 0;
   }
+  /* Only one of the two halves: it gets all four corners (and, for the
+     trigger, no divider line and a label like the primary button's). */
+  .wd-copy-page-primary.wd-copy-page-alone {
+    border-radius: 0.35rem;
+  }
+  .wd-copy-page-caret-trigger.wd-copy-page-labeled-trigger {
+    gap: 0.35rem;
+    padding: 0.35rem 0.65rem;
+    border-left: none;
+    border-radius: 0.35rem;
+    color: var(--wd-text-muted);
+    font-size: 0.85rem;
+    font-weight: 500;
+  }
   .wd-copy-page-menu {
     left: auto;
     right: 0;

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

@@ -390,9 +390,26 @@ const apiSchema = z.object({
   // site can set this to `false` to never involve a third party.
   proxy: z.boolean().default(true)
 }).strict().default({ proxy: true });
-const contextMenuSchema = z.object({
-  openIn: z.array(z.enum(["chatgpt", "claude", "perplexity"])).default(["chatgpt", "claude", "perplexity"])
-}).strict();
+const CONTEXT_MENU_OPTIONS = ["copy", "view", "chatgpt", "claude", "perplexity"];
+const ASSISTANT_OPTIONS = ["chatgpt", "claude", "perplexity"];
+const contextMenuSchema = z.union([
+  z.boolean(),
+  z.array(z.enum(CONTEXT_MENU_OPTIONS)),
+  z.object({
+    openIn: z.array(z.enum(ASSISTANT_OPTIONS)).optional()
+  }).strict()
+]);
+function contextMenuOptions(value) {
+  if (value === false) return [];
+  if (value === void 0 || value === null || value === true) return [...CONTEXT_MENU_OPTIONS];
+  if (Array.isArray(value)) return CONTEXT_MENU_OPTIONS.filter((option) => value.includes(option));
+  if (typeof value === "object") {
+    const openIn = value.openIn;
+    const assistants = Array.isArray(openIn) ? openIn : [...ASSISTANT_OPTIONS];
+    return CONTEXT_MENU_OPTIONS.filter((option) => option === "copy" || option === "view" || assistants.includes(option));
+  }
+  return [];
+}
 const redirectSchema = z.object({
   source: z.string(),
   destination: z.string()
@@ -519,9 +536,14 @@ const docsConfigSchema = z.object({
   // field by field via mergeSeo(), rather than needing to repeat every
   // field on every page.
   seo: seoFieldsSchema.default({}),
-  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
-  // default (no menu, no .md routes).
+  // The "Copy page" menu - see contextMenuSchema above. Absent means on,
+  // with every option; read it through contextMenuOptions().
   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([]),
@@ -824,7 +846,9 @@ function validateDocsConfig(rawText) {
   return { ok: true, data: result.data, issues: [] };
 }
 export {
+  CONTEXT_MENU_OPTIONS,
   ROOT_ALLOWED_EXTRA_KEYS,
+  contextMenuOptions,
   createJsonLocator,
   docsConfigSchema,
   formatValidationIssues,

package/src/lib/config-schema.ts

@@ -727,25 +727,50 @@ const apiSchema = z
   .strict()
   .default({ proxy: true });
 
-// The "Copy page" dropdown shown next to a page's title - copy the raw
-// Markdown to the clipboard, open the raw Markdown in a new tab, or
-// deep-link into an AI assistant with a prompt pointing at it. Opt-in:
-// undefined (the field simply absent from writedocs.json) means the feature
-// is off entirely - no menu rendered, no .md routes generated at build
-// time either (see [...slug].md.ts) - rather than defaulting to on,
-// since it changes both the UI and the build output. Once a site does
-// write a `contextMenu` key (even `{}`), copying/viewing-as-Markdown are
-// always included (they need nothing but the page's own content); only
-// `openIn` (the AI-assistant deep-links, which need an absolute URL to
-// point the assistant at) is independently configurable.
-const contextMenuSchema = z
-  .object({
-    openIn: z.array(z.enum(['chatgpt', 'claude', 'perplexity'])).default(['chatgpt', 'claude', 'perplexity']),
-  })
-  .strict();
+// The "Copy page" menu shown next to a page's title - copy the page's
+// Markdown, view it, or open it in an AI assistant - and the .md copy of
+// every page it relies on ([...slug].md.ts). On by default, with every
+// option, like the MCP server. writedocs.json narrows or turns it off:
+//
+//   (absent) or true         every option
+//   ["copy", "claude"]       only these, in the menu's own order
+//   false (or [])            no menu, and no .md routes
+//   { "openIn": [...] }      the earlier form: copy and view, plus these
+//                            assistants - still accepted
+//
+// Read it through contextMenuOptions() below - never test the raw value for
+// truthiness: absent now means on.
+export const CONTEXT_MENU_OPTIONS = ['copy', 'view', 'chatgpt', 'claude', 'perplexity'] as const;
+export type ContextMenuOption = (typeof CONTEXT_MENU_OPTIONS)[number];
+const ASSISTANT_OPTIONS = ['chatgpt', 'claude', 'perplexity'] as const;
+
+const contextMenuSchema = z.union([
+  z.boolean(),
+  z.array(z.enum(CONTEXT_MENU_OPTIONS)),
+  z
+    .object({
+      openIn: z.array(z.enum(ASSISTANT_OPTIONS)).optional(),
+    })
+    .strict(),
+]);
 
 export type ContextMenuConfig = z.infer<typeof contextMenuSchema>;
 
+/** The menu options a writedocs.json `contextMenu` value turns on, in menu
+ *  order - [] when the menu is off. Takes the raw value too (link-check.js
+ *  reads writedocs.json without the schema), so absent means every option. */
+export function contextMenuOptions(value: unknown): ContextMenuOption[] {
+  if (value === false) return [];
+  if (value === undefined || value === null || value === true) return [...CONTEXT_MENU_OPTIONS];
+  if (Array.isArray(value)) return CONTEXT_MENU_OPTIONS.filter((option) => value.includes(option));
+  if (typeof value === 'object') {
+    const openIn = (value as { openIn?: unknown }).openIn;
+    const assistants = Array.isArray(openIn) ? openIn : [...ASSISTANT_OPTIONS];
+    return CONTEXT_MENU_OPTIONS.filter((option) => option === 'copy' || option === 'view' || assistants.includes(option));
+  }
+  return [];
+}
+
 // One entry in writedocs.json's `redirects` array - wired almost directly into
 // Astro's own `redirects` config option (astro.config.mjs), which is what
 // actually generates the redirect pages. `permanent` is deliberately not
@@ -996,9 +1021,14 @@ export const docsConfigSchema = z.object({
   // field by field via mergeSeo(), rather than needing to repeat every
   // field on every page.
   seo: seoFieldsSchema.default({}),
-  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
-  // default (no menu, no .md routes).
+  // The "Copy page" menu - see contextMenuSchema above. Absent means on,
+  // with every option; read it through contextMenuOptions().
   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/content-check.js

@@ -434,6 +434,21 @@ export async function checkContent(contentDir, configText) {
       const { message, suggestion } = unknownIconMessage(icon);
       warnings.push(issue('writedocs.json', locate(jsonPath)?.line, message, suggestion));
     }
+    // No `domain`: the site builds, but everything that needs its full
+    // address goes without - flagged so it's a choice, not a surprise.
+    if (typeof config.domain !== 'string' || !config.domain.trim()) {
+      // `code` lets `writedocs convert` leave it out - it gives its own
+      // domain hint, with where the source tool kept that setting.
+      warnings.push({
+        code: 'no-domain',
+        ...issue(
+          'writedocs.json',
+          undefined,
+          'No "domain" set - there\'s no sitemap.xml, and llms.txt, the MCP server\'s page URLs and the "Open in…" links in the page menu use relative addresses or the address the page is opened from.',
+          'Set "domain" to the site\'s address, like "docs.example.com".'
+        ),
+      });
+    }
   }
   await checkOpenApi(contentDir, config, config ? createJsonLocator(configText) : null, openapiRefs, errors, warnings);
 

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

@@ -164,8 +164,9 @@ export const DESCRIPTIONS = {
   'seo.twitterCard': 'X/Twitter card style. Default "summary_large_image" with an `ogImage`, "summary" without.',
   'seo.keywords': 'Keywords for the <meta name="keywords"> tag.',
   '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.',
+  contextMenu: 'The "Copy page" menu on every page - copy as Markdown, view as Markdown, open in ChatGPT, Claude or Perplexity - and a Markdown copy of each page at its address + ".md". On by default with every option. A list picks the options ("copy", "view", "chatgpt", "claude", "perplexity"); false turns it all off.',
+  'contextMenu.openIn': 'The earlier form: which AI assistants the menu offers, besides copy and view. A list of options replaces it.',
+  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/".',