feat(mcp): add official MCP Server for AI Agent integration

2026-07-26 19:30:43 +08:00
parent 7f54256ac0
commit a0a90f558c
11 changed files with 934 additions and 4 deletions
@@ -0,0 +1,125 @@
+# MCP Server（Hermes / OpenClaw）
+
+TaskPool 提供官方 **MCP Server**，让 Hermes、OpenClaw、Cursor 等 AI Agent **完整接管**任务池：任务、脚本、环境变量、执行与日志。
+
+> OpenAPI ≠ MCP  
+> - **OpenAPI**：`/open2api/v1` REST 接口（设置页「启用 OpenAPI」）  
+> - **MCP Server**：`taskpool mcp`，把上述接口封装成 Agent 可调用的 Tools
+
+## 前置条件
+
+1. 启动后端：`taskpool server`
+2. 系统设置 → **启用 OpenAPI** → **生成 Token**
+3. 本机或 Agent 环境能访问面板地址（如 `http://127.0.0.1:8052`）
+
+## 启动
+
+```bash
+export TASKPOOL_URL=http://127.0.0.1:8052
+export TASKPOOL_TOKEN=你的OpenAPI_Token
+taskpool mcp
+```
+
+仅 stdio 传输：由 Agent 拉起子进程，通过标准输入输出通信。日志输出在 **stderr**，不会污染协议。
+
+## Hermes / OpenClaw 配置
+
+```json
+{
+  "mcpServers": {
+    "taskpool": {
+      "command": "taskpool",
+      "args": ["mcp"],
+      "env": {
+        "TASKPOOL_URL": "http://127.0.0.1:8052",
+        "TASKPOOL_TOKEN": "替换为设置页 Token"
+      }
+    }
+  }
+}
+```
+
+若二进制不在 PATH：
+
+```json
+{
+  "command": "/path/to/taskpool",
+  "args": ["mcp"],
+  "env": {
+    "TASKPOOL_URL": "https://你的面板地址",
+    "TASKPOOL_TOKEN": "xxx"
+  }
+}
+```
+
+Docker 部署时，把 `TASKPOOL_URL` 写成 Agent 能访问的地址（宿主机映射端口或内网域名）。
+
+## 工具清单（Tools）
+
+| 分类 | Tool | 说明 |
+|------|------|------|
+| 连通 | `ping_api` | 校验 URL + Token |
+| 任务 | `list_tasks` | 分页列表/筛选 |
+| 任务 | `get_task` | 详情 |
+| 任务 | `create_task` | 创建 |
+| 任务 | `update_task` | 更新 |
+| 任务 | `delete_task` | 删除 |
+| 任务 | `list_task_tags` | 标签 |
+| 执行 | `run_task` | 立即执行 |
+| 执行 | `stop_task` | 按 log_id 停止 |
+| 执行 | `get_last_results` | 最近结果 |
+| 日志 | `list_logs` | 日志列表 |
+| 日志 | `get_log` | 日志详情（含输出） |
+| 脚本 | `list_scripts` / `get_script` / `create_script` / `update_script` / `delete_script` | 脚本 CRUD |
+| 环境变量 | `list_envs` / `list_all_envs` / `get_env` / `create_env` / `update_env` / `delete_env` | 环境变量 CRUD |
+
+## Prompts
+
+- `ops_overview`：巡检任务与失败日志  
+- `run_and_check`：执行指定任务并检查日志（参数 `task_id`）
+
+## Skill（可选）
+
+仓库内提供 Agent Skill 文档，便于模型按固定流程操作：
+
+- [`skills/taskpool/SKILL.md`](../../skills/taskpool/SKILL.md)
+
+Skill 是说明书；**真正执行依赖 MCP Tools**。两者一起用效果最好。
+
+## 安全建议
+
+1. Token 等同管理员 OpenAPI 权限，勿提交到 Git  
+2. 删除任务/脚本/环境变量前应人工确认  
+3. 不要对不可信网络暴露面板与 Token  
+4. 生产建议独立 Token，并定期轮换  
+
+## 典型对话
+
+- 「列出所有启用的任务」→ `list_tasks`  
+- 「跑一下备份任务并看日志」→ `list_tasks` → `run_task` → `list_logs` → `get_log`  
+- 「创建一个每天凌晨执行的清理任务」→ `create_task`  
+- 「最近失败的任务是什么原因」→ `list_logs(status=failed)` → `get_log`
+
+## 与项目能力的对应
+
+参考 [项目介绍](./introduction.md) 中的能力边界：
+
+| 面板能力 | MCP 是否覆盖 |
+|----------|--------------|
+| 任务调度 / 手动执行 | ✅ |
+| 脚本管理 | ✅ |
+| 环境变量 | ✅ |
+| 执行日志 | ✅ |
+| 在线终端 | ❌（WebSocket，不适合 MCP 工具化） |
+| 语言环境 Mise 安装 | ❌（可后续扩展） |
+| 消息推送配置 | ❌（可后续扩展） |
+| 远程 Agent 节点 | 间接（任务上指定 agent 后可执行） |
+
+## 故障排查
+
+| 现象 | 处理 |
+|------|------|
+| `TASKPOOL_TOKEN 未配置` | 设置 env 或配置里的 Token |
+| `无效的 OpenAPI 令牌` | 设置页启用 OpenAPI 并重新生成 |
+| 连接失败 | 检查 `TASKPOOL_URL`、防火墙、容器网络 |
+| Agent 看不到 tools | 确认 `command` 路径正确，重启 Agent Gateway |