工具

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

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

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

概述

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

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

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

工具定义结构

每个工具定义如下结构：

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

实现工具

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

• TypeScript
• Python

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

// 定义可用工具
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "将两个数字相加",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

// 处理工具执行
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("未找到工具");
});

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

// 定义可用工具
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "将两个数字相加",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

// 处理工具执行
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("未找到工具");
});

app = Server("example-server")

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="calculate_sum",
            description="将两个数字相加",
            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"未找到工具：{name}")

示例工具模式

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

系统操作

与本地系统交互的工具：

{
  name: "execute_command",
  description: "运行 shell 命令",
  inputSchema: {
    type: "object",
    properties: {
      command: { type: "string" },
      args: { type: "array", items: { type: "string" } }
    }
  }
}

API 集成

包装外部 API 的工具：

{
  name: "github_create_issue",
  description: "创建 GitHub 问题",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      body: { type: "string" },
      labels: { type: "array", items: { type: "string" } }
    }
  }
}

数据处理

转换或分析数据的工具：

{
  name: "analyze_csv",
  description: "分析 CSV 文件",
  inputSchema: {
    type: "object",
    properties: {
      filepath: { type: "string" },
      operations: {
        type: "array",
        items: {
          enum: ["sum", "average", "count"]
        }
      }
    }
  }
}

最佳实践

实现工具时：

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

安全考虑

暴露工具时：

输入验证

• 根据架构验证所有参数
• 清理文件路径和系统命令
• 验证 URL 和外部标识符
• 检查参数大小和范围
• 防止命令注入

访问控制

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

错误处理

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

工具发现和更新

MCP 支持动态工具发现：

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

错误处理

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

1. 在结果中设置 isError 为 true
2. 在 content 数组中包含错误详细信息

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

• TypeScript
• Python

try {
  // 工具操作
  const result = performOperation();
  return {
    content: [
      {
        type: "text",
        text: `操作成功：${result}`
      }
    ]
  };
} catch (error) {
  return {
    isError: true,
    content: [
      {
        type: "text",
        text: `错误：${error.message}`
      }
    ]
  };
}

try {
  // 工具操作
  const result = performOperation();
  return {
    content: [
      {
        type: "text",
        text: `操作成功：${result}`
      }
    ]
  };
} catch (error) {
  return {
    isError: true,
    content: [
      {
        type: "text",
        text: `错误：${error.message}`
      }
    ]
  };
}

try:
    # 工具操作
    result = perform_operation()
    return types.CallToolResult(
        content=[
            types.TextContent(
                type="text",
                text=f"操作成功：{result}"
            )
        ]
    )
except Exception as error:
    return types.CallToolResult(
        isError=True,
        content=[
            types.TextContent(
                type="text",
                text=f"错误：{str(error)}"
            )
        ]
    )

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

测试工具

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

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