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

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