handoff-app 2.0.0-11 → 2.0.0-12

package/dist/app-builder/build.js

@@ -510,7 +510,7 @@ 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 MCP SDK
- * (and its `zod` peer) is only needed when `/api/mcp/` is enabled; the driver package is
+ * 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); the
  * SMTP email provider needs `nodemailer`.
  */
@@ -520,7 +520,7 @@ const getRequiredRegistryRuntimeModules = (handoff) => {
     // The assistant runs the MCP tools in-process, so it needs the MCP SDK whether or not the HTTP
     // endpoint is served.
     if ((0, config_1.isMcpEnabled)(handoff.config) || ai.enabled) {
-        base.push('@modelcontextprotocol/sdk', 'zod');
+        base.push('@modelcontextprotocol/sdk');
     }
     if (ai.enabled) {
         base.push('ai', '@ai-sdk/openai-compatible');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "2.0.0-11",
+  "version": "2.0.0-12",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",
@@ -167,8 +167,7 @@
     "vaul": "^1.1.2",
     "vite": "^6.3.5",
     "ws": "^8.18.3",
-    "yargs": "^17.7.2",
-    "zod": "^4.4.3"
+    "yargs": "^17.7.2"
   },
   "peerDependencies": {
     "typescript": ">=5.6 <7"

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,

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

@@ -1,7 +1,10 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { registerComponentTools } from './components';
-import { registerPageTools } from './pages';
-import { registerTokenTools } from './tokens';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
+import { componentTools } from './components';
+import { pageTools } from './pages';
+import { fail } from './result';
+import { tokenTools } from './tokens';
 
 /**
  * The Handoff MCP server: read-only access to the design system's components, tokens and pages.
@@ -21,10 +24,19 @@ import { registerTokenTools } from './tokens';
 /** Version of the MCP surface itself, reported in `initialize`. Bump when a tool contract changes. */
 const MCP_SERVER_VERSION = '2.0.0';
 
-export const createMcpServer = (): McpServer => {
-  const server = new McpServer(
+const tools = [...componentTools, ...tokenTools, ...pageTools];
+
+/** Compiled once per process, not per request. */
+const validator = new AjvJsonSchemaValidator();
+const toolsByName = new Map(
+  tools.map((tool) => [tool.definition.name, { ...tool, validate: validator.getValidator(tool.definition.inputSchema) }])
+);
+
+export const createMcpServer = (): Server => {
+  const server = new Server(
     { name: 'handoff', version: MCP_SERVER_VERSION },
     {
+      capabilities: { tools: {} },
       instructions:
         'Design-system knowledge for this project. Before writing UI code, find an existing component ' +
         'with handoff_search_components and read it with handoff_get_component. Take colors, typography ' +
@@ -33,8 +45,20 @@ export const createMcpServer = (): McpServer => {
     }
   );
 
-  registerComponentTools(server);
-  registerTokenTools(server);
-  registerPageTools(server);
+  server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: tools.map((tool) => tool.definition) }));
+
+  // Unknown tools and invalid arguments are tool errors, so the agent can read them and retry.
+  server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+    const tool = toolsByName.get(params.name);
+    if (!tool) {
+      return fail(`Tool "${params.name}" was not found.`);
+    }
+    const args = tool.validate(params.arguments ?? {});
+    if (!args.valid) {
+      return fail(`Invalid arguments for tool "${params.name}": ${args.errorMessage}.`);
+    }
+    return tool.run(args.data);
+  });
+
   return server;
 };

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

@@ -1,15 +1,16 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
 import type { TokenArtifactResource } from '@handoff/store';
 import type { DocsBackend, TokenSetDetail } from '../docs-api/backend';
 import { fail, ok, read } from './result';
+import { defineTool, type McpTool } from './tool';
 
 /** The token tool, and the reshaping that turns stored token sets into variables an agent can emit. */
 
-export const registerTokenTools = (server: McpServer): void => {
-  server.registerTool(
-    'handoff_get_tokens',
+type TokenFormat = 'css' | 'scss' | 'styleDictionary' | 'types';
+
+export const tokenTools: McpTool[] = [
+  defineTool<{ set?: string; kind?: 'foundation' | 'component'; format?: TokenFormat }>(
     {
+      name: 'handoff_get_tokens',
       title: 'Get design tokens',
       description:
         'Design tokens. With no arguments: the list of token sets, plus all foundation tokens (colors, ' +
@@ -20,15 +21,20 @@ export const registerTokenTools = (server: McpServer): void => {
         'stylesheet is available.',
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: {
-        set: z.string().optional().describe('Token set id from the list, for example "foundation/colors".'),
-        kind: z
-          .enum(['foundation', 'component'])
-          .optional()
-          .describe('Without `set`: list only sets of this kind. `component` leaves out the foundation tokens.'),
-        format: z
-          .enum(['css', 'scss', 'styleDictionary', 'types'])
-          .optional()
-          .describe('With `set`: return the generated file in this format.'),
+        type: 'object',
+        properties: {
+          set: { type: 'string', description: 'Token set id from the list, for example "foundation/colors".' },
+          kind: {
+            type: 'string',
+            enum: ['foundation', 'component'],
+            description: 'Without `set`: list only sets of this kind. `component` leaves out the foundation tokens.',
+          },
+          format: {
+            type: 'string',
+            enum: ['css', 'scss', 'styleDictionary', 'types'] satisfies TokenFormat[],
+            description: 'With `set`: return the generated file in this format.',
+          },
+        },
       },
     },
     async ({ set, kind, format }) =>
@@ -57,8 +63,8 @@ export const registerTokenTools = (server: McpServer): void => {
         }
         return ok({ id: detail.id, kind: detail.kind, format, path: artifact.path, content: artifact.content });
       })
-  );
-};
+  ),
+];
 
 /**
  * A token set's payload, under a key naming which of the four forms it is, so the agent never has to

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

@@ -0,0 +1,19 @@
+import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * One MCP tool: its listing, with a plain JSON Schema for its input, and its handler.
+ *
+ * Plain JSON Schema keeps Zod out of the app. The Next build type-checks this code against the
+ * consumer's `node_modules`, where a second Zod copy makes the SDK's Zod types incompatible with ours.
+ */
+export interface McpTool {
+  definition: Tool;
+  /** Runs with arguments already validated against `definition.inputSchema`. */
+  run: (args: unknown) => Promise<CallToolResult>;
+}
+
+/** `Args` must match `definition.inputSchema`; the server validates against the schema before `run`. */
+export const defineTool = <Args>(definition: Tool, run: (args: Args) => Promise<CallToolResult>): McpTool => ({
+  definition,
+  run: run as McpTool['run'],
+});

package/src/app-builder/build.ts

@@ -582,7 +582,7 @@ 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 MCP SDK
- * (and its `zod` peer) is only needed when `/api/mcp/` is enabled; the driver package is
+ * 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); the
  * SMTP email provider needs `nodemailer`.
  */
@@ -592,7 +592,7 @@ const getRequiredRegistryRuntimeModules = (handoff: Handoff): string[] => {
   // The assistant runs the MCP tools in-process, so it needs the MCP SDK whether or not the HTTP
   // endpoint is served.
   if (isMcpEnabled(handoff.config) || ai.enabled) {
-    base.push('@modelcontextprotocol/sdk', 'zod');
+    base.push('@modelcontextprotocol/sdk');
   }
   if (ai.enabled) {
     base.push('ai', '@ai-sdk/openai-compatible');