cueport

cueport

cueport 可让 MCP 主机或终端访问 CueAPI。CueAPI 是 Agent 工作的协调层：可安排提示（周期性 cron 或一次性）、按需触发提示、查看执行情况、认领工作器执行任务、通过心跳保持认领有效，并通过提交有证据支持的结果来完成闭环。一个二进制文件同时提供命令行界面和 stdio MCP 服务。

需要 API 密钥。将 CueAPI 账户中的密钥设为 CUEAPI_API_KEY；每次调用都会以 Authorization: Bearer <key> 发送该密钥，若未提供密钥，则会在发出任何请求前失败。 若要自行托管或针对其他主机进行测试，请将 CUEAPI_BASE_URL 与密钥一并设置；未设置时，调用将发送至 https://api.cueapi.ai。

安装

npx @reneturcios/cueport list-cues

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/cueport

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

cueport create-cue --name digest --schedule "0 9 * * *" --callback-url https://example.test/hook
cueport list-cues --status active --limit 5
cueport get-cue cue_abc123
cueport fire-cue cue_abc123 --payload-override '{"topic":"release notes"}'
cueport update-cue cue_abc123 --name "morning digest"
cueport pause-cue cue_abc123
cueport resume-cue cue_abc123
cueport delete-cue cue_abc123
cueport list-executions --cue-id cue_abc123 --status failed
cueport get-execution exec_123
cueport list-claimable --task digest --agent worker-a
cueport claim-execution exec_123 --worker-id worker-7
cueport claim-next --task-name digest --worker-id worker-7
cueport heartbeat exec_123 --worker-id worker-7
cueport report-outcome exec_123 --outcome succeeded --external-id ext_42 --result-url https://example.test/result

cueport --version

命令会输出上游 JSON 负载。退出码：成功时为 0；调用失败时为 1（包括缺少 API 密钥或上游 API 错误）；用法错误时为 2。

有两种行为值得了解。暂停和恢复不是独立端点：两者都是携带 paused 或 active 状态字段的 PATCH /v1/cues/{id}。而 claim-next 是扇出操作，并非单次调用：认领端点没有任务筛选器，因此工具会先获取服务器端筛选后的可认领列表，选出最早的一项，然后按 ID 认领该执行任务。

MCP 服务

一个二进制文件同时提供两种使用方式。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/cueport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "cueport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/cueport", "mcp"],
      "env": {
        "CUEAPI_API_KEY": "cue_sk_..."
      }
    }
  }
}

在 env 区块中添加 CUEAPI_BASE_URL，即可让服务指向其他兼容 CueAPI 的主机。

工具

工具	输入	功能
cueapi_create_cue	name、schedule（必填）；可选的 description、callback、method、timezone、payload、task 和 platform 字段	创建周期性或一次性提示。
cueapi_list_cues	status、limit（可选）	列出提示，可按状态筛选。
cueapi_get_cue	cue_id	获取一个提示。
cueapi_fire_cue	cue_id；可选的 payload_override、merge_strategy（默认为 merge，或使用 replace）	立即触发提示。
cueapi_update_cue	cue_id 加任意可变提示字段	稀疏更新；仅发送已提供的字段。
cueapi_pause_cue	cue_id	暂停提示（使用状态 paused 执行 PATCH）。
cueapi_resume_cue	cue_id	恢复提示（使用状态 active 执行 PATCH）。
cueapi_delete_cue	cue_id	永久删除提示。
cueapi_list_executions	cue_id、status、limit（可选）	列出执行任务，可按提示和状态筛选。
cueapi_get_execution	execution_id	获取一个执行任务及其状态和结果。
cueapi_list_claimable_executions	task、agent、limit（可选）	列出未认领的工作器执行任务，可在服务器端筛选。
cueapi_claim_execution	execution_id；可选的 worker_id	以原子方式认领一个执行任务。
cueapi_claim_next_execution	task_name、worker_id（可选）	认领最早的可认领执行任务。
cueapi_execution_heartbeat	execution_id、worker_id（均为必填）	延长认领租期；worker_id 会通过 X-Worker-Id 标头传递。
cueapi_report_outcome	execution_id、outcome（必填）；可选的 evidence 字段	提交附带证据的只写一次结果。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。