当前位置：首页 > java >正文

【MCP Node.js SDK 全栈进阶指南】初级篇（4）：MCP工具开发基础

java 2025/7/12 17:49:50

在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 =