handoff-app 2.0.0-5 → 2.0.0-6

package/src/app/components/McpIntegration/McpConfigDialog.tsx

@@ -0,0 +1,349 @@
+'use client';
+
+import { ExternalLink } from 'lucide-react';
+import Link from 'next/link';
+import * as React from 'react';
+
+import { cn } from '../../lib/utils';
+import { useConfigContext } from '../context/ConfigContext';
+import CopyToClipboard from '../CopyToClipboard';
+import { RuntimeModeBadge } from '../Layout/RuntimeModeBadge';
+import { Button } from '../ui/button';
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger } from '../ui/dialog';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '../ui/tabs';
+import { McpIcon } from './McpIcon';
+
+/**
+ * How to point a coding agent at this app's `/api/mcp/` endpoint.
+ *
+ * Availability comes from values baked in at build time (the `env` block in `next.config.mjs`): a
+ * static export has no API routes, and `runtime.mcp: false` leaves the endpoint out of any build.
+ * Both mean there is nothing to offer, so this UI is gated on the same value the route is and a
+ * build without the endpoint shows no affordance rather than a status dot that reds out on a 404.
+ *
+ * Registry mode puts `/api/mcp/` behind a `registry:read` credential where a workspace leaves it
+ * open. Standalone and Vercel registries need no telling apart: both serve the endpoint from their
+ * own origin, which is where the URL comes from.
+ */
+const isAvailable = process.env.HANDOFF_MCP_ENABLED !== 'false' && process.env.HANDOFF_BUILD_TARGET !== 'static';
+const isRegistryRuntime = process.env.HANDOFF_RUNTIME_MODE === 'registry';
+
+/** Placeholder for the reader's own token. No real credential is ever rendered here. */
+const CREDENTIAL_HEADERS = { Authorization: 'Bearer <your-token>' };
+
+interface McpTarget {
+  url: string;
+  headers?: Record<string, string>;
+}
+
+/** One server entry, as a client config file carries it. */
+interface ServerEntry {
+  type?: 'http';
+  url: string;
+  headers?: Record<string, string>;
+}
+
+const httpEntry = ({ url, headers }: McpTarget): ServerEntry => ({ type: 'http', url, ...(headers ? { headers } : {}) });
+
+/** Cursor's remote form is `url` + `headers`; it uses `type` for local stdio servers only. */
+const urlEntry = ({ url, headers }: McpTarget): ServerEntry => ({ url, ...(headers ? { headers } : {}) });
+
+interface McpClient {
+  id: string;
+  name: string;
+  /** Where the client reads the config from. */
+  configPath: string;
+  /** How to reach the same config outside the project. */
+  note: string;
+  /** The whole config file, in the shape this client expects. */
+  file: (name: string, target: McpTarget) => Record<string, unknown>;
+  /** Equivalent command line, where the client has one. */
+  command?: (name: string, target: McpTarget) => string;
+  /** One-click install URL. Only offered when the endpoint needs no credential. */
+  deeplink?: (name: string, target: McpTarget) => string;
+}
+
+const CLIENTS: McpClient[] = [
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    configPath: '.mcp.json',
+    note: 'Shared with the project. `--scope user` instead adds it to every project on this machine.',
+    file: (name, target) => ({ mcpServers: { [name]: httpEntry(target) } }),
+    command: (name, target) =>
+      [
+        `claude mcp add --transport http ${name} ${target.url}`,
+        ...(target.headers ? [`  --header "Authorization: ${target.headers.Authorization}"`] : []),
+      ].join(' \\\n'),
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    configPath: '.cursor/mcp.json',
+    note: 'Project scope. `~/.cursor/mcp.json` instead makes it available in every project.',
+    file: (name, target) => ({ mcpServers: { [name]: urlEntry(target) } }),
+    deeplink: (name, target) =>
+      `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(name)}&config=${btoa(JSON.stringify(urlEntry(target)))}`,
+  },
+  {
+    id: 'vscode',
+    name: 'VS Code',
+    configPath: '.vscode/mcp.json',
+    note: 'Workspace scope. "MCP: Open User Configuration" instead makes it available everywhere.',
+    file: (name, target) => ({ servers: { [name]: httpEntry(target) } }),
+    deeplink: (name, target) => `vscode:mcp/install?${encodeURIComponent(JSON.stringify({ name, ...httpEntry(target) }))}`,
+  },
+];
+
+const slugify = (value: string): string =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+/**
+ * Name the server after the design system, and mark a registry one. A workspace endpoint serves
+ * local build output including unpublished work while a registry serves what was published to it,
+ * so both can end up in one config file and the keys must not collide.
+ */
+const useServerName = (): string => {
+  const client = useConfigContext().config?.app?.client;
+  return ['handoff', client ? slugify(client) : '', isRegistryRuntime ? 'registry' : ''].filter(Boolean).join('-');
+};
+
+/**
+ * The endpoint as the reader's own browser reached it, so host, port and base path are never guessed.
+ *
+ * The trailing slash matters: the app sets `trailingSlash: true`, so a POST to `/api/mcp` gets a 308
+ * to `/api/mcp/`. Clients that follow it pay two round trips per call and the ones that don't fail
+ * outright, so hand out the URL that answers directly.
+ */
+const useMcpEndpoint = (): string => {
+  const [url, setUrl] = React.useState('');
+  React.useEffect(() => {
+    setUrl(`${window.location.origin}${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/mcp/`);
+  }, []);
+  return url;
+};
+
+/** What a probe of the endpoint found. */
+type EndpointStatus = 'checking' | 'live' | 'unreachable';
+
+// One probe per hard load, cached at module level, so soft navigation does not re-ask and a refresh
+// does.
+let cachedStatus: EndpointStatus | null = null;
+let inFlight: Promise<EndpointStatus> | null = null;
+
+/**
+ * Statuses that prove the route is being served. A GET is the cheapest question to ask: the handler
+ * answers 405 without ever building an MCP server, and a registry answers 401 ahead of that because
+ * the credential check runs first. Anything else, 404 and 5xx included, means it is not there.
+ */
+const LIVE_STATUSES = new Set([200, 401, 403, 405]);
+
+const probeEndpoint = (url: string): Promise<EndpointStatus> => {
+  if (cachedStatus) return Promise.resolve(cachedStatus);
+  if (inFlight) return inFlight;
+  inFlight = fetch(url, { method: 'GET' })
+    .then((res): EndpointStatus => (LIVE_STATUSES.has(res.status) ? 'live' : 'unreachable'))
+    .catch((): EndpointStatus => 'unreachable')
+    .then((status) => {
+      cachedStatus = status;
+      return status;
+    })
+    .finally(() => {
+      inFlight = null;
+    });
+  return inFlight;
+};
+
+const useEndpointStatus = (url: string): EndpointStatus => {
+  const [status, setStatus] = React.useState<EndpointStatus>(cachedStatus ?? 'checking');
+
+  React.useEffect(() => {
+    if (!url || cachedStatus) return;
+    let active = true;
+    void probeEndpoint(url).then((next) => {
+      if (active) setStatus(next);
+    });
+    return () => {
+      active = false;
+    };
+  }, [url]);
+
+  return status;
+};
+
+const DOT: Record<EndpointStatus, { className: string; label: string }> = {
+  checking: { className: 'bg-muted-foreground/40', label: 'Checking the MCP endpoint' },
+  live: { className: 'bg-green-500', label: 'MCP endpoint is live' },
+  unreachable: { className: 'bg-red-500', label: 'MCP endpoint is not responding' },
+};
+
+const StatusDot: React.FC<{ status: EndpointStatus; className?: string }> = ({ status, className }) => (
+  <span role="status" aria-label={DOT[status].label} title={DOT[status].label} className={cn('size-1.5 rounded-full', DOT[status].className, className)} />
+);
+
+const Snippet: React.FC<{ label: string; value: string; compact?: boolean }> = ({ label, value, compact }) => (
+  <div className="min-w-0 space-y-1.5">
+    <div className="flex items-center justify-between gap-2">
+      <code className="truncate rounded bg-muted px-1.5 py-0.5 text-[11px] text-muted-foreground">{label}</code>
+      <CopyToClipboard value={value} tooltip={`Copy ${label}`} showTooltip={false} className="relative size-7 shrink-0" />
+    </div>
+    <pre
+      className={cn(
+        'overflow-auto rounded-md border bg-muted/50 p-3 leading-relaxed',
+        compact ? 'max-h-48 text-[10px]' : 'max-h-64 text-xs'
+      )}
+    >
+      <code>{value}</code>
+    </pre>
+  </div>
+);
+
+const ClientConfig: React.FC<{ client: McpClient; name: string; target: McpTarget; compact?: boolean }> = ({
+  client,
+  name,
+  target,
+  compact,
+}) => {
+  // A one-click install would write the `<your-token>` placeholder verbatim and register a server
+  // that cannot connect, so a registry gets the snippet and the token pointer instead.
+  const deeplink = isRegistryRuntime ? undefined : client.deeplink?.(name, target);
+  const command = client.command?.(name, target);
+
+  return (
+    <div className="min-w-0 space-y-3">
+      {deeplink && (
+        <Button asChild size="sm" className="w-full gap-2">
+          <a href={deeplink}>
+            <ExternalLink aria-hidden="true" />
+            Install in {client.name}
+          </a>
+        </Button>
+      )}
+      {command && <Snippet label="command line" value={command} compact={compact} />}
+      <Snippet label={client.configPath} value={JSON.stringify(client.file(name, target), null, 2)} compact={compact} />
+      <p className="text-xs text-muted-foreground">{client.note}</p>
+    </div>
+  );
+};
+
+const Endpoint: React.FC<{ url: string; status: EndpointStatus }> = ({ url, status }) => (
+  <div className="min-w-0 space-y-1.5">
+    <div className="flex flex-wrap items-center justify-between gap-x-2">
+      <p className="flex items-center gap-1.5 text-xs font-medium">
+        <StatusDot status={status} />
+        Endpoint
+      </p>
+      {/* Saying so up front heads off opening the URL in a browser and getting a 405. */}
+      <p className="text-[10px] uppercase tracking-wide text-muted-foreground">POST · Streamable HTTP</p>
+    </div>
+    <div className="flex items-stretch overflow-hidden rounded-md border">
+      <code className="flex flex-1 items-center truncate px-3 py-2 font-mono text-xs text-gray-700 dark:text-gray-300">{url}</code>
+      <CopyToClipboard
+        value={url}
+        tooltip="Copy endpoint"
+        showTooltip={false}
+        className="relative h-auto w-9 shrink-0 self-stretch rounded-none border-0 border-l shadow-none"
+      />
+    </div>
+  </div>
+);
+
+const Credential: React.FC = () => (
+  <p className="border-t pt-3 text-xs text-muted-foreground">
+    Needs an access token — read-only access is enough.{' '}
+    <Link href="/account/tokens" className="font-medium text-foreground underline">
+      Create one in Account settings
+    </Link>
+    .
+  </p>
+);
+
+/** Endpoint, per-client config and credential guidance. Shared by the dialog and the mobile nav. */
+const ConnectionDetails: React.FC<{ url: string; status: EndpointStatus; compact?: boolean }> = ({ url, status, compact }) => {
+  const name = useServerName();
+  const target: McpTarget = { url, headers: isRegistryRuntime ? CREDENTIAL_HEADERS : undefined };
+
+  return (
+    <div className="min-w-0 space-y-4">
+      <Endpoint url={url} status={status} />
+      <Tabs defaultValue={CLIENTS[0].id} className="min-w-0">
+        <TabsList className="w-full">
+          {CLIENTS.map((client) => (
+            <TabsTrigger key={client.id} value={client.id} className="flex-1 text-xs">
+              {client.name}
+            </TabsTrigger>
+          ))}
+        </TabsList>
+        {CLIENTS.map((client) => (
+          <TabsContent key={client.id} value={client.id} className="min-w-0">
+            <ClientConfig client={client} name={name} target={target} compact={compact} />
+          </TabsContent>
+        ))}
+      </Tabs>
+      {isRegistryRuntime && <Credential />}
+    </div>
+  );
+};
+
+const mode = isRegistryRuntime ? 'registry' : 'workspace';
+
+const DESCRIPTION =
+  "This app serves an MCP endpoint, so a coding agent can read the components and tokens that already exist instead of inventing markup and values.";
+
+export function McpConfigDialog() {
+  return isAvailable ? <McpDialog /> : null;
+}
+
+const McpDialog: React.FC = () => {
+  const url = useMcpEndpoint();
+  const status = useEndpointStatus(url);
+
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="ghost" size="icon" className="relative" title="Connect a coding agent">
+          <McpIcon className="h-[1.2rem] w-[1.2rem]" />
+          <StatusDot status={status} className="absolute right-1.5 top-1.5" />
+          <span className="sr-only">Connect a coding agent</span>
+        </Button>
+      </DialogTrigger>
+      <DialogContent className="max-h-[85vh] overflow-y-auto sm:max-w-[560px]">
+        <DialogHeader>
+          <div className="flex flex-wrap items-center gap-2">
+            <DialogTitle>Connect a coding agent</DialogTitle>
+            <RuntimeModeBadge mode={mode} />
+          </div>
+          <DialogDescription>{DESCRIPTION}</DialogDescription>
+        </DialogHeader>
+        <ConnectionDetails url={url} status={status} />
+      </DialogContent>
+    </Dialog>
+  );
+};
+
+/**
+ * Inline variant for the mobile nav, which is itself a sheet, so a nested dialog would sit on top of
+ * it. It owns its divider, so a build without the endpoint renders nothing and leaves no stray rule.
+ */
+export function McpConfigMobile() {
+  return isAvailable ? <McpMobile /> : null;
+}
+
+const McpMobile: React.FC = () => {
+  const url = useMcpEndpoint();
+  const status = useEndpointStatus(url);
+
+  return (
+    <div className="mt-4 space-y-3 border-t pt-4">
+      <div className="flex flex-wrap items-center gap-2">
+        <McpIcon className="h-4 w-4" />
+        <span className="text-sm font-medium">Connect a coding agent</span>
+        <RuntimeModeBadge mode={mode} />
+      </div>
+      <ConnectionDetails url={url} status={status} compact />
+    </div>
+  );
+};

