提示词 Prompts - MCP 官方文档中文版

通过你的服务器启用 LLM 执行操作

工具是模型上下文协议 (MCP) 中一个强大的基本单元，它使服务器能够向客户端公开可执行的功能。通过工具，LLM 可以与外部系统交互、执行计算并在现实世界中执行操作。

工具旨在由模型控制，这意味着工具从服务器暴露给客户端，其目的是让 AI 模型能够自动调用它们（需要人工参与以授予批准）。

概述

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

发现 (Discovery)：客户端可以通过 tools/list 端点列出可用的工具。

调用 (Invocation)：工具使用 tools/call 端点调用，服务器执行请求的操作并返回结果。

灵活性 (Flexibility)：工具的范围可以从简单的计算到复杂的 API 交互。

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

工具定义结构

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

实现工具

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

TypeScript

Python

工具模式示例

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

系统操作

与本地系统交互的工具：

API 集成

包装外部 API 的工具：

数据处理

转换或分析数据的工具：

最佳实践

在实现工具时：

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

对参数使用详细的 JSON Schema 定义

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

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

对长时间运行的操作使用进度报告

保持工具操作的重点和原子性

记录预期的返回值结构

实施适当的超时

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

10.

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

安全注意事项

在暴露工具时：

输入验证

根据 schema 验证所有参数

清理文件路径和系统命令

验证 URL 和外部标识符

检查参数大小和范围

预防命令注入

访问控制

在需要时实施身份验证 (authentication)

使用适当的授权 (authorization) 检查

审计工具使用情况

速率限制请求

监控滥用情况

错误处理

不要将内部错误暴露给客户端

记录与安全相关的错误

适当处理超时

错误后清理资源

验证返回值

工具发现和更新

MCP 支持动态工具发现 (dynamic tool discovery)：

客户端可以随时列出可用的工具

当工具更改时，服务器可以使用 notifications/tools/list_changed 通知客户端

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

可以更新工具定义（尽管应该谨慎操作）

错误处理

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

在结果中将 isError 设置为 true

在 content 数组中包含错误详细信息

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

TypeScript

Python

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

测试工具

MCP 工具的综合测试策略应包括：

功能测试 (Functional testing)：验证工具是否使用有效输入正确执行，并适当处理无效输入

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

安全测试 (Security testing)：验证身份验证 (authentication)、授权 (authorization)、输入清理 (input sanitization) 和速率限制 (rate limiting)

性能测试 (Performance testing)：检查负载下的行为、超时处理和资源清理

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