127 lines
3.9 KiB
Markdown
127 lines
3.9 KiB
Markdown
# MCP 调试记录（Tao-Memory-Server / RikkaHub / Lucky）
|
||
|
||
> 目标：解决移动端 MCP 客户端（MOMERY‑PRO / RikkaHub）连接异常（-32000 / Connection closed）并完成握手与工具调用。
|
||
> 项目路径：`/root/.openclaw/workspace/tao_mcp_go`
|
||
> 反向代理：Lucky
|
||
> 服务端口：5001
|
||
|
||
---
|
||
|
||
## 一、现象与症状
|
||
|
||
- 客户端能发起 `GET /mcp/sse` 与 `POST /mcp/message`，但出现：
|
||
- `-32000: Connection closed`
|
||
- POST 进入后端但 10~30s 超时后断开
|
||
- initialize 反复重试，未进入 tools/list
|
||
|
||
---
|
||
|
||
## 二、关键问题定位 & 解决方案
|
||
|
||
### 1) JSON‑RPC initialize 返回格式不被客户端认可
|
||
**现象**：initialize 请求到了，但客户端无后续动作（反复初始化）。
|
||
|
||
**解决**：
|
||
- `MCPResponse.Result` 改为 `any`，允许返回 protocolVersion/capabilities 等结构。
|
||
- 增加 initialize 返回：
|
||
- `protocolVersion`
|
||
- `capabilities.tools/resources/prompts`
|
||
- `serverInfo`
|
||
|
||
### 2) CORS 预检/响应问题导致移动端丢弃响应
|
||
**现象**：OPTIONS 或 POST 可能被丢弃，客户端视为连接失败。
|
||
|
||
**解决**：
|
||
- `requireAuth` 中放行 `OPTIONS`，返回 200 + 允许头
|
||
- `MessageHandler` 每次响应前统一设置：
|
||
- `Access-Control-Allow-Origin: *`
|
||
- `Access-Control-Allow-Methods: GET, POST, OPTIONS`
|
||
- `Access-Control-Allow-Headers: Content-Type, Authorization`
|
||
|
||
### 3) SSE 端点返回错误导致路径拼接异常
|
||
**现象**：客户端生成 /mcp/mcp 或 /mcp/https://…
|
||
|
||
**解决**：
|
||
- 增加 `TAO_ENDPOINT_STYLE=message`，SSE 发送 `event: endpoint` 为 `message?token=...`
|
||
|
||
### 4) Lucky 反代缓冲导致 SSE 首包/POST 响应丢失
|
||
**现象**：SSE 未及时下发 endpoint；POST 处理后客户端超时。
|
||
|
||
**解决**：
|
||
- SSE 头加入：`X-Accel-Buffering: no`
|
||
- SSE 建立后立即 `Flush()`
|
||
- 心跳从 15s 调整为 5s
|
||
|
||
### 5) 协议版本不匹配导致客户端拒绝
|
||
**现象**：客户端请求协议 2025‑06‑18，服务端返回 2024‑11‑05，握手失败。
|
||
|
||
**解决**：
|
||
- initialize 返回 `protocolVersion: 2025-06-18`
|
||
|
||
### 6) 识别 notifications/initialized
|
||
**现象**：握手成功后仍死循环。
|
||
|
||
**解决**：
|
||
- 增加对 `notifications/initialized` 的处理与日志
|
||
|
||
### 7) POST 返回体被 Lucky 缓冲 / Chunked 不一致
|
||
**现象**：POST 返回体被代理吞掉或不及时转发。
|
||
|
||
**尝试**：
|
||
- 强制设置 `Content-Length`
|
||
- 禁用缓冲 `X-Accel-Buffering: no`
|
||
- 取消 `Connection: close`
|
||
|
||
> 此阶段仍存在“initialize 循环”问题，最终采用异步 SSE 方案解决。
|
||
|
||
---
|
||
|
||
## 三、终极解决方案：异步 SSE 通道模式（MCP 正式规范）
|
||
|
||
**核心思路**：
|
||
- POST 只作为“投递箱”，立即返回 `202 Accepted`
|
||
- 所有 JSON‑RPC 结果通过 SSE `event: message` 下发
|
||
|
||
**关键实现**：
|
||
- `SSEHandler`：建立 `token -> chan` 的映射，并在 `select` 中写入 `event: message`
|
||
- `MessageHandler`：读取 JSON 后立即 202，异步 `dispatchMCP()` 处理
|
||
- `dispatchMCP()`：根据 method 生成响应，写入对应 token 的 SSE 通道
|
||
|
||
**日志验证**：
|
||
- `[SSE Connect]` → SSE 已连
|
||
- `[MCP POST]` → POST 到达
|
||
- `[MCP Response] sent via SSE` → 回复已通过 SSE 下发
|
||
- `[MCP Notify] initialized` → 客户端确认握手完成
|
||
- `tools/list` 成功返回
|
||
|
||
---
|
||
|
||
## 四、最终生效状态（已验证）
|
||
|
||
日志证据显示握手完成：
|
||
- initialize → notifications/initialized → tools/list
|
||
- 全流程通过 SSE message 传输
|
||
|
||
---
|
||
|
||
## 五、关键配置（供后续复盘）
|
||
|
||
- 服务：`tao-mcp-go.service`
|
||
- 端口：5001
|
||
- 反代：Lucky
|
||
- SSE URL：`https://mcp.good.xx.kg/mcp/sse?token=...`
|
||
- Message URL：`https://mcp.good.xx.kg/mcp/message?token=...`
|
||
|
||
---
|
||
|
||
## 六、建议后续工作
|
||
|
||
1. 清理调试日志（POST body / SSE connect）
|
||
2. 增加 tools/call 执行日志
|
||
3. 在 README 中补充“异步 SSE 模式说明”
|
||
4. 如需兼容同步模式，建议单独开新路由避免混用
|
||
|
||
---
|
||
|
||
> 本文档用于存档，建议上传到仓库 `docs/` 目录。
|