package/src/app/components/McpIntegration/McpIcon.tsx

@@ -0,0 +1,10 @@
+/**
+ * The Model Context Protocol mark. Path from Simple Icons (`modelcontextprotocol`), CC0-1.0.
+ *
+ * Unlike the stroked lucide icons around it this is a filled path, so it takes `fill`, not `stroke`.
+ */
+export const McpIcon: React.FC<{ className?: string }> = ({ className }) => (
+  <svg className={className} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" focusable="false">
+    <path d="M13.85 0a4.16 4.16 0 0 0-2.95 1.217L1.456 10.66a.835.835 0 0 0 0 1.18.835.835 0 0 0 1.18 0l9.442-9.442a2.49 2.49 0 0 1 3.541 0 2.49 2.49 0 0 1 0 3.541L8.59 12.97l-.1.1a.835.835 0 0 0 0 1.18.835.835 0 0 0 1.18 0l.1-.098 7.03-7.034a2.49 2.49 0 0 1 3.542 0l.049.05a2.49 2.49 0 0 1 0 3.54l-8.54 8.54a1.96 1.96 0 0 0 0 2.755l1.753 1.753a.835.835 0 0 0 1.18 0 .835.835 0 0 0 0-1.18l-1.753-1.753a.266.266 0 0 1 0-.394l8.54-8.54a4.185 4.185 0 0 0 0-5.9l-.05-.05a4.16 4.16 0 0 0-2.95-1.218c-.2 0-.401.02-.6.048a4.17 4.17 0 0 0-1.17-3.552A4.16 4.16 0 0 0 13.85 0m0 3.333a.84.84 0 0 0-.59.245L6.275 10.56a4.186 4.186 0 0 0 0 5.902 4.186 4.186 0 0 0 5.902 0L19.16 9.48a.835.835 0 0 0 0-1.18.835.835 0 0 0-1.18 0l-6.985 6.984a2.49 2.49 0 0 1-3.54 0 2.49 2.49 0 0 1 0-3.54l6.983-6.985a.835.835 0 0 0 0-1.18.84.84 0 0 0-.59-.245" />
+  </svg>
+);

