MCP Tool Schema Generator 用于为 MCP 工具的输入参数生成完整的 JSON Schema 定义，并针对 AI 消费进行优化，包含清晰的描述、类型约束与校验规则。
主要能力
- 为工具输入生成 JSON Schema
- 从 schema 生成 TypeScript 类型
- 生成 Zod 校验 schema
- 生成面向 AI 优化的描述
- 支持复杂的嵌套结构
- 支持枚举、联合类型和约束
使用方式
在以下场景调用该技能：
- 为 MCP 工具定义输入 schema
- 创建类型安全的工具参数定义
- 生成工具输入的校验逻辑
- 为 AI 消费编写工具参数文档
输入参数
- toolName（string，必填）：MCP 工具的名称
- description（string，必填）：工具描述
- parameters（array，必填）：参数定义列表
- outputFormat（string，选填）：json-schema、zod 或 typescript（默认：全部）
- examples（array，选填）：用于文档的示例输入
参数定义结构
参数定义以数组形式提供，每个参数包含 name、type、description、required，可选 constraints（如 pattern、maxLength）、default、enum、properties（用于 object 嵌套）等字段。示例中展示了 path（string，必填，带 pattern 与 maxLength 约束）、encoding（string，选填，带 enum 与 default）、options（object，选填，含 maxSize、follow 属性）三类参数的定义方式。
输出结构
生成结果按工具名归档于 schemas/<toolName>/ 目录下，包含：
- schema.json：JSON Schema 定义
- schema.ts：TypeScript 类型
- validation.ts：Zod 校验 schema
- examples.json：示例输入
- README.md：schema 文档
生成的代码模式
JSON Schema 输出：生成符合 draft 2020-12 的 schema，包含 $schema、$id、title、description、type、properties、required、additionalProperties 等字段，并在属性中携带描述、约束和 examples。
TypeScript 类型输出：生成带 JSDoc 注释的 interface，注释中标注描述、pattern、maxLength、default、minimum、maximum、example 等信息。
Zod 校验输出：生成对应的 Zod schema（如 z.object、z.string().regex().max()、z.enum().optional().default() 等），并使用 strict()，同时通过 z.infer 导出类型。
支持的类型
string、number、integer、boolean、array、object、enum、null、union，分别映射到对应的 JSON Schema、TypeScript 与 Zod 表达方式。
支持的约束
minLength、maxLength、pattern、format、minimum、maximum、multipleOf、minItems、maxItems、uniqueItems，分别适用于 string、number、array 等类型，并映射到 JSON Schema 与 Zod 的对应写法。
面向 AI 优化的描述
生成的描述针对 AI 消费进行优化，包含：明确用途、有效取值、示例、约束、默认值。例如描述参数用途、支持绝对或相对路径、支持 Unix 与 Windows 路径格式、最大长度以及具体示例。
工作流程
- 解析参数——校验参数定义
- 推断类型——确定 TypeScript/Zod 类型
- 生成 JSON Schema——创建 draft 2020-12 schema
- 生成 TypeScript——创建 interface 定义
- 生成 Zod schema——创建校验代码
- 创建示例——生成有效示例输入
- 编写文档——创建带使用说明的 README
遵循的最佳实践
- 遵循 JSON Schema draft 2020-12
- 严格模式（additionalProperties: false）
- 为 AI 提供全面的描述
- 类型安全的 TypeScript interface
- 使用 Zod 进行运行时校验
- 为每个参数提供示例输入
参考资料
- JSON Schema 规范：https://json-schema.org/
- MCP 工具文档：https://modelcontextprotocol.io/docs/tools
- Zod 文档：https://zod.dev/
目标流程
- mcp-tool-implementation
- mcp-tool-documentation
- argument-parser-setup