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

前置条件

启动后端：taskpool server
系统设置 → 启用 OpenAPI → 生成 Token
本机或 Agent 环境能访问面板地址（如 http://127.0.0.1:8052）

启动

export TASKPOOL_URL=http://127.0.0.1:8052
export TASKPOOL_TOKEN=你的OpenAPI_Token
taskpool mcp

仅 stdio 传输：由 Agent 拉起子进程，通过标准输入输出通信。日志输出在 stderr，不会污染协议。

Hermes / OpenClaw 配置

{
  "mcpServers": {
    "taskpool": {
      "command": "taskpool",
      "args": ["mcp"],
      "env": {
        "TASKPOOL_URL": "http://127.0.0.1:8052",
        "TASKPOOL_TOKEN": "替换为设置页 Token"
      }
    }
  }
}

若二进制不在 PATH：

{
  "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

Skill 是说明书；真正执行依赖 MCP Tools。两者一起用效果最好。

安全建议

Token 等同管理员 OpenAPI 权限，勿提交到 Git
删除任务/脚本/环境变量前应人工确认
不要对不可信网络暴露面板与 Token
生产建议独立 Token，并定期轮换

典型对话

「列出所有启用的任务」→ list_tasks
「跑一下备份任务并看日志」→ list_tasks → run_task → list_logs → get_log
「创建一个每天凌晨执行的清理任务」→ create_task
「最近失败的任务是什么原因」→ list_logs(status=failed) → get_log

与项目能力的对应

参考项目介绍中的能力边界：

面板能力	MCP 是否覆盖
任务调度 / 手动执行	✅
脚本管理	✅
环境变量	✅
执行日志	✅
在线终端	❌（WebSocket，不适合 MCP 工具化）
语言环境 Mise 安装	❌（可后续扩展）
消息推送配置	❌（可后续扩展）
远程 Agent 节点	间接（任务上指定 agent 后可执行）

故障排查

现象	处理
`TASKPOOL_TOKEN 未配置`	设置 env 或配置里的 Token
`无效的 OpenAPI 令牌`	设置页启用 OpenAPI 并重新生成
连接失败	检查 `TASKPOOL_URL`、防火墙、容器网络
Agent 看不到 tools	确认 `command` 路径正确，重启 Agent Gateway

3.9 KiB Raw Blame History Unescape Escape