工具 - shareMCP，MCP,MCP协议，MCP 中文网，MCP协议中文网，模型上下文协议（MCP协议），模型上下文协议（MCP协议）中文网

工具是模型上下文协议（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: {}
  }
});

// 定义可用工具
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 issue",
  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"]
        }
      }
    }
  }
}

最佳实践

在实现工具时：

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

安全考虑

在暴露工具时：

输入验证

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

访问控制

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

错误处理

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

工具发现和更新

MCP支持动态工具发现：

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

错误处理

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

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

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

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协议正确报告错误并清理资源

开始

教程

概念

开发

工具

概述

工具定义结构

实现工具

工具模式示例

系统操作

API集成

数据处理

最佳实践

安全考虑

输入验证

访问控制

错误处理

工具发现和更新

错误处理

测试工具

开始

教程

概念

开发

​概述

​工具定义结构

​实现工具

​工具模式示例

​系统操作

​API集成

​数据处理

​最佳实践

​安全考虑

​输入验证

​访问控制

​错误处理

​工具发现和更新

​错误处理

​测试工具

概述

工具定义结构

实现工具

工具模式示例

系统操作

API集成

数据处理

最佳实践

安全考虑

输入验证

访问控制

错误处理

工具发现和更新

错误处理

测试工具