99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# MCP 工具中心（AI 模块）
|
||
|
||
本模块为「AI 智能体」接入 **MCP（Model Context Protocol）** 工具调用能力：
|
||
- **MCP 市场**：内置一批可一键添加的服务，以及项目自带的「内置演示 MCP」（零配置，直接可用）。
|
||
- **选择即用**：在「我的服务」里通过「启用」开关控制哪些 MCP 在会话中被调用；**只有启用状态的服务** 才会注入到 AI 会话。
|
||
- **会话自动调用**：聊天时，AI 会自动决定是否调用已启用的 MCP 工具，前端实时展示工具调用卡片（参数 / 结果 / 状态）。
|
||
|
||
---
|
||
|
||
## 一、如何使用
|
||
|
||
1. 打开「AI 广场」→ 左侧边栏点击 **CPU（MCP 工具中心）** 按钮。
|
||
2. 「MCP 市场」页 → 点击「内置演示 MCP」的 **添加**（或添加天眼查/企查查等，需自行申请对应的 URL/Key）。
|
||
3. 切到「我的服务」页 → 把要用的服务 **启用** 开关打开；可点击「测试」验证连接并预览工具。
|
||
4. 回到聊天窗 → 提问。例如：
|
||
- `现在几点钟了？`（触发 `get_time`）
|
||
- `帮我计算 (3+5)*2`（触发 `calculate`）
|
||
- `连云港今天天气怎么样？`（触发 `weather_query`）
|
||
5. 回答过程中，AI 气泡内会出现工具调用卡片：展开可看参数与返回结果。
|
||
|
||
> 头部「MCP」绿色指示器表示当前会话已接入 N 个 MCP 工具。
|
||
|
||
## 二、手动新增 MCP 服务
|
||
|
||
「我的服务」→「新增配置」，支持三种传输：
|
||
|
||
| 传输 | 说明 | 必填字段 |
|
||
|---|---|---|
|
||
| **stdio** | 本地进程（MCP Server 以子进程方式启动） | 启动命令 command；可选参数 args(JSON数组)、环境变量 env(JSON对象) |
|
||
| **http** | Streamable HTTP 传输 | 服务地址 url；可选请求头 headers(JSON对象) |
|
||
| **sse** | 传统 SSE 传输 | 服务地址 url；可选请求头 headers(JSON对象) |
|
||
|
||
示例（stdio + npx 远程包，Windows 会自动用 `cmd /c` 包装）：
|
||
```
|
||
命令: npx -y @modelcontextprotocol/server-everything
|
||
```
|
||
示例（http）：
|
||
```
|
||
地址: https://mcp.tianyancha.com/mcp
|
||
请求头: {"Authorization":"Bearer 你的Key"}
|
||
```
|
||
|
||
## 三、内置演示 MCP（cmd/demo-mcp）
|
||
|
||
项目自带一个 Go 编写的 stdio MCP Server，提供 5 个工具，用于零配置验证全链路：
|
||
`get_time`（当前时间）、`calculate`（表达式计算）、`weather_query`（模拟天气）、`echo`、`get_user_profile`。
|
||
|
||
重新编译（如需）：
|
||
```bash
|
||
cd go
|
||
go build -o bin/demo-mcp.exe ./cmd/demo-mcp
|
||
```
|
||
|
||
## 四、实现说明（文件清单）
|
||
|
||
### 后端（Go / Beego，`go/`）
|
||
| 文件 | 作用 |
|
||
|---|---|
|
||
| `models/backend_mcp_server.go` | MCP 服务器配置模型（传输、命令、URL、启用、状态、工具数） |
|
||
| `controllers/backend_mcp_server.go` | MCP 服务器接口：市场 / 增删改查 / 测试 / 工具发现 / 启停 |
|
||
| `services/mcp_client.go` | MCP 客户端管理器：stdio/http/sse 连接、工具列表、工具调用、连接缓存 |
|
||
| `services/mcp_market.go` | MCP 市场目录（内置演示 + 天眼查/企查查/前瞻/IT桔子/BOSS直聘） |
|
||
| `controllers/backend_ai_chat.go` | 聊天工具调用循环：注入已启用 MCP 工具 → LLM 返回 tool_calls → 执行 → 回填 → 流式输出 |
|
||
| `cmd/demo-mcp/main.go` | 内置演示 MCP Server（stdio） |
|
||
| `sql/create_backend_mcp_server.sql` | 建表 SQL（`yz_backend_mcp_server`） |
|
||
|
||
**SSE 事件扩展**（`POST /backend/ai/chat/send-stream`）：
|
||
`session` / `tool_list`（本次启用的工具）/ `tool_start`（开始调用某工具）/ `tool_result`（工具返回）/ `content`（文本增量）/ `done` / `error`
|
||
|
||
### 前端（Vue3 + Element Plus，`backend/src/`）
|
||
| 文件 | 作用 |
|
||
|---|---|
|
||
| `views/apps/ai/components/mcpConfig.vue` | MCP 工具中心（市场 + 我的服务 + 新增/编辑 + 工具预览） |
|
||
| `views/apps/ai/components/chatWindow.vue` | 聊天窗：SSE 工具事件解析 + 工具调用卡片渲染 + MCP 状态指示 |
|
||
| `views/apps/ai/components/chatSidebar.vue` | CPU 按钮入口（标题更新为「MCP 工具中心」） |
|
||
| `api/ai.js` | MCP 服务器 / 市场 API 封装 |
|
||
|
||
### 模型要求
|
||
- 需支持 **Function Calling / Tool Calling**（OpenAI 兼容与 Anthropic 均已适配）。
|
||
- 已内置两种接入：OpenAI 兼容（含豆包/DeepSeek/OpenRouter 等）与 Anthropic。
|
||
|
||
## 五、依赖说明
|
||
|
||
- 新增 Go 依赖：`github.com/mark3labs/mcp-go v0.33.0`（MCP 官方协议的 Go 客户端/服务端库）。
|
||
- `go.mod` 的 `go` 指令由 `1.17` 调整为 `1.23`（mcp-go v0.33 的最低要求；本机 Go 1.25 完全兼容）。
|
||
- 数据库：需先执行 `sql/create_backend_mcp_server.sql`（本环境已执行建表）。
|
||
|
||
## 六、构建与运行
|
||
|
||
```bash
|
||
# 后端（go/ 目录）
|
||
go build -o main.exe .
|
||
./main.exe # 监听 9000
|
||
|
||
# 前端（backend/ 目录，Vue SPA）
|
||
npm run dev # 开发，vite 端口 4001，/api 代理到 9000
|
||
npm run build # 生产构建
|
||
```
|