admin
066383de83
Build and Deploy / build-and-push (push) Successful in 54s
- Add MCP Controller and register /mcp route - MCP Server now uses OpenAPI Token for authentication - Update frontend settings to show built-in MCP endpoint config - Update docs to reflect integrated MCP endpoint
204 lines
5.2 KiB
Markdown
204 lines
5.2 KiB
Markdown
# MCP Server（Hermes / OpenClaw）
|
||
|
||
TaskPool 提供官方 **MCP Server**，让 Hermes、OpenClaw、Cursor 等 AI Agent **完整接管**任务池：任务、脚本、环境变量、执行与日志。
|
||
|
||
> OpenAPI ≠ MCP
|
||
> - **OpenAPI**：`/open2api/v1` REST 接口（设置页「启用 OpenAPI」）
|
||
> - **MCP Server**：`/mcp` HTTP 端点，把 OpenAPI 封装成 Agent 可调用的 Tools
|
||
|
||
## 前置条件
|
||
|
||
1. 启动后端服务（Docker 或 `taskpool server`）
|
||
2. 系统设置 → **启用 OpenAPI** → **生成 Token**
|
||
3. Agent 能访问面板地址（如 `http://your-server:8052`）
|
||
|
||
## 内置 MCP 端点
|
||
|
||
MCP Server 已**内置在后端服务中**，无需单独启动进程。启用 OpenAPI 后，MCP 端点自动可用：
|
||
|
||
```
|
||
http://your-server:8052/mcp
|
||
```
|
||
|
||
## Agent 配置示例
|
||
|
||
### HTTP 模式（推荐）
|
||
|
||
远程 Agent 直接访问内置端点，无需本地安装二进制。
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"taskpool": {
|
||
"url": "http://your-server:8052/mcp",
|
||
"headers": {
|
||
"Authorization": "Bearer 你的OpenAPI_Token"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### stdio 模式
|
||
|
||
本地 Agent 需要安装 `taskpool` 二进制（Claude Desktop、Cursor）。
|
||
|
||
```bash
|
||
export TASKPOOL_URL=http://your-server:8052
|
||
export TASKPOOL_TOKEN=你的OpenAPI_Token
|
||
taskpool mcp
|
||
```
|
||
|
||
Agent 配置：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"taskpool": {
|
||
"command": "taskpool",
|
||
"args": ["mcp"],
|
||
"env": {
|
||
"TASKPOOL_URL": "http://your-server:8052",
|
||
"TASKPOOL_TOKEN": "你的OpenAPI_Token"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 独立 HTTP 服务模式（可选）
|
||
|
||
如果需要单独部署 MCP 服务（如不同的端口或机器）：
|
||
|
||
```bash
|
||
# 监听默认端口 :8053
|
||
taskpool mcp --http
|
||
|
||
# 指定端口
|
||
taskpool mcp --http :9000
|
||
|
||
# 或通过环境变量
|
||
export MCP_HTTP_ADDR=:8053
|
||
taskpool mcp --http
|
||
```
|
||
|
||
独立模式暴露端点：
|
||
- `POST /mcp` - MCP 协议端点
|
||
- `GET /health` - 健康检查
|
||
|
||
## Agent 配置示例
|
||
|
||
### stdio 模式（Claude Desktop / Cursor）
|
||
|
||
```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"
|
||
}
|
||
}
|
||
```
|
||
|
||
### HTTP 模式（Hermes / OpenClaw）
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"taskpool": {
|
||
"url": "http://your-server:8053/mcp"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
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 |
|