typescript-sdk 服务端 Schema 库接入指南:ArkType、Valibot、JSON Schema 与校验器切换

原创2026-09-14 20:50:441,394 阅读
文章标签:后端MCP 服务MCP Clients人工智能WebSocketRPC框架

typescript-sdk 服务端 Schema 库接入指南:ArkType、Valibot、JSON Schema 与校验器切换

导读

本文讲解 typescript-sdk 服务端(@modelcontextprotocol/server)如何接入不同的 Schema 库来声明工具(tool)与提示词(prompt)的输入输出结构:ArkType、Zod 可直接使用,Valibot 需经 toStandardJsonSchema 包装,已有 JSON Schema 则用 fromJsonSchema 原样注册。文章同时深入 jsonSchemaValidator 的底层原理,说明默认校验器如何按运行时(Node.js 的 AJV / workerd 与浏览器的 @cfworker/json-schema)自动选择,以及如何通过 validators/ajv、validators/cf-worker 两个子路径手动替换。读完后你将能自由地为 MCP 服务端选择最合适的 Schema 体系,并理解参数校验、结构化输出校验与 elicitation 表单校验这三条校验路径的全部细节。

本文主体对应仓库文档 docs/advanced/schema-libraries.md,所有代码示例与源码证据均可在仓库中对应验证。

背景:SDK 的 Schema 统一抽象

registerTool 的 inputSchema、outputSchema 以及 prompt 的 argsSchema 接受任何实现了 Standard Schema(v1 规范)且能产出 JSON Schema 的对象。SDK 只依赖两条能力:

  1. 导出 JSON Schema —— 用于向模型(经 tools/list)宣传参数结构;
  2. 校验运行时数据 —— 在 handler 执行前校验入参、在结果离开发送前校验 structuredContent。

从这条规则出发,各类 Schema 库的接入方式差异就清晰了:Zod 与 ArkType 原生满足上述条件,直接传 schema 对象即可;Valibot 自身不提供 JSON Schema 导出,需要 @valibot/to-json-schema 包装;纯 JSON Schema 文档则用 fromJsonSchema 包装。底层支持这一抽象的接口定义在 packages/core-internal/src/validators/types.ts(jsonSchemaValidator.getValidator<T>(schema) 返回可多次调用的校验函数),Standard Schema 包装实现在 packages/core-internal/src/validators/fromJsonSchema.ts。

关于 v1 的原始 shape 写法

如果你是从 v1 迁移而来,注意原始 shape 写法(inputSchema: { name: z.string() })已被废弃,请改为直接传 schema 对象。迁移细节见 upgrade-to-v2.md。

用 ArkType Schema 注册工具

ArkType 天然符合 Standard Schema,无需任何包装,用法与 Zod 完全一致:

import { McpServer } from '@modelcontextprotocol/server';
import { type } from 'arktype';

const server = new McpServer({ name: 'schema-zoo', version: '1.0.0' });

server.registerTool(
    'greet',
    {
        description: 'Greet someone by name',
        inputSchema: type({ name: 'string', 'times?': '1 <= number.integer <= 5' })
    },
    async ({ name, times }) => ({
        content: [{ type: 'text', text: Array.from({ length: times ?? 1 }, () => `Hello, ${name}`).join('\n') }]
    })
);

这段代码演示了 ArkType 的类型语法('1 <= number.integer <= 5' 表示"1 到 5 之间的整数"),它属于 ArkType 的字符串定义风格,被 SDK 自动转换并理解。仅仅这一个 schema,SDK 就完成了三件事:

  • 推导出模型可见的 JSON Schema(注册后通过 tools/list 宣传);
  • 在 handler 运行前校验参数;
  • 推导 handler 参数的类型 —— name 是 string,times 是 number | undefined(因为 times? 可选)。

试着用超范围参数调用:greet 传 times: 99,SDK 会以 ArkType 自己的错误信息拒绝该调用,handler 根本不会执行:

{
  content: [
    {
      type: 'text',
      text: 'Input validation error: Invalid arguments for tool greet: times: times must be at most 5 (was 99)'
    }
  ],
  isError: true
}

注意拒绝结果是一个普通的工具结果(isError: true),模型可以读到错误信息并重试符合 schema 的参数。本页所有调用均来自连接该服务端的内存 Client,连接方式见 testing.md(对应示例中的 harness 部分,见 schema-libraries.examples.ts)。

用 Valibot Schema 注册工具

Valibot 不把 JSON Schema 转换能力挂在 schema 自身,需要显式用 @valibot/to-json-schema 的 toStandardJsonSchema 包装:

import { toStandardJsonSchema } from '@valibot/to-json-schema';
import * as v from 'valibot';

server.registerTool(
    'shout',
    { description: 'Greet someone, loudly', inputSchema: toStandardJsonSchema(v.object({ name: v.string() })) },
    async ({ name }) => ({ content: [{ type: 'text', text: `HELLO, ${name.toUpperCase()}` }] })
);

