在 mcp-use 中使用 Zod、ArkType 与 TypeBox 定义 MCP 工具输入 Schema：同款 greet 工具的三种校验器实现

在 mcp-use 中使用 Zod、ArkType 与 TypeBox 定义 MCP 工具输入 Schema同款 greet 工具的三种校验器实现【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址: https://gitcode.com/gh_mirrors/mc/mcp-use本指南以 mcp-use 仓库中的 schema-validators 示例 为主体完整展示同一个带输入校验的greetMCP 工具如何分别用 Zod、ArkType 与 TypeBox 三种 schema 校验器构建并深入mcp-use服务端源码说明inputSchema字段、StandardSchemaWithJSON标准以及校验在工具回调执行前发生的底层机制。读完本文你将掌握在mcp-useTypeScript 服务中接入任意主流 schema 库、写出可被 LLM 正确理解的工具参数定义并完成本地启动与联调验证的完整方法。示例概览三种校验器一个greet工具examples/typescript/schema-validators目录下并排存放着三个结构完全对称的独立 npm 工程arktype/— 使用 ArkTypearktype: ^2.2.3typebox/— 使用 TypeBoxtypebox: 1.3.6并搭配modelcontextprotocol/server: 2.0.0的 JSON Schema 转换工具zod/— 使用 Zodzod: ^4.4.3三个工程都声明了相同的mcp-use: ^2.0.4依赖、相同的type: module与相同的脚本集合dev/build/start/typecheck。它们实现的是同一个服务器一个名为greet、输入受校验的工具返回一段问候文本。这样并排组织的用意在于让读者可以零成本地对比同一功能在不同校验器下的写法差异从而根据自己的团队技术栈做出选择。逐版本解读同一功能的三种 Schema 写法Zod 版本z.objectdescribezod/src/index.ts 的完整实现如下import { MCPServer } from mcp-use; import { z } from zod; const server new MCPServer({ name: zod-schema-example, version: 1.0.0, description: Tool input validation with Zod., }); server.tool( { name: greet, inputSchema: z.object({ name: z.string().describe(Name to greet), }), }, async ({ name }) ({ content: [{ type: text, text: Hello from Zod, ${name}! }], }) ); export default server;关键点在于z.string().describe(Name to greet)字段描述通过.describe()挂载最终会成为 LLM 理解工具参数意图的提示信息详见下文源码分析。工具回调的入参{ name }类型由inputSchema自动推导全程享有 TypeScript 类型安全。ArkType 版本type(...)描述式语法arktype/src/index.ts 采用 ArkType 的字符串描述式 DSLimport { type } from arktype; import { MCPServer } from mcp-use; const server new MCPServer({ name: arktype-schema-example, version: 1.0.0, description: Tool input validation with ArkType., }); server.tool( { name: greet, inputSchema: type({ name: type(string).describe(Name to greet), }), }, async ({ name }) ({ content: [{ type: text, text: Hello from ArkType, ${name}! }], }) ); export default server;ArkType 的type({ name: type(string) })与 Zod 的z.object({ name: z.string() })结构几乎一一对应字段描述同样是.describe(...)。两者写法的亲缘性很高从 Zod 迁移到 ArkType 的成本很低。TypeBox 版本Type.ObjectfromJsonSchema显式转换typebox/src/index.ts 是三者中唯一需要显式 JSON Schema 转换的版本import { fromJsonSchema } from modelcontextprotocol/server; import { MCPServer } from mcp-use; import Type from typebox; const server new MCPServer({ name: typebox-schema-example, version: 1.0.0, description: Tool input validation with TypeBox., }); const greetInput Type.Object({ name: Type.String({ description: Name to greet }), }); server.tool( { name: greet, inputSchema: fromJsonSchemaType.Statictypeof greetInput(greetInput), }, async ({ name }) ({ content: [{ type: text, text: Hello from TypeBox, ${name}! }], }) ); export default server;TypeBox 把 schema 描述为Type.Object({ name: Type.String({ description: ... }) })描述以选项对象形式传递而非链式.describe()。fromJsonSchema来自modelcontextprotocol/serverTypeBox 1.x 输出为 JSON Schema将其转换为 mcp-use 所需的StandardSchemaWithJSON结构Type.Statictypeof greetInput则用于保证转换后的 schema 与回调入参类型一致。这一差异恰好说明不同校验器在 mcp-use 中接线的标准是统一的只是个别库需要一层显式的桥接转换。运行与联调从npm run dev到/mcp端点schema-validators的 README 给出了通用运行方式以 zod 为例其余两个工程操作完全一致cd zod npm install npm run devdev脚本执行的是mcp-use dev命令。从 CLI 源码看开发服务器默认监听$PORT环境变量指定的端口未设置时回落到3000并且dev模式在端口被占用时会自动向上探测新端口同时打印提示见 libraries/typescript/packages/cli/src/cli/dev.ts#L378-L385 中的[mcp-use] port ${requested} is taken, using ${port}。因此 README 中说连接http://localhost:3000/mcp是默认情形——若日志提示端口已被占用请以实际打印的端口为准。启动后用任意 MCP 客户端或 mcp-use Inspector连接端点http://localhost:3000/mcp工具greet调用参数{ name: Ada }三个版本的服务器都会返回一段问候文本例如Hello from Zod, Ada!ArkType/TypeBox 版本返回相应前缀的文本。若传入的参数不符合 schema例如name缺失或类型为数字输入校验会在工具回调执行之前被拦截并返回校验错误——这正是本示例所演示的核心价值让 MCP 工具的参数契约由 schema 强制保证而非在业务代码里手写判断。除dev外package.json还提供了mcp-use build构建产物与mcp-use start以生产模式启动、tsc --noEmit类型检查等脚本便于从开发到部署的完整链路。源码纵深inputSchema与StandardSchemaWithJSON为什么三个完全不同的库能无缝接入同一个server.tool()答案在 mcp-use 服务端的工具定义类型中。查看 libraries/typescript/packages/server/src/tools.ts#L53-L80 的ToolDefinition接口export interface ToolDefinition { name: string; title?: string; description?: string; /** 支持任何实现了 Standard Schema 且可转换 JSON Schema 的库zod v4、ArkType、Valibot …… */ inputSchema?: StandardSchemaWithJSON; /** inputSchema 的别名新代码推荐使用 inputSchema与 MCP 线上字段名一致 */ schema?: StandardSchemaWithJSON; outputSchema?: StandardSchemaWithJSON; annotations?: ToolAnnotations; ... }inputSchema的类型是StandardSchemaWithJSON它来自modelcontextprotocol/server是“Standard Schema JSON Schema 转换能力”的统一抽象。源码注释明确列举了该协议兼容的库zod v4、ArkType、Valibot 等。因此本示例中的 Zod 4zod: ^4.4.3与 ArkType 2arktype: ^2.2.3都可以直接传入而无需桥接TypeBox 由于不直接暴露 Standard Schema 接口才需要通过fromJsonSchema做一次转换——这正是三种写法存在差异的根本原因。工具定义同时支持inputSchema与历史别名schema二者的优先级由 resolveToolInputSchema 决定同时设置时inputSchema胜出。服务器在注册工具时会调用该函数解析最终 schema并在回调执行前完成校验见 libraries/typescript/packages/server/src/server.ts#L1953-L1997 中resolveToolInputSchema(definition)与校验逻辑校验通过后才会进入你的回调函数。类型层面的闭环同样值得注意InferToolInput见 tools.ts#L162-L175会从inputSchema推导回调参数类型——所以你不需要手写{ name: string }的入参注解TypeScript 会自动把回调里的{ name }推导为string类型schema 即单一事实来源。此外字段描述Zod/ArkType 的.describe(...)、TypeBox 的description选项会随 schema 一起出现在工具描述信息中成为 LLM 选择与填参的依据因此为每个字段编写清晰、面向模型的描述是提升 MCP 工具可用性的关键实践。小结与选型建议本示例的核心结论可以归纳为三点Schema 无关mcp-use 通过StandardSchemaWithJSON统一接纳 zod v4、ArkType、Valibot 等 Standard Schema 库TypeBox 等非 Standard Schema 库则可用fromJsonSchema显式桥接校验前置工具输入在回调执行前即完成校验业务代码无需重复防御类型闭环回调参数类型由inputSchema自动推导schema 与实现天然一致。选型上追求极简上手与生态成熟可选 Zod偏好编译期极致性能与描述式语法可选 ArkType团队已有 JSON Schema 基础设施或需要与 OpenAPI/配置体系打通时可选 TypeBox。三种方案都可在本仓库的 schema-validators 目录 中直接npm install npm run dev对照体验选择最契合团队习惯的那一种即可。【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址: https://gitcode.com/gh_mirrors/mc/mcp-use创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考