handoff-app 2.0.0-11 → 2.0.0-13

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

@@ -134,18 +134,13 @@ type EndpointStatus = 'checking' | 'live' | 'unreachable';
 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'))
+  // The endpoint answers HEAD with 204 before the credential check. Thus a served route never logs an
+  // error status to the console.
+  inFlight = fetch(url, { method: 'HEAD' })
+    .then((res): EndpointStatus => (res.ok ? 'live' : 'unreachable'))
     .catch((): EndpointStatus => 'unreachable')
     .then((status) => {
       cachedStatus = status;
@@ -184,29 +179,19 @@ const StatusDot: React.FC<{ status: EndpointStatus; className?: string }> = ({ s
   <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 }) => (
+const Snippet: React.FC<{ label: string; value: string }> = ({ label, value }) => (
   <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'
-      )}
-    >
+    <pre className="max-h-64 overflow-auto rounded-md border bg-muted/50 p-3 text-xs leading-relaxed">
       <code>{value}</code>
     </pre>
   </div>
 );
 
-const ClientConfig: React.FC<{ client: McpClient; name: string; target: McpTarget; compact?: boolean }> = ({
-  client,
-  name,
-  target,
-  compact,
-}) => {
+const ClientConfig: React.FC<{ client: McpClient; name: string; target: McpTarget }> = ({ client, name, target }) => {
   // 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);
@@ -222,8 +207,8 @@ const ClientConfig: React.FC<{ client: McpClient; name: string; target: McpTarge
           </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} />
+      {command && <Snippet label="command line" value={command} />}
+      <Snippet label={client.configPath} value={JSON.stringify(client.file(name, target), null, 2)} />
       <p className="text-xs text-muted-foreground">{client.note}</p>
     </div>
   );
@@ -261,8 +246,8 @@ const Credential: React.FC = () => (
   </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 }) => {
+/** Endpoint, per-client config and credential guidance. */
+const ConnectionDetails: React.FC<{ url: string; status: EndpointStatus }> = ({ url, status }) => {
   const name = useServerName();
   const target: McpTarget = { url, headers: isRegistryRuntime ? CREDENTIAL_HEADERS : undefined };
 
@@ -279,7 +264,7 @@ const ConnectionDetails: React.FC<{ url: string; status: EndpointStatus; compact
         </TabsList>
         {CLIENTS.map((client) => (
           <TabsContent key={client.id} value={client.id} className="min-w-0">
-            <ClientConfig client={client} name={name} target={target} compact={compact} />
+            <ClientConfig client={client} name={name} target={target} />
           </TabsContent>
         ))}
       </Tabs>
@@ -323,27 +308,3 @@ const McpDialog: React.FC = () => {
     </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/Navigation/MobileNav.tsx

@@ -4,7 +4,6 @@ import { useTheme } from 'next-themes';
 import Link from 'next/link';
 import { useRouter } from 'next/router';
 import { AiAssistantMobileTrigger } from '../../components/AiAssistant/AiAssistantProvider';
-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';
@@ -72,7 +71,6 @@ 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/util/index.ts

@@ -557,17 +557,6 @@ export const fetchDocPageMetadataAndContent = (localPath: string, slug: string |
  */
 export const filterOutUndefined = <T>(value: T): value is NonNullable<T> => value !== undefined;
 
-/**
- * Create a title string from a prefix
- * @param prefix
- * @returns
- */
-export const titleString = (prefix: string | null): string => {
-  const config = getClientRuntimeConfig();
-  const prepend = prefix ? `${prefix} | ` : '';
-  return `${prepend}${config?.app?.client} Design System`;
-};
-
 /**
  * Get the tokens for a component
  * @param component

package/src/app/lib/asset-storage.ts

@@ -1,20 +1,20 @@
 /**
- * Server-only asset storage runtime. Resolves the active adapter from the baked server runtime
- * config and lazily builds and memoizes it. Writes use the active adapter. Reads resolve by each
- * blob's recorded provider, so `database` blobs (inline bytea) stay readable when a `custom` adapter
- * is active. `database` has no adapter: its bytes live directly in `asset_blobs.content`.
+ * Server-only asset storage runtime. Resolves the active provider from the baked server runtime
+ * config and lazily builds and memoizes it. Writes use the active provider. Reads resolve by each
+ * blob's recorded provider, so `database` blobs (inline bytea) stay readable when a `custom` provider
+ * is active. `database` has no module: its bytes live directly in `asset_blobs.content`.
  *
  * Imported exclusively by registry API route handlers and the registry store.
  */
 
 import { resolveAssetStorageSettings, type ResolvedAssetStorage } from '@handoff/registry/asset-storage/resolve';
-import type { AssetStorage } from '@handoff/registry/asset-storage/types';
+import type { StorageProvider } from '@handoff/registry/asset-storage/types';
 import type { AssetStorageProvider } from '@handoff/registry/db/schema';
 import { getServerRuntimeConfig } from './docs-api/runtime-config';
 import { loadServerModule } from './server-module';
 
 let activeCache: ResolvedAssetStorage | null = null;
-const adapterCache = new Map<string, AssetStorage | null>();
+const providerCache = new Map<string, StorageProvider | null>();
 
 /** The active, fully-resolved asset storage settings for new uploads. */
 export const getActiveAssetStorage = (): ResolvedAssetStorage => {
@@ -32,49 +32,49 @@ export class AssetStorageError extends Error {
   }
 }
 
-/** Load a custom adapter module and coerce its default export (adapter object or factory) to an adapter. */
-const loadCustomAdapter = async (active: ResolvedAssetStorage): Promise<AssetStorage> => {
+/** Load a custom provider module and coerce its default export (provider object or factory) to a provider. */
+const loadCustomProvider = async (active: ResolvedAssetStorage): Promise<StorageProvider> => {
   if (!active.module) {
-    throw new AssetStorageError('A custom asset storage adapter is selected but no module path is configured.');
+    throw new AssetStorageError('A custom asset storage provider is selected but no module path is configured.');
   }
-  const candidate = (await loadServerModule(active.module, { options: active.options })) as Partial<AssetStorage> | null;
+  const candidate = (await loadServerModule(active.module, { options: active.options })) as Partial<StorageProvider> | null;
   if (!candidate || typeof candidate.put !== 'function' || typeof candidate.get !== 'function' || typeof candidate.delete !== 'function') {
-    throw new AssetStorageError(`Custom asset storage module "${active.module}" must default-export a defineAssetStorage adapter.`);
+    throw new AssetStorageError(`Custom asset storage module "${active.module}" must default-export a defineStorageProvider() result.`);
   }
-  return candidate as AssetStorage;
+  return candidate as StorageProvider;
 };
 
 /**
- * Resolve the {@link AssetStorage} adapter for a recorded provider, or `null` when the provider is the
- * inline `database` default (there is no adapter; content lives in the DB row). Reading a blob whose
+ * Resolve the {@link StorageProvider} for a recorded provider, or `null` when the provider is the
+ * inline `database` default (there is no module; content lives in the DB row). Reading a blob whose
  * provider is no longer configured throws an actionable error rather than silently failing.
  */
-export const getAssetStorageAdapter = async (provider: AssetStorageProvider): Promise<AssetStorage | null> => {
+export const getStorageProvider = async (provider: AssetStorageProvider): Promise<StorageProvider | null> => {
   if (provider === 'database') {
     return null;
   }
-  if (adapterCache.has(provider)) {
-    return adapterCache.get(provider) ?? null;
+  if (providerCache.has(provider)) {
+    return providerCache.get(provider) ?? null;
   }
 
   const active = getActiveAssetStorage();
-  if (active.adapterKind !== provider) {
+  if (active.provider !== provider) {
     throw new AssetStorageError(
-      `No asset storage adapter is configured for provider "${provider}". A blob was stored by that ` +
+      `No asset storage module is configured for provider "${provider}". A blob was stored by that ` +
         'provider but it is no longer selected. Restore its configuration to read it.'
     );
   }
-  const adapter = await loadCustomAdapter(active);
+  const storage = await loadCustomProvider(active);
 
-  adapterCache.set(provider, adapter);
-  return adapter;
+  providerCache.set(provider, storage);
+  return storage;
 };
 
-/** The adapter for the active provider (used for new uploads), or `null` for the inline database default. */
-export const getActiveAssetStorageAdapter = (): Promise<AssetStorage | null> => getAssetStorageAdapter(getActiveAssetStorage().adapterKind);
+/** The active provider (used for new uploads), or `null` for the inline database default. */
+export const getActiveStorageProvider = (): Promise<StorageProvider | null> => getStorageProvider(getActiveAssetStorage().provider);
 
 /** Reset memoized state (test seam only). */
 export const __resetAssetStorageCache = (): void => {
   activeCache = null;
-  adapterCache.clear();
+  providerCache.clear();
 };

package/src/app/lib/auth/email.ts

@@ -1,13 +1,12 @@
 import { isEnvReference, resolveEnvReferences } from '@handoff/config/from-env';
-import { createResendProvider } from '@handoff/registry/email/adapters/resend';
-import { createSmtpProvider } from '@handoff/registry/email/adapters/smtp';
+import { createSmtpProvider } from '@handoff/registry/email/providers/smtp';
 import type { EmailProviderKind, EmailSettings } from '@handoff/registry/email/resolve';
 import type { EmailProvider } from '@handoff/registry/email/types';
 import { getServerRuntimeConfig } from '../docs-api/runtime-config';
 import { loadServerModule } from '../server-module';
 
 /** Options a provider needs before email counts as configured. */
-const REQUIRED_OPTIONS: Record<EmailProviderKind, readonly string[]> = { resend: ['apiKey'], smtp: ['host'], custom: [] };
+const REQUIRED_OPTIONS: Record<EmailProviderKind, readonly string[]> = { smtp: ['host'], custom: [] };
 
 /**
  * The settings that still need a value, named as the administrator sets them: the config key, or the
@@ -17,6 +16,7 @@ export const missingRegistryEmailSettings = (): string[] => {
   const settings = getServerRuntimeConfig().email;
   const options = resolveEnvReferences(settings.options, process.env);
   const missing = settings.from ? [] : ['runtime.registry.email.from'];
+  if (!settings.provider) return [...missing, 'runtime.registry.email.provider'];
   if (settings.provider === 'custom' && !settings.module) missing.push('runtime.registry.email.module');
   for (const key of REQUIRED_OPTIONS[settings.provider]) {
     if (options[key] !== undefined) continue;
@@ -31,7 +31,7 @@ export const registryEmailIsConfigured = (): boolean => missingRegistryEmailSett
 /** The provider name for messages shown to an administrator. */
 export const registryEmailProviderName = (): string => {
   const { provider } = getServerRuntimeConfig().email;
-  return provider === 'resend' ? 'Resend' : provider === 'smtp' ? 'SMTP' : 'the custom email provider';
+  return provider === 'smtp' ? 'SMTP' : 'the custom email provider';
 };
 
 let customProvider: Promise<EmailProvider> | null = null;
@@ -46,7 +46,6 @@ const loadCustomProvider = async (settings: EmailSettings, options: Record<strin
 };
 
 const getEmailProvider = (settings: EmailSettings, options: Record<string, unknown>): Promise<EmailProvider> => {
-  if (settings.provider === 'resend') return Promise.resolve(createResendProvider(options));
   if (settings.provider === 'smtp') return Promise.resolve(createSmtpProvider(options));
   customProvider ??= loadCustomProvider(settings, options).catch((error) => {
     customProvider = null;

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

@@ -31,7 +31,7 @@ export const documentationMetadata = (source: Record<string, unknown>) => {
   return {
     title,
     description,
-    metaTitle: value('metaTitle') || title,
+    metaTitle: value('metaTitle'),
     metaDescription: value('metaDescription') || description,
   };
 };

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

@@ -21,7 +21,7 @@ import {
 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';
+import { getStorageProvider } from '../asset-storage';
 // A static import includes package defaults in each registry serverless bundle. A deployed function
 // cannot read the build machine's `config/docs` directory.
 import defaultPages from '../../generated/default-pages.json';
@@ -148,8 +148,7 @@ const searchRegistryPages = async (db: RegistryDatabase, request: PageSearchRequ
 export const createRegistryDocsBackend = async (): Promise<DocsBackend> => {
   const connection = await getRegistryConnection();
   const { db } = connection;
-  // Inject the storage-adapter resolver so object-backed asset content resolves by provider id.
-  const store = createRegistryStore({ db, resolveAssetAdapter: getAssetStorageAdapter });
+  const store = createRegistryStore({ db, resolveStorageProvider: getStorageProvider });
 
   return {
     async listComponents() {

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

@@ -2,9 +2,9 @@ import fs from 'fs-extra';
 import path from 'path';
 import type { RuntimeMode } from '@handoff/types/config';
 import { DEFAULT_DATABASE_URL_ENV, DEFAULT_REGISTRY_DRIVER, type RegistryDatabaseDriver } from '@handoff/registry/db/driver';
-import { DEFAULT_ASSET_STORAGE_ADAPTER, type AssetStorageSettings } from '@handoff/registry/asset-storage/resolve';
+import { DEFAULT_ASSET_STORAGE_PROVIDER, type AssetStorageSettings } from '@handoff/registry/asset-storage/resolve';
 import { mergeAiConnections, parseAiConnections, type AiSettings } from '@handoff/ai/connections';
-import { DEFAULT_EMAIL_PROVIDER, parseEmailSettings, type EmailSettings } from '@handoff/registry/email/resolve';
+import { parseEmailSettings, type EmailSettings } from '@handoff/registry/email/resolve';
 
 /**
  * Server-side runtime resolution for the docs read API.
@@ -41,7 +41,7 @@ export interface ServerRuntimeConfig {
   ai: AiSettings;
   registry: ServerRegistryRuntimeConfig;
   /**
-   * Asset storage adapter, module, and options for registry mode. Options hold `{ $env }` references,
+   * Asset storage provider, module, and options for registry mode. Options hold `{ $env }` references,
    * never secret values.
    */
   assetStorage: AssetStorageSettings;
@@ -60,13 +60,13 @@ const defaults = (): ServerRuntimeConfig => ({
     driver: DEFAULT_REGISTRY_DRIVER,
     databaseUrlEnv: DEFAULT_DATABASE_URL_ENV,
   },
-  assetStorage: { adapter: DEFAULT_ASSET_STORAGE_ADAPTER },
-  email: { provider: DEFAULT_EMAIL_PROVIDER, options: {} },
+  assetStorage: { provider: DEFAULT_ASSET_STORAGE_PROVIDER },
+  email: { options: {} },
 });
 
 /** Parse the baked asset-storage selection from env (names/selectors only; JSON options tolerated). */
 const assetStorageFromEnv = (): AssetStorageSettings => {
-  const adapter = process.env.HANDOFF_ASSET_STORAGE_ADAPTER?.trim();
+  const provider = process.env.HANDOFF_ASSET_STORAGE_PROVIDER?.trim();
   let options: Record<string, unknown> | undefined;
   const rawOptions = process.env.HANDOFF_ASSET_STORAGE_OPTIONS?.trim();
   if (rawOptions) {
@@ -79,7 +79,7 @@ const assetStorageFromEnv = (): AssetStorageSettings => {
   }
   const maxInline = Number(process.env.HANDOFF_ASSET_STORAGE_MAX_INLINE_BYTES);
   return {
-    adapter: adapter === 'custom' ? adapter : DEFAULT_ASSET_STORAGE_ADAPTER,
+    provider: provider === 'custom' ? provider : DEFAULT_ASSET_STORAGE_PROVIDER,
     module: process.env.HANDOFF_ASSET_STORAGE_MODULE?.trim() || undefined,
     maxInlineBytes: Number.isFinite(maxInline) && maxInline > 0 ? maxInline : undefined,
     options,
@@ -167,7 +167,7 @@ export const getServerRuntimeConfig = (): ServerRuntimeConfig => {
           ? parsed.registry.databaseUrlEnv.trim()
           : DEFAULT_DATABASE_URL_ENV;
       const assetStorage: AssetStorageSettings =
-        parsed?.assetStorage && typeof parsed.assetStorage === 'object' ? parsed.assetStorage : { adapter: DEFAULT_ASSET_STORAGE_ADAPTER };
+        parsed?.assetStorage && typeof parsed.assetStorage === 'object' ? parsed.assetStorage : { provider: DEFAULT_ASSET_STORAGE_PROVIDER };
       cached = {
         mode: parsed?.mode === 'registry' ? 'registry' : 'workspace',
         mcp: parsed?.mcp !== false,

package/src/app/lib/mcp/components.ts

@@ -1,10 +1,9 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
 import { buildArtifactUrl } from '@handoff/artifacts/url';
 import type { SlotMetadata } from '@handoff/transformers/preview/component';
 import type { ComponentListObject, OptionalPreviewRender, TransformComponentTokensResult } from '@handoff/transformers/preview/types';
 import type { DocsBackend } from '../docs-api/backend';
 import { basePath, fail, ok, read } from './result';
+import { defineTool, type McpTool } from './tool';
 
 /** The component tools: search, read, one preview, and the source. */
 
@@ -16,10 +15,12 @@ const MAX_SEARCH_LIMIT = 100;
 const SOURCE_FIELDS = ['code', 'css', 'sass', 'js'] as const;
 type SourceField = (typeof SOURCE_FIELDS)[number];
 
-export const registerComponentTools = (server: McpServer): void => {
-  server.registerTool(
-    'handoff_search_components',
+const componentId = { type: 'string', description: 'Component id, as returned by handoff_search_components.' };
+
+export const componentTools: McpTool[] = [
+  defineTool<{ query?: string; group?: string; category?: string; tag?: string; limit?: number }>(
     {
+      name: 'handoff_search_components',
       title: 'Search components',
       description:
         'Find components. `query` matches id, title, group, categories and tags. With no arguments, ' +
@@ -27,11 +28,14 @@ export const registerComponentTools = (server: McpServer): void => {
         'tags. Read one component with handoff_get_component.',
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: {
-        query: z.string().optional().describe('Text to find. Case-insensitive substring match.'),
-        group: z.string().optional().describe('Group name, for example "Form Elements". Exact match, case-insensitive.'),
-        category: z.string().optional().describe('Category name. Exact match, case-insensitive.'),
-        tag: z.string().optional().describe('Tag name. Exact match, case-insensitive.'),
-        limit: z.number().int().min(1).max(MAX_SEARCH_LIMIT).optional().describe(`Max results (default ${DEFAULT_SEARCH_LIMIT}).`),
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Text to find. Case-insensitive substring match.' },
+          group: { type: 'string', description: 'Group name, for example "Form Elements". Exact match, case-insensitive.' },
+          category: { type: 'string', description: 'Category name. Exact match, case-insensitive.' },
+          tag: { type: 'string', description: 'Tag name. Exact match, case-insensitive.' },
+          limit: { type: 'integer', minimum: 1, maximum: MAX_SEARCH_LIMIT, description: `Max results (default ${DEFAULT_SEARCH_LIMIT}).` },
+        },
       },
     },
     async ({ query, group, category, tag, limit }) =>
@@ -42,11 +46,11 @@ export const registerComponentTools = (server: McpServer): void => {
         const components = matched.slice(0, limit ?? DEFAULT_SEARCH_LIMIT).map(toComponentSummary);
         return ok({ total: matched.length, returned: components.length, components });
       })
-  );
+  ),
 
-  server.registerTool(
-    'handoff_get_component',
+  defineTool<{ id: string }>(
     {
+      name: 'handoff_get_component',
       title: 'Get component',
       description:
         'One component: properties, variants, usage and guidelines. `usage` is the snippet of the first ' +
@@ -56,9 +60,7 @@ export const registerComponentTools = (server: McpServer): void => {
         'handoff_get_component_preview. `tokens.set`, when present, is the id to pass to ' +
         'handoff_get_tokens. Do not derive a token set id from the component id.',
       annotations: { readOnlyHint: true, openWorldHint: false },
-      inputSchema: {
-        id: z.string().describe('Component id, as returned by handoff_search_components.'),
-      },
+      inputSchema: { type: 'object', properties: { id: componentId }, required: ['id'] },
     },
     async ({ id }) =>
       read(`component "${id}"`, async (backend) => {
@@ -76,19 +78,23 @@ export const registerComponentTools = (server: McpServer): void => {
           )
         );
       })
-  );
+  ),
 
-  server.registerTool(
-    'handoff_get_component_preview',
+  defineTool<{ id: string; preview: string }>(
     {
+      name: 'handoff_get_component_preview',
       title: 'Get component preview',
       description:
         'One state of a component: `values` (the args), `usage` (the snippet) and `html` (the rendered ' +
         'markup). `html` is absent when the component is not built.',
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: {
-        id: z.string().describe('Component id, as returned by handoff_search_components.'),
-        preview: z.string().describe('Preview id, as listed in `previews[].id` by handoff_get_component.'),
+        type: 'object',
+        properties: {
+          id: componentId,
+          preview: { type: 'string', description: 'Preview id, as listed in `previews[].id` by handoff_get_component.' },
+        },
+        required: ['id', 'preview'],
       },
     },
     async ({ id, preview }) =>
@@ -108,20 +114,18 @@ export const registerComponentTools = (server: McpServer): void => {
         }
         return ok(toPreviewResult(record, preview, found, basePath(), await readPreviewDocument(backend, id, preview)));
       })
-  );
+  ),
 
-  server.registerTool(
-    'handoff_get_component_source',
+  defineTool<{ id: string }>(
     {
+      name: 'handoff_get_component_source',
       title: 'Get component source',
       description:
         'The implementation of a component: `code` (the component or template) and, when present, ' +
         '`css`, `sass` and `js`. Use it only when handoff_get_component is not enough. The source ' +
         'fields are absent when the component is not built.',
       annotations: { readOnlyHint: true, openWorldHint: false },
-      inputSchema: {
-        id: z.string().describe('Component id, as returned by handoff_search_components.'),
-      },
+      inputSchema: { type: 'object', properties: { id: componentId }, required: ['id'] },
     },
     async ({ id }) =>
       read(`source of component "${id}"`, async (backend) => {
@@ -131,8 +135,8 @@ export const registerComponentTools = (server: McpServer): void => {
         }
         return ok(toComponentSource(record, await readComponentArtifact(backend, id)));
       })
-  );
-};
+  ),
+];
 
 const componentNotFound = (id: string) =>
   fail(`Component "${id}" was not found. Use handoff_search_components to list the components that exist.`);

package/src/app/lib/mcp/pages.ts

@@ -1,16 +1,15 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
 import type { PageDetail } from '../docs-api/records';
 import { createSearchRequest, DEFAULT_RESULT_LIMIT, MAX_QUERY_LENGTH, MAX_RESULT_LIMIT, MAX_TERMS } from '../docs-api/search';
 import { pageIdFromUrl } from './page-url';
 import { fail, ok, read } from './result';
+import { defineTool, type McpTool } from './tool';
 
 /** The documentation page tools: search and read. */
 
-export const registerPageTools = (server: McpServer): void => {
-  server.registerTool(
-    'handoff_search_pages',
+export const pageTools: McpTool[] = [
+  defineTool<{ query: string; group?: string; limit?: number }>(
     {
+      name: 'handoff_search_pages',
       title: 'Search pages',
       description:
         'Search documentation pages by title, description and Markdown body. Returns ranked `results` ' +
@@ -18,14 +17,18 @@ export const registerPageTools = (server: McpServer): void => {
         'Read a page with handoff_get_page.',
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: {
-        query: z
-          .string()
-          .describe(
-            `Search text, at most ${MAX_QUERY_LENGTH} characters and ${MAX_TERMS} terms. Case-insensitive. ` +
-              'Terms shorter than two characters are ignored.'
-          ),
-        group: z.string().optional().describe('Page group name. Exact match, case-insensitive.'),
-        limit: z.number().int().min(1).max(MAX_RESULT_LIMIT).optional().describe(`Max results (default ${DEFAULT_RESULT_LIMIT}).`),
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description:
+              `Search text, at most ${MAX_QUERY_LENGTH} characters and ${MAX_TERMS} terms. Case-insensitive. ` +
+              'Terms shorter than two characters are ignored.',
+          },
+          group: { type: 'string', description: 'Page group name. Exact match, case-insensitive.' },
+          limit: { type: 'integer', minimum: 1, maximum: MAX_RESULT_LIMIT, description: `Max results (default ${DEFAULT_RESULT_LIMIT}).` },
+        },
+        required: ['query'],
       },
     },
     async ({ query, group, limit }) => {
@@ -35,11 +38,11 @@ export const registerPageTools = (server: McpServer): void => {
       }
       return read('pages', async (backend) => ok(await backend.searchPages({ ...parsed.request, group: group?.trim() || undefined })));
     }
-  );
+  ),
 
-  server.registerTool(
-    'handoff_get_page',
+  defineTool<{ url: string }>(
     {
+      name: 'handoff_get_page',
       title: 'Get page',
       description:
         'One documentation page by its URL from handoff_search_pages, for example /guides/setup, or / ' +
@@ -47,7 +50,11 @@ export const registerPageTools = (server: McpServer): void => {
         'external-link page, the external site is not fetched.',
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: {
-        url: z.string().describe('Internal route, without a base path, query string or fragment.'),
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'Internal route, without a base path, query string or fragment.' },
+        },
+        required: ['url'],
       },
     },
     async ({ url }) => {
@@ -63,8 +70,8 @@ export const registerPageTools = (server: McpServer): void => {
         return ok(toPageResult(page));
       });
     }
-  );
-};
+  ),
+];
 
 export const toPageResult = (page: PageDetail) => ({
   id: page.id,