名称： mcp-integration
描述： 通过 Model Context Protocol 服务器访问外部工具与数据源。使 AI 代理能够发现并执行来自已配置 MCP 服务器的工具（法律数据库、API、数据库连接器、天气服务等）。
许可证： MIT

MCP 集成使用指南

概述

使用 MCP 集成插件来发现和执行外部 MCP 服务器提供的工具。此技能使您能够访问法律数据库、查询 API、搜索数据库，并与任何提供 MCP 接口的服务集成。

该插件提供了一个统一的 mcp 工具，包含两个操作：
- list - 发现所有已连接服务器提供的可用工具
- call - 使用参数执行特定工具

使用流程

🔍 阶段一：工具发现

1.1 检查可用工具

始终从列出可用工具开始，以查看已连接了哪些 MCP 服务器以及它们提供了哪些功能。

操作：

{
  tool: "mcp",
  args: {
    action: "list"
  }
}

响应结构：

[
  {
    "id": "server:toolname",
    "server": "server-name",
    "name": "tool-name",
    "description": "此工具的功能描述",
    "inputSchema": {
      "type": "object",
      "properties": {...},
      "required": [...]
    }
  }
]

1.2 理解工具模式

对于每个工具，请检查：
- id：格式为 "server:toolname" — 按 : 分割可得到服务器名和工具名
- description：理解该工具的作用
- inputSchema：定义参数的 JSON 模式
- properties：可用参数及其类型和描述
- required：必需参数名称的数组

1.3 将工具与用户请求匹配

常见的工具命名模式：
- search_* - 查找或搜索操作（例如 search_statute、search_users）
- get_* - 检索特定数据（例如 get_statute_full_text、get_weather）
- query - 执行查询（例如 database:query）
- analyze_* - 分析操作（例如 analyze_law）
- resolve_* - 解析引用（例如 resolve_citation）

🎯 阶段二：工具执行

2.1 验证参数

调用工具前：
1. 从 inputSchema.required 中识别所有必需参数
2. 验证参数类型是否符合模式（字符串、数字、布尔值、数组、对象）
3. 检查约束条件（最小值、最大值、枚举值、模式）
4. 确保已从用户处获得必要信息

2.2 构建工具调用

操作：

{
  tool: "mcp",
  args: {
    action: "call",
    server: "<server-name>",
    tool: "<tool-name>",
    args: {
      // 来自 inputSchema 的工具特定参数
    }
  }
}

示例 - 韩国法律搜索：

{
  tool: "mcp",
  args: {
    action: "call",
    server: "kr-legal",
    tool: "search_statute",
    args: {
      query: "연장근로 수당",
      limit: 5
    }
  }
}

2.3 解析响应

工具响应遵循以下结构：

{
  "content": [
    {
      "type": "text",
      "text": "JSON 字符串或文本结果"
    }
  ],
  "isError": false
}

对于 JSON 响应：

const data = JSON.parse(response.content[0].text);
// 访问 data.result、data.results 或直接属性

🔄 阶段三：多步骤工作流

3.1 链式工具调用

对于复杂请求，按顺序执行多个工具：

示例 - 法律研究工作流：
1. 搜索 - 使用 search_statute 查找相关法律
2. 检索 - 使用 get_statute_full_text 获取完整文本
3. 分析 - 使用 analyze_law 进行解释
4. 判例 - 使用 search_case_law 查找相关案例

每一步都使用前一步的输出信息来指导下一次调用。

3.2 保持上下文

在工具调用之间：
- 从每个响应中提取相关信息
- 使用提取的数据作为后续调用的参数
- 逐步构建理解
- 向用户呈现综合结果

⚠ 阶段四：错误处理

4.1 常见错误

"Tool not found: server:toolname"
- 原因：服务器未连接或工具不存在
- 解决方案：运行 action: "list" 以验证可用工具
- 检查服务器和工具名称的拼写

"Invalid arguments for tool"
- 原因：缺少必需参数或类型错误
- 解决方案：查看列表响应中的 inputSchema
- 确保提供所有必需参数且类型正确

"Server connection failed"
- 原因：MCP 服务器未运行或无法访问
- 解决方案：告知用户服务暂时不可用
- 如果可能，建议替代方案

4.2 错误响应格式

错误返回：

{
  "content": [{"type": "text", "text": "Error: message"}],
  "isError": true
}

优雅处理：
- 清晰地解释问题所在
- 不要暴露技术实现细节
- 建议后续步骤或替代方案
- 不要过度重试

完整示例

用户请求："查找关于加班费的韩国法律"

步骤 1：发现工具

{tool: "mcp", args: {action: "list"}}

响应显示 kr-legal:search_statute 包含：
- 必需参数：query（字符串）
- 可选参数：limit（数字）、category（字符串）

步骤 2：执行搜索

{
  tool: "mcp",
  args: {
    action: "call",
    server: "kr-legal",
    tool: "search_statute",
    args: {
      query: "연장근로 수당",
      category: "노동법",
      limit: 5
    }
  }
}

步骤 3：解析并呈现

const data = JSON.parse(response.content[0].text);
// 向用户呈现 data.results

面向用户的响应：

找到 5 条关于加班费的韩国法律：

1. 劳动基准法第56条（延长、夜间及假日劳动）
   - 加班工作需支付 50% 的津贴

2. 劳动基准法第50条（工作时间）
   - 标准工作时间：每周 40 小时

您需要我检索任何法律的全文吗？

快速参考

列出工具

{tool: "mcp", args: {action: "list"}}

调用工具

{
  tool: "mcp",
  args: {
    action: "call",
    server: "server-name",
    tool: "tool-name",
    args: {param1: "value1"}
  }
}

核心模式

工具 ID 解析： "server:toolname" → 按 : 分割得到服务器名和工具名

参数验证： 检查 inputSchema.required 和 inputSchema.properties[param].type

响应解析： 对于 JSON 响应使用 JSON.parse(response.content[0].text)

错误检测： 检查 response.isError === true

参考文档

核心文档

• 插件自述文件：README.md - 安装与配置
• 真实示例：REAL_EXAMPLE_KR_LEGAL.md - 可运行的 kr-legal 设置
• API 参考：API.md - 技术性 API 详情
• 配置指南：CONFIGURATION.md - 服务器配置指南
• 故障排除：TROUBLESHOOTING.md - 常见问题与解决方案

使用示例

• 示例集合：EXAMPLES.md - 包含 13 个真实场景示例：
• 法律研究工作流
• 数据库查询
• 天气服务集成
• 多步骤复杂工作流
• 错误处理模式

请记住： 当不确定可用工具时，始终从 action: "list" 开始。