工具 Tools - MCP 官方文档中文版

使 LLMs 通过您的服务器执行操作

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

工具被设计为由模型控制，这意味着工具从服务器暴露给客户端，目的是让 AI 模型能够自动调用它们（同时有人在环中批准）。

概述

在 MCP 中，工具允许服务器暴露可被客户端调用并由LLMs使用的可执行函数。工具的关键方面包括：

发现: 客户可以通过tools/list端点列出可用的工具

调用: 工具通过tools/call端点被调用，服务器执行请求的操作并返回结果

灵活性: 工具可以是从简单计算到复杂 API 交互的各种类型

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

工具定义结构

每个工具都定义为以下结构：

实施工具

这是一个在 MCP 服务器中实现基本工具的示例：

TypeScript

Python

示例工具模式

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

系统操作

与本地系统交互的工具：

API 集成

外部 API 的工具封装：

数据处理

能够转换或分析数据的工具：

最佳实践

在实现工具时：

提供清晰、描述性的名称和描述

使用详细的 JSON Schema 定义参数

在工具描述中包含示例，以演示模型应如何使用它们

实现适当的错误处理和验证

使用进度报告来报告长时间的操作

保持工具操作集中且原子化

文档化预期的返回值结构

实现适当的超时机制

考虑对资源密集型操作进行速率限制

10.

记录工具使用情况以供调试和监控

安全考虑事项

当暴露工具时：

输入验证

验证所有参数是否符合方案

对文件路径和系统命令进行清理处理

验证 URL 和外部标识符

检查参数大小和范围

防止命令注入

访问控制

在需要的地方实现身份验证

进行适当的授权检查

审计工具使用

限制请求速率

监控滥用行为

错误处理

不要向客户端暴露内部错误

记录安全相关的错误

适当处理超时

错误后清理资源

验证返回值

工具发现和更新

MCP supports dynamic tool discovery:

Clients can list available tools at any time

Servers can notify clients when tools change using notifications/tools/list_changed

工具可以在运行时添加或移除

工具定义可以更新（尽管这应该谨慎进行）

错误处理

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

将isError设置为true在结果中

在content数组中包含错误详情

这里是一个工具的正确错误处理示例：

TypeScript

Python

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

测试工具

MCP 工具的全面测试策略应包括：

功能测试：验证工具在使用有效输入时能否正确执行，并妥善处理无效输入

集成测试：使用真实和模拟依赖项测试工具与外部系统的交互

安全测试: 验证身份验证、授权、输入净化和速率限制

性能测试: 检查在负载下的行为、超时处理和资源清理

错误处理：确保工具通过 MCP 协议正确报告错误并清理资源