handoff-app 2.0.0-5 → 2.0.0-6

package/README.md

@@ -385,6 +385,51 @@ runtime: {
 },
 ```
 
+## MCP
+
+The documentation app serves a Model Context Protocol endpoint at `/api/mcp/`, so
+coding agents can look up the pages, components and tokens that already exist instead
+of inventing markup and values. It is stateless Streamable HTTP over `POST`;
+there is nothing to start and no extra port. Keep the trailing slash: the app
+sets `trailingSlash: true`, so `/api/mcp` answers with a 308 redirect.
+
+| Target | Endpoint | Credential |
+| --- | --- | --- |
+| Workspace (`dev` / `start`) | `http://localhost:3000/api/mcp/` | none, as with `/api/docs/*` |
+| Registry (standalone or Vercel) | `<registry url>/api/mcp/` | an access token, read-only is enough |
+| Static export | not available, a static site has no API routes | n/a |
+
+Registry tokens come from `handoff-app login` or Account settings in the
+registry itself, and are the same credentials the rest of the registry API takes.
+
+The endpoint is served unless a project turns it off:
+
+```ts
+runtime: {
+  mcp: false,
+},
+```
+
+Like `runtime.mode`, this is config-only and baked at build time, so changing it
+in a deployed registry means a rebuild. A disabled build answers 404 on the route,
+drops the MCP SDK from the packaged bundle, and shows no connect affordance at all
+rather than one that fails.
+
+The documentation app carries its own endpoint and a ready-made client config
+for Claude Code, Cursor and VS Code behind the plug icon in the header. By hand:
+
+```json
+{
+  "mcpServers": {
+    "handoff": {
+      "type": "http",
+      "url": "https://registry.example.com/api/mcp/",
+      "headers": { "Authorization": "Bearer hnd_..." }
+    }
+  }
+}
+```
+
 ## Configuration
 
 Configuration is read from `handoff.config.ts`, `.js`, `.cjs`, or `.json`, in

package/dist/app-builder/build.js

@@ -40,6 +40,7 @@ const p = __importStar(require("@clack/prompts"));
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const config_1 = require("../config");
 const components_1 = require("../pipeline/components");
 const patterns_1 = require("../pipeline/patterns");
 const resolve_1 = require("../registry/asset-storage/resolve");
@@ -216,6 +217,7 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
     // Resolved runtime mode + registry connection inputs (names only) baked into the Next bundle so the
     // deployed registry app resolves its mode/DB env-var name without any build-machine filesystem.
     const escapedRuntimeMode = escapeForSingleQuotedJsString(runtimeMode);
+    const escapedMcpEnabled = escapeForSingleQuotedJsString(String((0, config_1.isMcpEnabled)(handoff.config)));
     const escapedRegistryDriver = escapeForSingleQuotedJsString((0, driver_1.resolveRegistryDriver)(handoff.config));
     const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString((0, driver_1.resolveDatabaseUrlEnv)(handoff.config));
     // Asset storage selection baked (provider + module + env-var names + non-secret options JSON).
@@ -233,6 +235,7 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
         '%HANDOFF_EXPORT_PATH%': escapedExportPath,
         '%HANDOFF_WEBSOCKET_PORT%': escapedWebsocketPort,
         '%HANDOFF_RUNTIME_MODE%': escapedRuntimeMode,
+        '%HANDOFF_MCP_ENABLED%': escapedMcpEnabled,
         '%HANDOFF_REGISTRY_DRIVER%': escapedRegistryDriver,
         '%HANDOFF_REGISTRY_DATABASE_URL_ENV%': escapedDatabaseUrlEnv,
         '%HANDOFF_ASSET_STORAGE_ADAPTER%': escapedAssetStorageAdapter,
