Schema - wangshengliang

Schema 是 MCP 中核心要素之一，定义了各类 JSON‑RPC 请求与响应的 结构、校验规则与类型安全。

Zod#

Zod 是一个现代的、TypeScript 优先的 模式验证库（schema validation library），它在前端（如表单校验、API 参数校验）和后端（如请求校验、配置文件验证、自动生成 JSON Schema）中都非常流行。

快速上手

import { z } from 'zod'
const userSchema = z.object({
  name: z.string(),
  age: z.number(),
})

const input = { name: '张三', age: 30 }

const result = userSchema.safeParse(input)

if (result.success) {
  console.log('合法数据', result.data)
} else {
  console.error('校验失败', result.error.format())
}

zod 对象上面的方法：

.partial(): 所有字段都变为可选

const PartialUser = userSchema.partial()

.pick() 和 .omit()

userSchema.pick({ name: true }) // 只保留 name 字段
userSchema.omit({ age: true }) // 移除 age 字段

.merge(): 合并两个对象 schema

const schemaA = z.object({ a: z.string() })
const schemaB = z.object({ b: z.number() })
const merged = schemaA.merge(schemaB) // { a: string, b: number }

常用 Zod 类型

类型	写法	说明
字符串	`z.string()`	可链 `.min(n)`、`.max(n)`、`.email()` 等
数字	`z.number()`	可链 `.int()`、`.positive()`、`.gte(n)`
布尔值	`z.boolean()`
日期	`z.date()`
数组	`z.array(z.string())`	表示字符串数组
对象	`z.object({})`	用于定义结构
可选字段	`.optional()`	表示字段可缺省
可以为 null	`.nullable()`
联合类型	`z.union([z.string(), z.number()])`
枚举	`z.enum(["A", "B", "C"])`

其它能力

转换

const TrimmedString = z.string().transform((str) => str.trim())

默认值

const WithDefault = z.string().default('hello')

自定义校验

const Password = z.string().refine((p) => p.length >= 8, {
  message: '密码至少 8 位',
})

Schema#

MCP 里面提供了一组 Schema.

Schema 由 TypeScript + Zod 定义，制作成 JSON Schema，用于验证协议消息结构。

在 SDK 中，每个 JSON‑RPC 方法（如 resources/list、tools/call）都对应相应的 Zod Schema，比如：

ReadResourceRequestSchema
ListResourcesRequestSchema
CallToolRequestSchema
ListPromptsRequestSchema

这些 schema 的功能包括：

校验请求结构 严格保证参数类型与字段是否存在；
生成 TS 类型，提高类型安全；
生成 JSON Schema，用于能力声明或与客户端协商能力。

例如 ReadResourceRequestSchema 实际就等价于：

const ReadResourceRequestSchema = z.object({
  method: z.literal('resources/read'),
  params: z.object({
    uri: z
      .string()
      .describe('资源的 URI，格式如 file://、http://、bananaphone://'),
  }),
})

因此 MCP 提供的 Schema 可以调用 zod 对象上面的方法：

import { ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js'

// 模拟请求参数
const requestParams = {
  method: 'resources/read',
  params: {
    uri: 'bananaphone://info',
  },
}
// 校验请求
const result = ReadResourceRequestSchema.safeParse(requestParams)

if (!result.success) {
  console.error('参数格式不对:', result.error.format())
} else {
  console.log('✅ 参数合法:', result.data)
}

常见请求 Schema 结构一览

功能	Schema 名	结构
读取资源	`ReadResourceRequestSchema`	`{ method: "resources/read", params: { uri } }`
列出资源	`ListResourcesRequestSchema`	`{ method: "resources/list", params: {} }`
列出资源模板	`ListResourceTemplatesRequestSchema`	`{ method: "resources/templates", params: {} }`
列出工具	`ListToolsRequestSchema`	`{ method: "tools/list", params: {} }`
调用工具	`CallToolRequestSchema`	`{ method: "tools/call", params: { function, args } }`
列出提示词	`ListPromptsRequestSchema`	`{ method: "prompts/list", params: {} }`
调用提示词	`CallPromptRequestSchema`	`{ method: "prompts/call", params: { id, input } }`

setRequestHandler#

这是 MCP SDK 提供的底层方法，用于注册对某个 JSON-RPC 请求类型 的处理函数。

MCP 使用 JSON-RPC 2.0 协议，客户端发送：

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": { ... }
}

SDK 内部为每种 method 提供一个对应的 Schema，setRequestHandler() 会：

接收请求：拦截特定 method（如 "tools/list"）
用 Schema 校验请求结构：如果校验失败，返回错误；否则进入 handler
执行你的 handlerFunction：将 params 提供给你处理逻辑
将你的返回值转为标准 JSON-RPC 响应：自动处理错误、封装 result 字段

server.setRequestHandler(SomeRequestSchema, async (request) => {
  const params = request.params

  // 做点什么
  return {
    ...yourResponseObject,
  }
})

课堂练习

通过 setRequestHandler 注册工具。

-EOF-