package/src/app/components/Navigation/MobileNav.tsx

@@ -3,6 +3,7 @@ import { Menu, Monitor, Moon, Sun, X } from 'lucide-react';
 import { useTheme } from 'next-themes';
 import Link from 'next/link';
 import { useRouter } from 'next/router';
+import { McpConfigMobile } from '../../components/McpIntegration/McpConfigDialog';
 import { Button } from '../../components/ui/button';
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from '../../components/ui/sheet';
 import { cn } from '../../lib/utils';
@@ -37,7 +38,7 @@ export function MobileNav() {
           <Menu />
         </Button>
       </SheetTrigger>
-      <SheetContent side="right" className="w-full max-w-[300px] [&>button:first-of-type]:hidden">
+      <SheetContent side="right" className="w-full max-w-[300px] overflow-y-auto [&>button:first-of-type]:hidden">
         <SheetHeader className="flex flex-row items-center justify-between">
           <SheetTitle>
             <Link href="/">
@@ -69,6 +70,7 @@ export function MobileNav() {
                 </Link>
               );
             })}
+          <McpConfigMobile />
           <div className="mt-4 border-t pt-4">
             <Button variant="ghost" className="w-full justify-start font-normal" onClick={toggleTheme}>
               {theme === 'light' && (

package/src/app/components/ui/dialog.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import { X } from 'lucide-react';
+import * as React from 'react';
+
+import { cn } from '../../lib/utils';
+
+const Dialog = DialogPrimitive.Root;
+
+const DialogTrigger = DialogPrimitive.Trigger;
+
+const DialogOverlay = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Overlay
+    ref={ref}
+    className={cn(
+      'fixed inset-0 z-50 bg-gray-200/50 backdrop-blur-xs data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+      className
+    )}
+    {...props}
+  />
+));
+DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
+
+const DialogContent = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+  <DialogPrimitive.Portal>
+    <DialogOverlay />
+    <DialogPrimitive.Content
+      ref={ref}
+      className={cn(
+        'fixed left-1/2 top-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 sm:rounded-lg',
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 transition-opacity hover:opacity-100 focus:outline-hidden focus:ring-2 focus:ring-ring focus:ring-offset-2">
+        <X className="h-4 w-4" />
+        <span className="sr-only">Close</span>
+      </DialogPrimitive.Close>
+    </DialogPrimitive.Content>
+  </DialogPrimitive.Portal>
+));
+DialogContent.displayName = DialogPrimitive.Content.displayName;
+
+const DialogHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div className={cn('flex flex-col space-y-1.5', className)} {...props} />
+);
+DialogHeader.displayName = 'DialogHeader';
+
+const DialogTitle = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Title ref={ref} className={cn('text-lg font-semibold leading-none tracking-tight', className)} {...props} />
+));
+DialogTitle.displayName = DialogPrimitive.Title.displayName;
+
+const DialogDescription = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Description ref={ref} className={cn('text-sm text-muted-foreground', className)} {...props} />
+));
+DialogDescription.displayName = DialogPrimitive.Description.displayName;
+
+export { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger };

