工具 - Model Context Protocol

工具是模型上下文协议（MCP）中的强大原语，使服务器能够向客户端公开可执行功能。通过工具，LLM 可以与外部系统交互，执行计算，并在现实世界中采取行动。

工具被设计为模型控制的，这意味着工具从服务器公开给客户端，目的是让 AI 模型能够自动调用它们（在人类参与循环以授予批准的情况下）。

概述

MCP 中的工具允许服务器公开可由客户端调用并由 LLM 用于执行操作的可执行函数。工具的关键方面包括：

发现：客户端可以通过 tools/list 端点列出可用工具
调用：工具使用 tools/call 端点调用，服务器执行请求的操作并返回结果
灵活性：工具可以从简单的计算到复杂的 API 交互不等

与资源一样，工具由唯一名称标识，并可包含描述以指导其使用。然而，与资源不同，工具代表可以修改状态或与外部系统交互的动态操作。

工具定义结构

每个工具的定义具有以下结构：

{
  name: string;          // 工具的唯一标识符
  description?: string;  // 人类可读的描述
  inputSchema: {         // 工具参数的 JSON Schema
    type: "object",
    properties: { ... }  // 工具特定参数
  }
}

实现工具

以下是在 MCP 服务器中实现基本工具的示例：

const server = new Server({
  name: "example-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "Add two numbers together",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_sum") {
    const { a, b } = request.params.arguments;
    return {
      content: [
        {
          type: "text",
          text: String(a + b)
        }
      ]
    };
  }
  throw new Error("Tool not found");
});

const server = new Server({
  name: "example-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "Add two numbers together",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_sum") {
    const { a, b } = request.params.arguments;
    return {
      content: [
        {
          type: "text",
          text: String(a + b)
        }
      ]
    };
  }
  throw new Error("Tool not found");
});

app = Server("example-server")

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="calculate_sum",
            description="Add two numbers together",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["a", "b"]
            }
        )
    ]

@app.call_tool()
async def call_tool(
    name: str,
    arguments: dict
) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
    if name == "calculate_sum":
        a = arguments["a"]
        b = arguments["b"]
        result = a + b
        return [types.TextContent(type="text", text=str(result))]
    raise ValueError(f"Tool not found: {name}")

工具模式示例

以下是服务器可以提供的一些工具类型示例：

系统操作

与本地系统交互的工具：

{
  name: "execute_command",
  description: "Run a shell command",
  inputSchema: {
    type: "object",
    properties: {
      command: { type: "string" },
      args: { type: "array", items: { type: "string" } }
    }
  }
}

API 集成

包装外部 API 的工具：

{
  name: "github_create_issue",
  description: "Create a GitHub issue",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      body: { type: "string" },
      labels: { type: "array", items: { type: "string" } }
    }
  }
}

数据处理

转换或分析数据的工具：

{
  name: "analyze_csv",
  description: "Analyze a CSV file",
  inputSchema: {
    type: "object",
    properties: {
      filepath: { type: "string" },
      operations: {
        type: "array",
        items: {
          enum: ["sum", "average", "count"]
        }
      }
    }
  }
}

最佳实践

在实现工具时：

提供清晰、描述性的名称和描述
使用详细的 JSON Schema 定义参数
在工具描述中包含示例，以演示模型应如何使用它们
实现适当的错误处理和验证
对长时间操作使用进度报告
保持工具操作集中和原子化
记录预期的返回值结构
实现适当的超时
考虑对资源密集型操作进行速率限制
记录工具使用情况以进行调试和监控

安全考虑

在公开工具时：

输入验证

根据模式验证所有参数
净化文件路径和系统命令
验证 URL 和外部标识符
检查参数大小和范围
防止命令注入

访问控制

在需要时实现身份验证
使用适当的授权检查
审计工具使用
限制请求速率
监控滥用

错误处理

不向客户端公开内部错误
记录与安全相关的错误
适当处理超时
错误后清理资源
验证返回值

工具发现和更新

MCP 支持动态工具发现：

客户端可以随时列出可用工具
服务器可以使用 notifications/tools/list_changed 通知客户端工具何时更改
工具可以在运行时添加或删除
工具定义可以更新（尽管应谨慎进行）

错误处理

工具错误应在结果对象内报告，而不是作为 MCP 协议级错误。这允许 LLM 查看并可能处理错误。当工具遇到错误时：

在结果中将 isError 设置为 true
在 content 数组中包含错误详情

以下是工具正确错误处理的示例：

try {
  // Tool operation
  const result = performOperation();
  return {
    content: [
      {
        type: "text",
        text: `Operation successful: ${result}`
      }
    ]
  };
} catch (error) {
  return {
    isError: true,
    content: [
      {
        type: "text",
        text: `Error: ${error.message}`
      }
    ]
  };
}

try {
  // Tool operation
  const result = performOperation();
  return {
    content: [
      {
        type: "text",
        text: `Operation successful: ${result}`
      }
    ]
  };
} catch (error) {
  return {
    isError: true,
    content: [
      {
        type: "text",
        text: `Error: ${error.message}`
      }
    ]
  };
}

try:
    # Tool operation
    result = perform_operation()
    return types.CallToolResult(
        content=[
            types.TextContent(
                type="text",
                text=f"Operation successful: {result}"
            )
        ]
    )
except Exception as error:
    return types.CallToolResult(
        isError=True,
        content=[
            types.TextContent(
                type="text",
                text=f"Error: {str(error)}"
            )
        ]
    )

这种方法允许 LLM 看到发生了错误，并可能采取纠正措施或请求人类干预。

测试工具

MCP 工具的全面测试策略应涵盖：

功能测试：验证工具使用有效输入正确执行，并适当处理无效输入
集成测试：使用真实和模拟依赖项测试工具与外部系统的交互
安全测试：验证身份验证、授权、输入净化和速率限制
性能测试：检查负载下的行为、超时处理和资源清理
错误处理：确保工具通过 MCP 协议正确报告错误并清理资源

入门指南

核心概念

SDK 文档

开发

工具

概述

工具定义结构

实现工具

工具模式示例

系统操作

API 集成

数据处理

最佳实践

安全考虑

输入验证

访问控制

错误处理

工具发现和更新

错误处理

测试工具

入门指南

核心概念

SDK 文档

开发

​概述

​工具定义结构

​实现工具

​工具模式示例

​系统操作

​API 集成

​数据处理

​最佳实践

​安全考虑

​输入验证

​访问控制

​错误处理

​工具发现和更新

​错误处理

​测试工具

概述

工具定义结构

实现工具

工具模式示例

系统操作

API 集成

数据处理

最佳实践

安全考虑

输入验证

访问控制

错误处理

工具发现和更新

错误处理

测试工具