包装后,tools/list 会宣传 shout 及其派生的 JSON Schema,而每个到达 handler 的调用仍由 Valibot 解析校验(toStandardJsonSchema 产出的对象同时保留了 Valibot 的校验语义)。这是一种"JSON Schema 给模型看、Valibot 校验跑本地"的双轨模式,适合已经重度使用 Valibot 的既有代码库。

从已有的 JSON Schema 起步

如果你已经有手写或由 TypeBox 等库生成的 JSON Schema 文档,fromJsonSchema(从 @modelcontextprotocol/server 导出)可以把它包装后直接注册,完全绕开 Schema 库:

import { fromJsonSchema } from '@modelcontextprotocol/server';

server.registerTool(
    'farewell',
    {
        description: 'Say goodbye',
        inputSchema: fromJsonSchema<{ name: string }>({
            type: 'object',
            properties: { name: { type: 'string' } },
            required: ['name']
        })
    },
    async ({ name }) => ({ content: [{ type: 'text', text: `Goodbye, ${name}` }] })
);

tools/list 宣传的正是你传入的文档,原样不变:

{
  type: 'object',
  properties: { name: { type: 'string' } },
  required: [ 'name' ]
}

泛型参数 fromJsonSchema<{ name: string }> 用于给 handler 参数标注类型;省略时参数类型为 unknown(可在调用点自行断言)。

从源码看,packages/server/src/fromJsonSchema.ts 是 @modelcontextprotocol/core-internal 同名函数的薄包装:coreFromJsonSchema(schema, validator ?? new DefaultJsonSchemaValidator()),其中 DefaultJsonSchemaValidator 来自 @modelcontextprotocol/server/_shims —— 这就是"按运行时自动选择校验器"的入口(见下文)。核心实现(packages/core-internal/src/validators/fromJsonSchema.ts)在创建时立即 validator.getValidator<T>(schema) 编译出校验函数,并把它封装成 Standard Schema 对象:jsonSchema.input/output 返回原始文档,validate 调用编译好的校验器并把失败信息映射为标准 issues。这也是后面警告"fromJsonSchema 的校验器在创建时绑定"的原因。

用任意库校验结构化输出

outputSchema 与 prompt 的 argsSchema 遵循同一条 Standard Schema 规则。返回与 schema 匹配的值作为 structuredContent,与给人看的 content 并存:

server.registerTool(
    'measure',
    {
        description: 'Measure the length of a name',
        inputSchema: type({ name: 'string' }),
        outputSchema: type({ name: 'string', length: 'number' })
    },
    async ({ name }) => {
        const output = { name, length: name.length };
        return { content: [{ type: 'text', text: JSON.stringify(output) }], structuredContent: output };
    }
);

SDK 会在结果离开服务端前,用 ArkType schema 校验 structuredContent。用 { name: 'Ada' } 调用 measure,两种渲染都会返回:

{
  content: [ { type: 'text', text: '{"name":"Ada","length":3}' } ],
  structuredContent: { name: 'Ada', length: 3 }
}

structuredContent 是给机器消费的结构化数据,content 是给模型阅读的文本(或 image/audio 等其他内容块);二者可以不同,只要 structuredContent 通过 outputSchema 校验。结构化结果在协议线路上的编码随协议版本(era)而异,见 protocol-versions.md。

替换 JSON Schema 校验器:AJV 定制

服务端内置的 JSON Schema 校验器在两个地方运行:一是 fromJsonSchema 注册的 schema,二是 elicitation 表单响应。要定制 AJV 实例,从 validators/ajv 子路径导入 —— 它重新导出了 SDK 内部打包的 Ajv 与 addFormats,无需额外安装依赖(见 packages/server/src/validators/ajv.ts):

import { addFormats, Ajv, AjvJsonSchemaValidator } from '@modelcontextprotocol/server/validators/ajv';

const ajv = new Ajv({ strict: true, allErrors: true });
addFormats(ajv);
const validator = new AjvJsonSchemaValidator(ajv);

const strict = new McpServer({ name: 'schema-zoo', version: '1.0.0' }, { jsonSchemaValidator: validator });

现在 strict 这个服务端实例的 elicitation 表单响应将由你配置的 AJV 实例校验(strict: true 意味着对未知关键字等发出警告/报错,适合对 schema 质量要求高的场景)。

::: warning jsonSchemaValidator 选项只覆盖 elicitation 表单响应。fromJsonSchema 注册的 schema 在校验器在创建时就绑定了 —— 需要传入你自己的校验器作为第二个参数:fromJsonSchema(document, validator)。这与 packages/server/src/fromJsonSchema.ts 的实现一致:显式传入的 validator 优先级最高,未传才回落到默认运行时校验器。 :::

AJV 校验器的底层行为

