cueapi

cueapi-mcp

面向 CueAPI 的官方 Model Context Protocol 服务。CueAPI 是 AI Agent 系统的开源协调层。

让启用了 MCP 的助手（Claude Desktop、Cursor、Zed 或其他 MCP 宿主）能够在对话中安排 Agent 工作、获取执行历史，并通过有证据支持的结果报告完成闭环。

为什么

Agent 无法一次调用就完成任务。它们需要跨越时间、工具、环境、Agent 和人员进行协作。每次交接都可能暗藏无声故障。CueAPI 会通过结构化证据为每次交接闭环：外部 ID、结果 URL 或产物。此 MCP 服务让 Agent 能够直接访问这一层，从而既能安排自己的后续工作，也能提供有据可依的结果报告。

安装

npm install -g @cueapi/mcp
# or use via npx (no install):
npx -y @cueapi/mcp

配置（Claude Desktop）

将以下内容添加到 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

在 cueapi.ai 生成 API 密钥。要自托管？请同时设置 CUEAPI_BASE_URL 和 CUEAPI_API_KEY。

配置（Cursor / Zed / 其他宿主）

任何支持 stdio 服务的 MCP 宿主都可以运行此服务。将宿主指向 cueapi-mcp 二进制文件，并在环境中传入 CUEAPI_API_KEY。

提供的工具

工具	功能
cueapi_create_cue	创建周期性（cron）或一次性（at）提示
cueapi_list_cues	列出提示，并按状态筛选
cueapi_get_cue	获取单条提示的详细信息
cueapi_fire_cue	立即触发现有提示，可选覆盖负载
cueapi_update_cue	更新提示的可变字段（名称、计划、回调、负载等）
cueapi_pause_cue	暂停提示，使其停止触发
cueapi_resume_cue	恢复已暂停的提示
cueapi_delete_cue	永久删除提示
cueapi_list_executions	列出历史执行记录，并按提示/状态筛选
cueapi_get_execution	按 ID 获取单条执行记录，包括状态和结果
cueapi_list_claimable_executions	列出未认领的工作器执行记录，并在服务端按任务/Agent 筛选
cueapi_claim_execution	原子化地认领指定执行记录以进行处理
cueapi_claim_next_execution	认领下一条可用执行记录（可选任务筛选）
cueapi_execution_heartbeat	延长正在执行的记录的认领租约
cueapi_report_outcome	报告只写一次的结果，并附上证据（外部 ID / URL）

对话示例

你： 安排一个每天上午 9 点运行的任务，将摘要发布到我的 webhook。

助手（使用 cueapi_create_cue）： 已创建提示 cue_abc123，首次触发时间为明天 9:00 UTC。

你： 显示它最近五次的运行记录。

助手（使用 cueapi_list_executions）： ...

开发

npm install
npm test        # vitest smoke tests for the tool surface
npm run build   # compile TypeScript to dist/
npm run dev     # run the server locally with tsx

链接

• CueAPI 主页： https://cueapi.ai
• 文档： https://docs.cueapi.ai
• 核心项目（开源）： https://github.com/cueapi/cueapi-core
• Model Context Protocol： https://modelcontextprotocol.io

更新日志

• 0.4.1。 添加 cueapi_update_cue 工具：更新 cue 的可变字段（名称、计划、回调 URL、时区、负载、描述）。封装 PATCH /v1/cues/{id}。采用稀疏更新——只发送提供的字段。弥补了各封装之间的功能差距（此前其他所有客户端封装都支持更新，MCP 直到现在才支持）。
• 0.4.0。 添加五个执行生命周期工具——cueapi_get_execution、cueapi_list_claimable_executions、cueapi_claim_execution、cueapi_claim_next_execution、cueapi_execution_heartbeat。补齐了接收、认领、处理和完成的完整流程，供希望在会话内（例如 Claude Desktop、Cursor、Zed）消费 worker 传输执行任务的 MCP 宿主 Agent 使用。重点：list_claimable_executions 通过 task / agent 查询参数在服务端筛选（客户端筛选会触发已知的 LIMIT-50 饥饿问题）；由于服务端尚不支持直接认领端点的任务筛选，claim_next_execution 接受可选的 task_name，并在内部执行一系列操作（筛选列表 → 选择最早项 → 按 ID 认领）；execution_heartbeat 通过 X-Worker-Id 请求标头发送 worker_id（服务端通过此方式传递该字段），并在架构中将其设为必填项，这样配置错误的调用方会在封装层报错，而不会悄悄绕过竞态保护。内部变更：CueAPIClient.request() 新增可选的 extraHeaders 参数，以支持每次调用使用自定义标头。
• 0.3.0。 添加 cueapi_fire_cue 工具：立即触发已有 cue，并可选提供 payload_override（以及 merge_strategy: 'merge' | 'replace'，默认值为 'merge'）。封装 POST /v1/cues/{id}/fire。让 Agent 无需创建临时 cue 即可触发临时的一次性执行，还能将每次触发时的动态数据传递给 webhook 分发和 worker 认领响应，而不修改已存储的 cue。
• 0.1.4。 修复 cueapi_pause_cue / cueapi_resume_cue，使其使用 PATCH /v1/cues/{id} 和 {"status": "paused" | "active"}（此前调用了不存在的 /pause 和 /resume 端点，导致运行时返回 404）。PR #1。这是实际包含该修复的版本；0.1.3 曾提前发布并附带此说明，但未包含合并后的代码。
• 0.1.3。 提前发布，后由 0.1.4 取代。与 0.1.2 相比没有功能变更。
• 0.1.2。 注册到 Official MCP Registry。
• 0.1.0。 首次发布：提供 8 个工具，用于创建 / 列出 / 获取 / 暂停 / 恢复 / 删除 cue、列出执行记录和报告结果。

许可证

MIT © Vector Apps Inc.