介绍
# MCP Integration Usage Guide
## 概述
使用 MCP 集成插件来发现并执行外部 MCP 服务器提供的工具。此技能使您能够访问法律数据库、查询 API、搜索数据库，以及与任何提供 MCP 接口的服务进行集成。
该插件提供了一个统一的 `mcp` 工具，包含两个操作： - `list` - 发现所有已连接服务器中可用的工具 - `call` - 使用参数执行特定工具
---
# 流程
## 🔍 第一阶段：工具发现
### 1.1 检查可用工具
**始终先列出可用工具**，以查看已连接的 MCP 服务器及其提供的功能。
**操作：** ``` { tool: "mcp", args: { action: "list" } } ```
**响应结构：** ```json [ { "id": "server:toolname", "server": "server-name", "name": "tool-name", "description": "What this tool does", "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. 验证参数类型与模式匹配（string、number、boolean、array、object） 3. 检查约束（最小值、最大值、枚举值、模式） 4. 确保您拥有来自用户的必要信息
### 2.2 构建工具调用
**操作：** ``` { tool: "mcp", args: { action: "call", server: "<server-name>", tool: "<tool-name>", args: { // Tool-specific parameters from inputSchema } } } ```
**示例 - 韩国法律搜索：** ``` { tool: "mcp", args: { action: "call", server: "kr-legal", tool: "search_statute", args: { query: "연장근로 수당", limit: 5 } } } ```
### 2.3 解析响应
工具响应遵循以下结构： ```json { "content": [ { "type": "text", "text": "JSON string or text result" } ], "isError": false } ```
对于 JSON 响应： ```javascript const data = JSON.parse(response.content[0].text); // Access data.result, data.results, or direct properties ```
---
## 🔄 第三阶段：多步骤工作流
### 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"** - 原因：缺少必填参数或类型错误 - 解决方案：查看 list 响应中的 `inputSchema` - 确保提供了所有必填参数且类型正确
**"Server connection failed"** - 原因：MCP 服务器未运行或不可访问 - 解决方案：告知用户服务暂时不可用 - 如可能，建议替代方案
### 4.2 错误响应格式
错误返回： ```json { "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：解析并展示 ```javascript const data = JSON.parse(response.content[0].text); // Present data.results to user ```
**面向用户的响应：** ``` Found 5 Korean statutes about overtime pay:
1. 근로기준법 제56조 (연장·야간 및 휴일 근로) - Overtime work requires 50% premium 2. 근로기준법 제50조 (근로시간) - Standard working hours: 40 hours per week
Would you like me to retrieve the full text of any statute? ```
---
# 快速参考
## 列出工具 ``` {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**：[README.md](README.md) - 安装和配置 - **真实示例**：[REAL_EXAMPLE_KR_LEGAL.md](docs/REAL_EXAMPLE_KR_LEGAL.md) - 正常运行的 kr-legal 设置 - **API 参考**：[API.md](docs/API.md) - 技术 API 详细信息 - **配置**：[CONFIGURATION.md](docs/CONFIGURATION.md) - 服务器配置指南 - **故障排除**：[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) - 常见问题和解决方案
## 使用示例
- **示例集合**：[EXAMPLES.md](docs/EXAMPLES.md) - 13 个真实世界示例，包括： - 法律研究工作流 - 数据库查询 - 天气服务集成 - 多步骤复杂工作流 - 错误处理模式
---
**请记住：** 当不确定可用工具时，始终以 `action: "list"` 开始。