TaskPool/docs/guide/mcp.md

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 直接访问内置端点，无需本地安装二进制。

{
  "mcpServers": {
    "taskpool": {
      "url": "http://your-server:8052/mcp",
      "headers": {
        "Authorization": "Bearer 你的OpenAPI_Token"
      }
    }
  }
}

stdio 模式

本地 Agent 需要安装 taskpool 二进制（Claude Desktop、Cursor）。

export TASKPOOL_URL=http://your-server:8052
export TASKPOOL_TOKEN=你的OpenAPI_Token
taskpool mcp

Agent 配置：

{
  "mcpServers": {
    "taskpool": {
      "command": "taskpool",
      "args": ["mcp"],
      "env": {
        "TASKPOOL_URL": "http://your-server:8052",
        "TASKPOOL_TOKEN": "你的OpenAPI_Token"
      }
    }
  }
}

独立 HTTP 服务模式（可选）

如果需要单独部署 MCP 服务（如不同的端口或机器）：

# 监听默认端口 :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）

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

HTTP 模式（Hermes / OpenClaw）

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

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

与项目能力的对应

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

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

故障排查

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