feat: MCP v2 — SSE 流式端点、独立搜索工具、移除 token 默认兜底

- GET /mcp SSE 端点:endpoint 握手 + notifications/tools/list_changed 实时推送(服务/分类增删触发),30s keepalive
- tonav_search_services 独立全文搜索工具,相关度排序(name>tags>description>url),支持 tag 收窄
- TONAV_MCP_TOKEN 未设置时 MCP 端点禁用(503)+ 启动警告,不再回退到硬编码默认 token
- 服务端版本号 1.0.0 -> 2.0.0
- README 同步更新(工具表 7 个、双端点说明、部署变量表)
This commit is contained in:
2026-09-11 06:48:37 +08:00
parent c707667a84
commit 9d7282074f
3 changed files with 280 additions and 30 deletions
+56
View File
@@ -32,6 +32,16 @@
- ⏰ **定时自动备份** — 可配置每天凌晨 3:00 自动执行
- 📁 **本地备份管理** — 自动保留最近 5 份本地备份
### MCP Server(AI 集成)
- 🤖 **原生 MCP Server v2** — Streamable HTTP 双端点:`POST /mcp`(请求-响应) + `GET /mcp`(SSE 流式)
- 📡 **服务端主动推送** — 服务/分类变更时通过 SSE 推送 `notifications/tools/list_changed`
- 🔑 **Bearer Token 鉴权** — 通过 `TONAV_MCP_TOKEN` 环境变量配置;**未设置时 MCP 端点禁用(返回 503),无默认兜底**
- 🧰 **7 个工具** — 添加服务 / 创建分类 / 列出分类 / 列出服务 / 搜索服务 / 更新服务 / 删除服务
- 🔎 **全文搜索** — `tonav_search_services` 独立搜索工具,按名称>标签>描述>URL 相关度排序
- 📝 **智能添加** — 添加服务不传名称时自动抓取目标网页 `<title>` 与 meta description,图标默认取 favicon
- 🏷️ **分类自动创建** — 指定分类不存在时自动创建
- 📦 **批量调用** — 支持单条与批量 JSON-RPC 请求,通知类请求返回 202
## 技术栈
| 组件 | 技术 |
@@ -43,6 +53,7 @@
| 认证 | bcrypt + Cookie Session |
| 前端 | 原生 HTML/CSS/JS |
| 备份 | WebDAV 协议 |
| MCP | JSON-RPC 2.0(Streamable HTTP POST + SSE GET,Bearer Token 鉴权) |
## 项目结构
@@ -63,6 +74,7 @@ ToNav-go/
│ ├── health.go # 健康检查定时任务
│ ├── settings.go # 系统设置 & 备份/恢复/删除
│ ├── views.go # 页面渲染(首页/Dashboard/管理页面)
│ ├── mcp.go # MCP Server v2(POST/GET /mcp, JSON-RPC 2.0 + SSE, Bearer Token)
│ └── utils.go # 工具函数(Session 获取)
├── utils/
│ ├── config.go # 配置加载(环境变量)
@@ -106,6 +118,7 @@ docker compose up -d
| `TONAV_PORT` | `9520` | 监听端口 |
| `TONAV_DB` | `/app/data/tonav.db` | 数据库路径 |
| `TONAV_SECRET` | 内置密钥 | Cookie 签名密钥(生产环境务必修改) |
| `TONAV_MCP_TOKEN` | **未设置则 MCP 禁用** | MCP 接口鉴权 Token(必须配置,无默认值) |
| `TZ` | `Asia/Shanghai` | 时区 |
**数据持久化:**
@@ -162,6 +175,7 @@ chmod +x tonav-go-ctl.sh
| `TONAV_PORT` | `9520` | 监听端口 |
| `TONAV_DB` | `tonav.db` | 数据库文件路径 |
| `TONAV_SECRET` | 内置密钥 | Cookie 签名密钥 |
| `TONAV_MCP_TOKEN` | **未设置则 MCP 禁用** | MCP 接口鉴权 Token(必须配置) |
### 默认账号
@@ -197,6 +211,48 @@ chmod +x tonav-go-ctl.sh
| DELETE | `/admin/api/backup/delete?name=xxx` | 删除云端备份 |
| POST | `/admin/api/backup/restore?name=xxx` | 恢复云端备份 |
### MCP 接口(Bearer Token 鉴权)
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/mcp` | MCP Streamable HTTP 端点(JSON-RPC 2.0 请求-响应) |
| GET | `/mcp` | MCP SSE 流式端点(服务端主动推送通知) |
- 鉴权:请求头 `Authorization: Bearer <TONAV_MCP_TOKEN>`,缺失或错误返回 401
- **未配置 `TONAV_MCP_TOKEN` 时端点返回 503(MCP 禁用),启动日志会警告**
- POST 支持 `initialize` / `ping` / `tools/list` / `tools/call` 方法;通知类请求返回 202
- POST 支持单条与批量 JSON-RPC 请求
- GET 为 SSE 流:首个事件 `endpoint: /mcp`(握手),后续 `message` 事件推送 `notifications/tools/list_changed`(服务/分类增删时触发),每 30s keepalive
**MCP 工具(7 个):**
| 工具 | 说明 |
|------|------|
| `tonav_add_service` | 添加服务(自动抓取网页 title/描述/favicon,分类不存在自动创建,同 URL 查重) |
| `tonav_create_category` | 创建分类 |
| `tonav_list_categories` | 列出所有分类(含服务数量) |
| `tonav_list_services` | 列出服务,支持关键词 / 分类 / 标签过滤 |
| `tonav_search_services` | 全文搜索服务,按名称>标签>描述>URL 相关度排序,支持标签收窄 |
| `tonav_update_service` | 按名称或 ID 更新服务 |
| `tonav_delete_service` | 按名称或 ID 删除服务 |
**调用示例:**
```bash
TOKEN="your-mcp-token"
# 列出全部工具
curl -s -X POST http://127.0.0.1:9520/mcp \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# 添加服务(不传 name 时自动抓取网页标题)
curl -s -X POST http://127.0.0.1:9520/mcp \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"tonav_add_service","arguments":{"url":"https://github.com","category":"开发","tags":["代码"]}}}'
```
## 数据模型
### Service 服务