在MCP（模型上下文协议）的生态系统中，工具（Tools）是一种强大的扩展机制，允许AI模型执行各种操作并获取结果。本文将深入探讨MCP TypeScript-SDK中的工具开发基础，包括工具定义与参数验证、Zod模式详解与高级用法、异步工具处理与错误管理以及工具调用与结果格式化。通过学习这些内容，你将能够为你的MCP应用开发功能丰富、安全可靠的工具。
一、工具定义与参数验证
1. 工具的本质与作用
工具是MCP服务器暴露给AI模型的可执行函数，类似于REST API中的POST端点。与资源（Resources）不同，工具预期会执行计算和产生副作用，例如写入数据库、调用外部API或执行系统操作。每个工具都有三个基本组成部分：
- 名称（Name）：唯一标识工具的字符串
- 参数模式（Parameters Schema）：定义工具接收的参数及其类型
- 执行函数（Execute Function）：实现工具功能的异步函数
2. 基本工具定义
在MCP TypeScript-SDK中，有两种定义工具的方式：使用registerTool方法或者使用简化的tool方法。以下是一个基本的工具定义示例：
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';const server = new McpServer({name: 'tools-demo',version: '1.0.0'
});// 方式一：使用registerTool方法
server.registerTool({name: 'greeting',description: '发送问候',parameters: z.object({name: z.string().describe('被问候者的名字'),}),execute: async ({ name }) => {return {content: [{ type: 'text', text: `你好，${name}！` }]};},
});// 方式二：使用简化的tool方法
server.tool('add',{ a: z.number().describe('第一个数值'), b: z.number().describe('第二个数值') },async ({ a, b }) => {return {content: [{ type: 'text', text: String(a + b) }]};}
);
3. 参数验证的重要性
参数验证是确保工具安全运行的关键步骤，它可以：
- 防止错误的数据类型导致工具运行失败
- 阻止潜在的恶意输入
- 提供明确的错误信息，帮助调试
- 自动生成工具的文档和提示
MCP TypeScript-SDK使用Zod库进行参数验证，它提供了一种声明式且类型安全的方式来定义参数模式。
4. 基本参数验证
以下是一些常见的参数验证示例：
// 简单类型验证
server.tool('echo',{ message: z.string() },async ({ message }) => ({content: [{ type: 'text', text: message }]})
);// 多参数验证
server.tool('register-user',{username: z.string().min(3).max(20),email: z.string().email(),age: z.number().int().min(18).optional()},async ({ username, email, age }) => {// 处理用户注册return {content: [{ type: 'text', text: `用户 ${username} 注册成功！` }]};}
);// 嵌套对象验证
server.tool('create-post',{post: z.object({title: z.string().max(100),content: z.string(),tags: z.array(z.string()).optional()}),authorId: z.string()},async ({ post, authorId }) => {// 创建帖子return {content: [{ type: 'text', text: `帖子"${post.title}"已创建！` }]};}
);
二、Zod模式详解与高级用法
Zod是一个TypeScript优先的模式验证库，能够轻松定义复杂的数据结构和验证规则。在MCP工具开发中，它扮演着至关重要的角色。
1. Zod核心概念
- 模式（Schema）：定义数据结构和验证规则
- 解析（Parse）：验证数据并转换为正确的类型
- 推断（Infer）：从模式中推断TypeScript类型
2. 常用Zod模式
import { z } from 'zod';// 基本类型
const stringSchema = z.string();
const numberSchema = z.number();
const booleanSchema = z.boolean();// 复合类型
const arraySchema = z.array(z.string());
const objectSchema = z.object({name: z.string(),age: z.number()
});// 联合类型
const unionSchema = z.union([z.string(), z.number()]);
// 或者更简洁的语法
const unionSchema2 = z.string().or(z.number());// 枚举类型
const statusSchema = z.enum(['pending', 'completed', 'failed']);// 可选字段
const optionalSchema = z.object({required: z.string(),optional: z.number().optional()
});// 默认值
const defaultSchema =