从 packages/core-internal/src/validators/ajvProvider.ts 可以看到 AjvJsonSchemaValidator 的完整行为:

  • 默认配置:未传入自定义实例时,按 strict: false、validateFormats: true、validateSchema: false、allErrors: true 构造引擎并注册 ajv-formats,且懒加载 —— 引擎在第一次真正需要校验 schema 时才实例化,避免为从不做 JSON Schema 校验的服务端支付 AJV 初始化成本;
  • 按方言分派:根据 schema 声明的 $schema 选择引擎 —— 无 $schema 或 2020-12 用 Ajv2020,2019-09 用 Ajv2019,draft-07/draft-06 用经典 Ajv(draft-07 类),其他方言直接抛 Error,提示传入预配置实例;
  • 自定义实例优先:构造时传入 ajv 后,所有 schema 一律用该实例,方言选择权完全交给调用方(自带方言、自带配置);
  • $id 缓存:schema 带 $id 时优先 getSchema($id) 复用已编译校验器,否则 compile。

另外注意:SDK 内部打包了 ajv 但不重新导出 Ajv2020(其类型图会影响下游声明打包)。需要自建 2020-12 实例时,请自行添加与 SDK 锁定版本一致的 ajv 依赖并 import { Ajv2020 } from 'ajv/dist/2020.js' —— 直接用 new Ajv(...) 得到的是 draft-07 类,会静默降级方言。

按运行时选择校验器:默认行为与强制指定

不设置 jsonSchemaValidator 时,SDK 按运行时自动选择默认校验器:

  • Node.js:AJV(AjvJsonSchemaValidator);
  • workerd(Cloudflare Workers)与浏览器:@cfworker/json-schema(CfWorkerJsonSchemaValidator)。

这一分派通过 packages/server/src/shimsNode.ts 与 packages/server/src/shimsBrowser.ts 实现 —— 两者都把各自的实现导出为 DefaultJsonSchemaValidator,服务端构造函数 options?.jsonSchemaValidator ?? new DefaultJsonSchemaValidator()(见 packages/server/src/server/server.ts)据此取得运行时默认。@cfworker/json-schema 不依赖代码生成(无 eval/new Function),因此适合对动态执行有限制的边缘运行时。

想在任意运行时强制使用轻量实现,从 validators/cf-worker 子路径导入:

import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker';

const edge = new McpServer({ name: 'schema-zoo', version: '1.0.0' }, { jsonSchemaValidator: new CfWorkerJsonSchemaValidator() });

edge 的两条校验路径(fromJsonSchema 与 elicitation 表单)将统一走 @cfworker/json-schema,与运行时无关。

CfWorker 校验器的配置项

从 packages/core-internal/src/validators/cfWorkerProvider.ts 可以看到它接受两个可选配置:

  • shortcircuit:默认 true,遇到第一个错误即停止校验;设为 false 则收集全部错误(错误信息以 instanceLocation: error 拼接返回);
  • draft:显式强制 JSON Schema 方言('4' | '7' | '2019-09' | '2020-12')。设置后跳过 $schema 分派;未设置时按 schema 声明的 $schema 分派(无 $schema 或 2020-12 视为 '2020-12',其他未知方言抛 Error)。

两种校验器的已知差异

源码注释记录了引擎间的一个行为差异:经典 AJV(draft-07)会校验紧邻 $ref 的关键字(比 draft-07 规范"忽略兄弟关键字"更严格,与 v1 默认引擎一致),而 cfworker 实现按规范忽略它们。另一个已知差距:@cfworker/json-schema 在 draft-07 的 dependencies 关键字上存在 $ref 收集限制(依赖键与 JSON Schema 关键字同名且子 schema 含 $ref 时,触发依赖会抛 Unresolved $ref),该偏差由录制契约测试固定。若你的 schema 依赖这些边界行为,建议在目标运行时用真实数据验证一遍。

小结

  • inputSchema、outputSchema 与 prompt 的 argsSchema 接受任何能导出 JSON Schema 的 Standard Schema —— Zod 与 ArkType 直接用,Valibot 经 @valibot/to-json-schema 包装;
  • 原始 shape 写法(inputSchema: { name: z.string() })已废弃,请传 schema 对象;
  • fromJsonSchema(document) 注册已有的 JSON Schema,泛型参数标注 handler 参数类型(省略则为 unknown);
  • 服务端选项 jsonSchemaValidator 只替换 elicitation 表单响应的校验器;fromJsonSchema 自带校验器,作为第二个参数传入 fromJsonSchema(document, validator);
  • 默认校验器按运行时选择 —— Node.js 用 AJV,workerd 与浏览器用 @cfworker/json-schema;validators/ajv 与 validators/cf-worker 两个子路径可强制指定其一(AJV 分支还支持自定义引擎与方言分派,cf-worker 分支支持 shortcircuit 与 draft 配置)。

更完整的可运行示例(含内存 Client 驱动、所有输出逐字对照)见 examples/guides/advanced/schema-libraries.examples.ts;工具注册的整体能力(title、annotations、混合内容块等)见 docs/servers/tools.md。

登录后查看全文
typescript-sdk