package/src/app/lib/docs-api/backend.ts

@@ -65,7 +65,11 @@ export interface DocsBackend {
   listPages(): Promise<PageListObject[]>;
   getComponentDetail(id: string): Promise<ComponentDetail | null>;
   getPatternDetail(id: string): Promise<PatternDetail | null>;
-  /** A page's record + rendered markdown body, or `null` when absent. Read by the catch-all route. */
+  /**
+   * The effective page for an id: its record plus the markdown body. A package default resolves
+   * here like a published or project page, so a caller can read every route the site serves. Same
+   * overlay rule as {@link DocsBackend.searchPages}.
+   */
   getPageDetail(id: string): Promise<PageDetail | null>;
   /**
    * Search the effective page set and return ranked, display-ready results. Project pages replace

package/src/app/lib/docs-api/page-discovery.ts

@@ -15,6 +15,7 @@ import {
   type PageSearchResult,
   type SearchablePage,
 } from './page-search';
+import { pageRoots } from './records';
 import { MAX_SEARCH_CANDIDATES, truncateSearchBody, type SearchResponse } from './search';
 
 /**
@@ -38,12 +39,6 @@ interface CachedPage extends DiscoveredPage {
 
 const discoveryCache = new Map<string, CachedPage>();
 
-/** Project pages replace package defaults with the same ID. */
-const pageRoots = (): string[] => [
-  path.resolve(process.env.HANDOFF_MODULE_PATH ?? '', 'config', 'docs'),
-  path.resolve(process.env.HANDOFF_WORKING_PATH ?? '', 'pages'),
-];
-
 /** Reuse a cached record when the file size and modification time have not changed. */
 const readRecord = (id: string, absolutePath: string): CachedPage | null => {
   let stats: fs.Stats;

package/src/app/lib/docs-api/page-rendering.ts

@@ -1,9 +1,29 @@
+import { normalizePageDeclaration } from '@handoff/config/normalizers/page';
+import { HOME_PAGE_ID, HOME_PAGE_PATH } from '@handoff/registry/content-kinds';
+import type { PageDetail } from './records';
+// A static import puts the package defaults in every bundle. A deployed registry function cannot
+// read the build machine's `config/docs` directory.
+import defaultPages from '../../generated/default-pages.json';
+
 /** Registry pages use short-lived ISR so independent instances converge after a publish. */
 export const REGISTRY_PAGE_REVALIDATE_SECONDS = 1;
 
 export type BakedDefaultPage = { metadata: Record<string, unknown>; content: string };
 
-/** Normalize registry records and baked frontmatter into the page component's metadata contract. */
+/**
+ * The packaged default for a page id. Shared by the registry backing and by the registry build,
+ * which must resolve the home page without a database connection.
+ */
+export const defaultPageDetail = (id: string): PageDetail | null => {
+  const page = (defaultPages as Record<string, BakedDefaultPage>)[id];
+  if (!page) {
+    return null;
+  }
+  const routePath = id === HOME_PAGE_ID ? HOME_PAGE_PATH : `/${id}`;
+  return { ...normalizePageDeclaration(page.metadata, { id, routePath }), content: page.content };
+};
+
+/** Normalize a page record into the page component's metadata contract. */
 export const documentationMetadata = (source: Record<string, unknown>) => {
   const value = (key: string): string => (typeof source[key] === 'string' ? (source[key] as string) : '');
   const title = value('title');

package/src/app/lib/docs-api/records.ts

@@ -77,15 +77,33 @@ export const getPatternDetail = (id: string): PatternDetail | null => {
 };
 
 /**
- * Workspace-mode page reads. These scan `<workingPath>/pages/` directly (there is no generated page
- * summary). Vestigial in practice — workspace nav is baked and the catch-all reads markdown through
- * `fetchDocPageMarkdown` — but implemented honestly so the {@link DocsBackend} contract holds.
+ * Workspace-mode page reads, scanned from the filesystem because there is no generated page summary.
+ * `getPageDetail` resolves the effective page, so it answers for every route the site serves.
+ * `listPages` stays project-only: it feeds the nav resolver, which already gets the package defaults
+ * from the baked menu shell.
  */
 const workingPagesRoot = (): string => path.resolve(process.env.HANDOFF_WORKING_PATH ?? '', 'pages');
 
+/** Effective page roots in precedence order: a project page replaces a package default of the same id. */
+export const pageRoots = (): string[] => [path.resolve(process.env.HANDOFF_MODULE_PATH ?? '', 'config', 'docs'), workingPagesRoot()];
+
 /** Collect page slugs, including the root home page but excluding nested section index files. */
 const collectPageSlugs = (root: string): string[][] => collectPageSlugSegments(root, { includeRootIndex: true });
 
+/**
+ * The markdown file for a page id. The id is matched against the collected slugs rather than joined
+ * onto a root, so a request cannot reach outside them.
+ */
+const resolvePageSource = (id: string): string | null => {
+  let sourcePath: string | null = null;
+  for (const root of pageRoots()) {
+    if (collectPageSlugs(root).some((segments) => segments.join('/') === id)) {
+      sourcePath = path.resolve(root, `${id}.md`);
+    }
+  }
+  return sourcePath;
+};
+
 export const listPages = (): PageListObject[] => {
   const root = workingPagesRoot();
   return collectPageSlugs(root).map((segments) => {
@@ -98,16 +116,13 @@ export const listPages = (): PageListObject[] => {
 };
 
 export const getPageDetail = (id: string): PageDetail | null => {
-  const root = workingPagesRoot();
-  const segments = collectPageSlugs(root).find((candidate) => candidate.join('/') === id);
-  if (!segments) {
+  const sourcePath = resolvePageSource(id);
+  if (!sourcePath) {
     return null;
   }
-  const slug = segments.join('/');
-  const sourcePath = path.resolve(root, `${slug}.md`);
   const { data, content } = parseMarkdown(fs.readFileSync(sourcePath, 'utf8'));
-  const routePath = slug === HOME_PAGE_ID ? HOME_PAGE_PATH : `/${slug}`;
-  return { ...normalizePageDeclaration(data, { id: slug, routePath, sourcePath }), content };
+  const routePath = id === HOME_PAGE_ID ? HOME_PAGE_PATH : `/${id}`;
+  return { ...normalizePageDeclaration(data, { id, routePath, sourcePath }), content };
 };
 
 /**

package/src/app/lib/docs-api/registry.ts

@@ -18,7 +18,7 @@ import {
   type PageSearchResult,
   type SearchablePage,
 } from './page-search';
-import type { BakedDefaultPage } from './page-rendering';
+import { defaultPageDetail, type BakedDefaultPage } from './page-rendering';
 import { MAX_SEARCH_BODY_LENGTH, MAX_SEARCH_CANDIDATES, truncateSearchBody, type SearchResponse } from './search';
 import { getRegistryConnection } from '../registry-connection';
 import { getAssetStorageAdapter } from '../asset-storage';
@@ -181,7 +181,9 @@ export const createRegistryDocsBackend = async (): Promise<DocsBackend> => {
         .from(pages)
         .leftJoin(pageFiles, eq(pageFiles.pageId, pages.id))
         .where(eq(pages.id, id));
-      return row ? { ...row.record, content: row.body ?? '' } : null;
+      // A package default the project never published is still served at its route, so it resolves
+      // here too. Publishing the same id replaces it, as it does in search.
+      return row ? { ...row.record, content: row.body ?? '' } : defaultPageDetail(id);
     },
     async searchPages(request: PageSearchRequest) {
       return searchRegistryPages(db, request);

package/src/app/lib/docs-api/runtime-config.ts

@@ -33,6 +33,8 @@ export interface ServerRegistryRuntimeConfig {
 /** Resolved server-side runtime configuration for the docs read API. */
 export interface ServerRuntimeConfig {
   mode: RuntimeMode;
+  /** Whether this build serves `/api/mcp/`. Config-only, baked at build time. */
+  mcp: boolean;
   registry: ServerRegistryRuntimeConfig;
   /**
    * Asset storage selection for registry mode (provider + non-secret options + env-var names). Secret
@@ -46,6 +48,7 @@ let cached: ServerRuntimeConfig | null = null;
 /** Safe defaults: workspace mode with the default Postgres driver + `DATABASE_URL` env var. */
 const defaults = (): ServerRuntimeConfig => ({
   mode: 'workspace',
+  mcp: true,
   registry: {
     driver: DEFAULT_REGISTRY_DRIVER,
     databaseUrlEnv: DEFAULT_DATABASE_URL_ENV,
@@ -103,6 +106,7 @@ const fromEnv = (): ServerRuntimeConfig | null => {
   const databaseUrlEnv = process.env.HANDOFF_REGISTRY_DATABASE_URL_ENV?.trim() || DEFAULT_DATABASE_URL_ENV;
   return {
     mode: mode === 'registry' ? 'registry' : 'workspace',
+    mcp: process.env.HANDOFF_MCP_ENABLED?.trim() !== 'false',
     registry: {
       driver: process.env.HANDOFF_REGISTRY_DRIVER?.trim() === 'neon' ? 'neon' : 'pg',
       databaseUrlEnv,
@@ -142,6 +146,7 @@ export const getServerRuntimeConfig = (): ServerRuntimeConfig => {
           : { adapter: DEFAULT_ASSET_STORAGE_ADAPTER };
       cached = {
         mode: parsed?.mode === 'registry' ? 'registry' : 'workspace',
+        mcp: parsed?.mcp !== false,
         registry: {
           driver: parsed?.registry?.driver === 'neon' ? 'neon' : 'pg',
           databaseUrlEnv,

package/src/app/lib/docs-api/search.ts

@@ -96,7 +96,12 @@ const parseLimit = (raw: string | undefined): number => {
  * of rejecting the full query. The request fails only when it contains no usable term.
  */
 export const parseSearchRequest = (req: NextApiRequest): { request: SearchRequest } | { error: string } => {
-  const query = singleQueryValue(req.query.q)?.trim() ?? '';
+  return createSearchRequest(singleQueryValue(req.query.q), singleQueryValue(req.query.limit));
+};
+
+/** Shared validation and normalization for HTTP and MCP search callers. */
+export const createSearchRequest = (rawQuery?: string, rawLimit?: string): { request: SearchRequest } | { error: string } => {
+  const query = rawQuery?.trim() ?? '';
   if (!query) {
     return { error: 'Provide a non-empty `q` search parameter.' };
   }
@@ -111,5 +116,5 @@ export const parseSearchRequest = (req: NextApiRequest): { request: SearchReques
   if (terms.length > MAX_TERMS) {
     return { error: `Search query must contain no more than ${MAX_TERMS} distinct terms.` };
   }
-  return { request: { query, terms, phrase, limit: parseLimit(singleQueryValue(req.query.limit)) } };
+  return { request: { query, terms, phrase, limit: parseLimit(rawLimit) } };
 };