MCP集成使用指南

概述

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

该插件提供了一个统一的mcp工具，它包含两个操作：

• list- 从所有已连接的服务器发现可用工具
• call- 使用参数执行特定工具

流程

🔍 阶段1：工具发现

1.1 检查可用工具

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

操作：

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

响应结构：

[
  {
    "id": "server:toolname",
    "server": "server-name",
    "name": "tool-name", 
    "description": "What this tool does",
    "inputSchema": {
      "type": "object",
      "properties": {...},
      "required": [...]
    }
  }
]

1.2 理解工具架构

对于每个工具，检查：

• id格式为"服务器:工具名"- 在:处分割以获取服务器和工具名
• 描述: 理解工具的功能
• 输入模式: 定义参数的JSON模式
  • 属性: 可用参数及其类型和描述
  • 必需项: 必需参数名称的数组

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: {
      // Tool-specific parameters from inputSchema
    }
  }
}

示例 - 韩国法律搜索：

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

2.3 解析响应

工具响应遵循以下结构：

{
  "content": [
    {
      "type": "text",
      "text": "JSON string or text result"
    }
  ],
  "isError": false
}

对于JSON响应：

const data = JSON.parse(response.content[0].text);
// Access data.result, data.results, or direct properties

🔄 阶段 3：多步骤工作流

3.1 链式工具调用

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

示例 - 法律研究工作流：

1. 搜索-search_statute (搜索法规)以查找相关法律
2. 检索-get_statute_full_text (获取法规全文)获取完整文本
3. 分析-analyze_law (分析法律)进行解释
4. 判例-搜索案例法查找相关案例

每个步骤都使用前一步骤的输出来指导下一个调用。

3.2 维护上下文

在工具调用之间：

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

⚠ 第 4 阶段：错误处理

4.1 常见错误

"未找到工具：服务器:工具名"

• 原因：服务器未连接或工具不存在
• 解决方案：运行操作："list"以验证可用工具
• 检查服务器和工具名称的拼写

"工具参数无效"

• 原因：缺少必需参数或类型错误
• 解决方案：审查inputSchema从列表响应
• 确保提供所有必需参数，且类型正确

“服务器连接失败”

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

4.2 错误响应格式

错误返回：

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

优雅处理：

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

完整示例

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

步骤1：发现工具

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

响应显示kr-legal:search_statute包含：

• 必需：查询（字符串）
• 可选的：限制（数字），类别（字符串）

步骤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);
// 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解析： "服务器:工具名"→ 以:分隔，获取服务器名和工具名

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

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

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

参考文档

核心文档

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

使用示例

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

请记住：不确定可用工具时始终以action: "list"