Skip to content

MCP客户端功能介绍.md

Latest commit

 

History

History
234 lines (169 loc) · 8 KB

MCP客户端功能介绍.md

File metadata and controls

234 lines (169 loc) · 8 KB

MCP 客户端功能介绍

MJ-Studio 支持在对话中调用外部 MCP（Model Context Protocol）服务，让 AI 助手获得扩展能力，如访问文件系统、查询数据库、调用第三方 API 等。

功能概述

通过 MCP 客户端，AI 助手可以：

  • 调用外部工具：执行 MCP 服务提供的各种工具
  • 多步推理：连续调用多个工具完成复杂任务
  • 实时反馈：工具调用过程在对话中实时展示

使用场景

  • 让 AI 助手查询 GitHub 仓库、创建 Issue
  • 让 AI 助手访问本地文件系统读写文件
  • 让 AI 助手查询数据库获取实时数据
  • 让 AI 助手调用自定义 API 完成特定任务

配置层级

MCP 服务采用两层配置结构：

用户级配置

在「设置 → MCP 服务」页面管理所有 MCP 服务：

  • 添加、编辑、删除 MCP 服务
  • 测试服务连接状态
  • 管理每个服务的工具（启用/禁用、自动批准）

助手级配置

在助手编辑页面选择该助手可用的 MCP 服务：

  • 不同助手可以启用不同的 MCP 服务
  • 同一服务可被多个助手共享

添加 MCP 服务

手动配置

  1. 进入「设置 → MCP 服务」
  2. 点击「添加」按钮
  3. 填写服务信息：
    • 名称：服务标识，如「GitHub」
    • 描述：服务用途说明
    • 服务地址：MCP 服务的 URL
    • 请求头：认证信息等自定义请求头
    • 超时时间：工具调用超时时间（秒）

服务类型自动识别：

  • URL 以 /mcp 结尾 → StreamableHTTP 传输
  • 其他 URL → SSE 传输

JSON 导入

支持批量导入 MCP 服务配置：

HTTP 类型示例：

{
  "mcpServers": {
    "github": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

stdio 类型示例（本地进程）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/dir"]
    }
  }
}

工具管理

每个 MCP 服务连接后会自动发现可用的工具。在服务详情页面可以：

启用/禁用工具

  • 默认所有工具启用
  • 禁用不需要的工具可减少 AI 的选择范围

自动批准

控制工具调用时是否需要用户确认：

  • 关闭（默认）：每次调用需用户确认
  • 开启：自动执行，无需确认

建议：

  • 只读查询类工具可开启自动批准
  • 写入、删除等危险操作建议保持需确认

对话中使用

启用 MCP 服务

  1. 编辑助手设置
  2. 在「MCP 服务」区域勾选要启用的服务
  3. 设置最大调用轮次（默认 20）

工具调用消息流程

AI 调用工具时，消息会按以下流程创建：

  1. 助手消息 - AI 输出纯文本内容后，该消息立即完成
  2. 工具消息 - 包含所有工具调用记录（可能有多个），状态实时更新
  3. 助手消息（继续回复） - AI 基于工具结果继续回复
消息 1: 🧑 用户
        帮我搜索 nuxt mcp 相关项目

消息 2: 🤖 助手 [已完成]
        让我帮你搜索一下。

消息 3: 🔧 工具消息 [包含工具调用记录]
        ┌─────────────────────────────────────────────────┐
        │ 🔧 search_repositories (GitHub)      ⏳ 待确认   │
        │ 参数: { "query": "nuxt mcp" }                   │
        │                        [拒绝]  [批准执行]        │
        └─────────────────────────────────────────────────┘

消息 4: 🤖 助手 [已完成]
        根据搜索结果，我找到了以下相关项目：
        1. nuxt-mcp-server - Nuxt 的 MCP 服务端实现
        2. ...

关键特性：

  • 每条消息都有独立的状态（pending → streaming → completed）
  • 工具调用不会阻塞消息完成，而是创建独立的 tool 消息
  • 连续多个工具调用合并到同一个 tool 消息中，避免消息气泡过多
  • 支持多端同步，每条消息的状态变化都会实时推送
  • 工具调用状态实时同步：通过 tool.message.updated SSE 事件实时更新，刷新页面后状态正确恢复

工具调用状态

工具调用块有以下状态：

状态 说明 界面表现
pending 等待用户确认 显示批准/拒绝按钮
invoking 正在执行 显示加载动画
done 执行完成 显示完成图标，可展开查看结果
error 执行出错 显示错误图标，可展开查看错误信息
cancelled 已取消（用户拒绝或超时） 显示取消图标

状态通过 tool.message.updated SSE 事件实时推送，前端组件订阅该事件自动更新界面。

工具确认

未开启自动批准的工具，调用前会请求确认：

🤖 助手
我需要创建一个 Issue 来记录这个问题。

🔧 工具消息
┌────────────────────────────────────────────────────────────┐
│ 🔧 create_issue (GitHub)                        ⏳ 待确认   │
│                                                            │
│ ▸ 参数                                                     │
│   {                                                        │
│     "repo": "user/project",                                │
│     "title": "Bug: 登录失败",                              │
│     "body": "详细描述..."                                  │
│   }                                                        │
│                                                            │
│                                    [拒绝]  [批准执行]       │
└────────────────────────────────────────────────────────────┘
  • 批准执行：执行工具调用，AI 继续处理结果
  • 拒绝：告知 AI 用户拒绝了此操作

多步工具调用

AI 可以连续调用多个工具完成复杂任务。所有工具调用会合并到同一个工具消息中：

🔧 工具消息
┌─────────────────────────────────────────────────────────────┐
│ 🔧 search_issues (GitHub)                          ✓ 完成   │
│ 🔧 get_issue_details (GitHub)                      ✓ 完成   │
│ 🔧 add_comment (GitHub)                            ✓ 完成   │
└─────────────────────────────────────────────────────────────┘

🤖 助手
我已经找到了相关的 Issue #42，并添加了评论说明解决方案。

最大调用轮次限制（默认 20）可防止无限循环。

支持的传输类型

类型 说明 状态
StreamableHTTP MCP 官方推荐的 HTTP 传输，URL 以 /mcp 结尾 ✅ 支持
SSE 传统 Server-Sent Events 传输 ✅ 支持
stdio 本地进程标准输入输出 ✅ 支持

常见问题

AI 不调用工具

  1. 确认助手已启用对应的 MCP 服务
  2. 确认工具未被禁用
  3. 检查模型是否支持工具调用（部分模型不支持）

与 MCP 服务端的区别

MJ-Studio 同时支持 MCP 服务端和客户端：

功能 MCP 服务端 MCP 客户端
方向 向外提供服务 调用外部服务
用途 让 Claude Desktop 等调用本系统 让本系统 AI 调用外部工具
配置位置 设置 → API 管理 设置 → MCP 服务
文档 MCP 接口功能介绍 本文档