@@ -426,12 +429,16 @@ containers, custom Node servers, and other non-Vercel hosts.
 /**
  * Resolve the set of npm packages the packaged registry app must be able to `require`/`import` at
  * runtime, given the configured database driver. `next`/`react`/`react-dom` run the server and React
- * runtime; `drizzle-orm` backs both the request-time DB client and the migration runner; the driver
- * package is driver-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
+ * runtime; `drizzle-orm` backs both the request-time DB client and the migration runner; the MCP SDK
+ * (and its `zod` peer) is only needed when `/api/mcp/` is enabled; the driver package is
+ * driver-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
  */
 const getRequiredRegistryRuntimeModules = (handoff) => {
     var _a;
     const base = ['next', 'next-auth', 'react', 'react-dom', 'drizzle-orm'];
+    if ((0, config_1.isMcpEnabled)(handoff.config)) {
+        base.push('@modelcontextprotocol/sdk', 'zod');
+    }
     const driver = (0, driver_1.resolveRegistryDriver)(handoff.config);
     const driverModules = driver === 'neon' ? ['@neondatabase/serverless', 'ws'] : ['pg'];
     // Asset-storage SDKs the deployed registry must be able to load at request time. The pre-packaged

package/dist/app-builder/client-config.js

@@ -65,6 +65,7 @@ const buildServerRuntimeConfig = (config, modeOverride) => {
     const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(config);
     return {
         mode: (_b = modeOverride !== null && modeOverride !== void 0 ? modeOverride : (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.mode) !== null && _b !== void 0 ? _b : 'workspace',
+        mcp: (0, config_1.isMcpEnabled)(config),
         registry: {
             driver: (0, driver_1.resolveRegistryDriver)(config),
             databaseUrlEnv: (0, driver_1.resolveDatabaseUrlEnv)(config),

package/dist/config/defaults.d.ts

@@ -6,6 +6,8 @@ export interface ImageStyle {
     width: number;
     description: string;
 }
+/** Whether the MCP endpoint is served. On unless `runtime.mcp` is explicitly `false`. */
+export declare const isMcpEnabled: (config: Config | null | undefined) => boolean;
 export declare const defaultConfig: () => Config;
 /**
  * Retrieves the client configuration from the provided handoff configuration.

package/dist/config/defaults.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getClientConfig = exports.defaultConfig = void 0;
+exports.getClientConfig = exports.defaultConfig = exports.isMcpEnabled = void 0;
 const connection_1 = require("../registry/connection");
+/** Whether the MCP endpoint is served. On unless `runtime.mcp` is explicitly `false`. */
+const isMcpEnabled = (config) => { var _a; return ((_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.mcp) !== false; };
+exports.isMcpEnabled = isMcpEnabled;
 const defaultConfig = () => {
     var _a, _b, _c, _d;
     return ({

package/dist/config/index.d.ts

@@ -1,4 +1,4 @@
-export { defaultConfig, getClientConfig } from './defaults';
+export { defaultConfig, getClientConfig, isMcpEnabled } from './defaults';
 export type { ImageStyle } from './defaults';
 export { HandoffConfigError, initConfig, initConfigWithMetadata } from './loader';
 export type { ConfigLoadContext } from './loader';

package/dist/config/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeEntries = exports.isEntryCovered = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.getClientConfig = exports.defaultConfig = void 0;
+exports.writeEntries = exports.isEntryCovered = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.isMcpEnabled = exports.getClientConfig = exports.defaultConfig = void 0;
 // Config defaults and client config
 var defaults_1 = require("./defaults");
 Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return defaults_1.defaultConfig; } });
 Object.defineProperty(exports, "getClientConfig", { enumerable: true, get: function () { return defaults_1.getClientConfig; } });
+Object.defineProperty(exports, "isMcpEnabled", { enumerable: true, get: function () { return defaults_1.isMcpEnabled; } });
 // Config file loading
 var loader_1 = require("./loader");
 Object.defineProperty(exports, "HandoffConfigError", { enumerable: true, get: function () { return loader_1.HandoffConfigError; } });

package/dist/types/config.d.ts

@@ -127,6 +127,13 @@ export interface HandoffRuntimeConfig {
      * Mode is never inferred from environment variables, database settings, or token presence.
      */
     mode?: RuntimeMode;
+    /**
+     * Whether the app serves the `/api/mcp/` Model Context Protocol endpoint. Set to `false` to leave
+     * the endpoint and the header affordance out of the build; the route then answers 404. Like
+     * `mode`, this is config-only and baked at build time, so changing it needs a rebuild.
+     * @default true
+     */
+    mcp?: boolean;
     /** Workspace-mode settings. */
     workspace?: {
         entries?: ConfigEntries;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "2.0.0-5",
+  "version": "2.0.0-6",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",
@@ -53,6 +53,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@neondatabase/serverless": "^1.1.0",
     "@radix-ui/react-accordion": "^1.2.8",
     "@radix-ui/react-collapsible": "^1.1.2",
@@ -121,7 +122,8 @@
     "vaul": "^1.1.2",
     "vite": "^6.3.5",
     "ws": "^8.18.3",
-    "yargs": "^17.7.2"
+    "yargs": "^17.7.2",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "typescript": ">=5.6 <7"

package/src/app/components/CopyToClipboard.tsx

@@ -7,11 +7,14 @@ import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './ui/t
 
 type CopyToClipboardProps = {
   value: string;
+  /** Accessible name for the control, and the hover tooltip unless `showTooltip` is off. */
   tooltip: string;
+  /** Hide the tooltip where the surrounding UI already says what the button copies. */
+  showTooltip?: boolean;
   className?: string;
 };
 
-export const CopyToClipboard: React.FC<CopyToClipboardProps> = ({ value, tooltip, className }) => {
+export const CopyToClipboard: React.FC<CopyToClipboardProps> = ({ value, tooltip, showTooltip = true, className }) => {
   const [copied, setCopied] = React.useState<boolean>(false);
 
   const handleCopy = async () => {
@@ -24,33 +27,32 @@ export const CopyToClipboard: React.FC<CopyToClipboardProps> = ({ value, tooltip
     }
   };
 
+  const button = (
+    <Button
+      variant="outline"
+      size="icon"
+      className={cn('disabled:opacity-100', className)}
+      onClick={handleCopy}
+      aria-label={copied ? 'Copied' : tooltip}
+      disabled={copied}
+    >
+      <div className={cn('transition-all', copied ? 'scale-100 opacity-100' : 'scale-0 opacity-0')}>
+        <CheckIcon className="stroke-gray-600" size={16} aria-hidden="true" />
+      </div>
+      <div className={cn('absolute transition-all', copied ? 'scale-0 opacity-0' : 'scale-100 opacity-100')}>
+        <CopyIcon aria-hidden="true" />
+      </div>
+    </Button>
+  );
+
+  if (!showTooltip) {
+    return button;
+  }
+
   return (
     <TooltipProvider delayDuration={0}>
       <Tooltip>
-        <TooltipTrigger asChild>
-          <Button
-            variant="outline"
-            size="icon"
-            className={cn('disabled:opacity-100', className)}
-            onClick={handleCopy}
-            aria-label={copied ? 'Copied' : 'Copy to clipboard'}
-            disabled={copied}
-          >
-            <div
-              className={cn('transition-all', copied ? 'scale-100 opacity-100' : 'scale-0 opacity-0')}
-            >
-              <CheckIcon className="stroke-gray-600" size={16} aria-hidden="true" />
-            </div>
-            <div
-              className={cn(
-                'absolute transition-all',
-                copied ? 'scale-0 opacity-0' : 'scale-100 opacity-100'
-              )}
-            >
-              <CopyIcon aria-hidden="true" />
-            </div>
-          </Button>
-        </TooltipTrigger>
+        <TooltipTrigger asChild>{button}</TooltipTrigger>
         <TooltipContent className="px-2 py-1 text-xs">{tooltip}</TooltipContent>
       </Tooltip>
     </TooltipProvider>
@@ -58,4 +60,3 @@ export const CopyToClipboard: React.FC<CopyToClipboardProps> = ({ value, tooltip
 };
 
 export default CopyToClipboard;
-

package/src/app/components/Layout/Header.tsx

@@ -1,23 +1,18 @@
 import Link from 'next/link';
 import { useEffect, useState } from 'react';
+import { McpConfigDialog } from '../../components/McpIntegration/McpConfigDialog';
 import { ModeToggle } from '../../components/ModeSwitcher';
 import { MainNav } from '../../components/Navigation/MainNav';
 import { MobileNav } from '../../components/Navigation/MobileNav';
 import { cn } from '../../lib/utils';
-import { Badge } from '../ui/badge';
 import { useConfigContext } from '../context/ConfigContext';
 import { AuthControls } from '../Auth/AuthControls';
-
-const RUNTIME_MODE_LABEL: Record<'workspace' | 'registry', string> = {
-  workspace: 'Workspace',
-  registry: 'Registry',
-};
+import { RuntimeModeBadge } from './RuntimeModeBadge';
 
 export function Header() {
   const context = useConfigContext();
   const [isScrolled, setIsScrolled] = useState(false);
   const runtimeMode = context.config?.runtime?.mode ?? 'workspace';
-  const runtimeModeLabel = RUNTIME_MODE_LABEL[runtimeMode];
   // The static export is a self-contained snapshot of the workspace, not a live runtime, so the
   // runtime-mode badge carries no meaning there and is omitted.
   const isStaticSnapshot = process.env.HANDOFF_BUILD_TARGET === 'static';
@@ -44,14 +39,11 @@ export function Header() {
             <Link href="/">
               <img className="max-h-5" src={`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/logo.svg`} alt={context.config?.app?.title} />
             </Link>
-            {!isStaticSnapshot && (
-              <Badge variant={runtimeMode === 'registry' ? 'info' : 'default'} aria-label={`Runtime mode: ${runtimeModeLabel}`}>
-                {runtimeModeLabel}
-              </Badge>
-            )}
+            {!isStaticSnapshot && <RuntimeModeBadge mode={runtimeMode} />}
           </div>
           <div className="hidden items-center gap-4 @2xl:flex">
             <MainNav />
+            <McpConfigDialog />
             {runtimeMode === 'registry' ? <AuthControls /> : null}
             <ModeToggle />
           </div>

package/src/app/components/Layout/RuntimeModeBadge.tsx

@@ -0,0 +1,18 @@
+import type { RuntimeMode } from '@handoff/types/config';
+import { Badge } from '../ui/badge';
+
+const LABEL: Record<RuntimeMode, string> = {
+  workspace: 'Workspace',
+  registry: 'Registry',
+};
+
+/**
+ * The Workspace/Registry marker, shared by the header and the MCP connect dialog. `mode` is a prop
+ * because the header reads the projected client config while the dialog reads the mode baked into
+ * the bundle.
+ */
+export const RuntimeModeBadge: React.FC<{ mode: RuntimeMode; className?: string }> = ({ mode, className }) => (
+  <Badge variant={mode === 'registry' ? 'info' : 'default'} className={className} aria-label={`Runtime mode: ${LABEL[mode]}`}>
+    {LABEL[mode]}
+  </Badge>
+);