batchwatch-mcp

batchwatch MCP 服务

让 AI Agent 询问 batchwatch“我应该把这个任务放进批处理队列吗？”，而不是靠猜。

当开发者向 Claude、Cursor、Cline 或任何支持 MCP 的 Agent 提问 “我应该把这个任务放进批处理队列，还是同步运行？” 时，此服务可让 Agent 调用 batchwatch，获取真实的队列证据——测得的等待时间分布、当前状况、分级置信度，以及数据的新鲜度。

它将 batchwatch 现有的读取路由封装为 MCP 工具。这是一个轻量且忠实的代理：它不做决策，也不会编造数字。 每个回答都是提供方自己的 JSON，原样传递，并包含 API 已返回的 n、confidence、why、basis 和 freshness。如果 API 宕机或响应缓慢，工具会返回错误，绝不会编造数据。

访问权限与层级——与 batchwatch 其他服务使用相同的门槛

由于它是忠实的代理，此服务采用与 batchwatch API 相同的层级——没有单独的 MCP 方案，也没有 MCP 快速通道。每个工具都会携带你的 BATCHWATCH_TOKEN，并享有该密钥在其他地方对应的确切层级：

• 没有令牌 → 你可以读取公共数据，但会延迟 15 分钟。你仍然能获取所有回答——等待时间分布、当前状况和结论——数据新鲜度与开放 API 提供的一致。
• 有令牌 → Agent 可享有该密钥对应的层级，以及相应的数据新鲜度、用量和 live 行为。实时数据让 Agent 能据此为真实流量进行路由，而这里的实时数据与 API 中一样，需要付费购买。

一种访问模式，在一个地方进行限制——batchwatch 层级系统（参阅 batchwatch API 文档中的 Tiers, delay, quota and the free trial）。

工具

每个工具都映射到 src/index.js 中的一个真实路由（没有 tradeoff 工具——/v1/tradeoff 在 KRAVSPEC 中有提及，但尚未实现；为一个无法提供回答的路由提供工具，正是本项目拒绝发布的虚假功能）。

工具	路由	可回答的问题
should_i_batch	GET /v1/should-i-batch	给定一个模型和你自己的 max_wait，批处理队列当前能否满足它？即结论。
estimate_batchtime	GET /v1/estimate-batchtime	我的任务可能要等多久？返回分布，而非单一预计时间。
conditions	GET /v1/conditions	当前状况与近期常态相比如何——“问题出在我这边还是他们那边？”
distribution	GET /v1/distribution	完整的实测等待时间分布（原始证据）。
coverage	GET /v1/coverage	哪些提供方和模型组合有数据，以及每种组合能在多大程度上提供回答。
wait	GET /v1/wait	公共的“队列现在是否在处理任务？”读数（未提供密钥时会有延迟）。

batchwatch 报告的是分布和当前状况，而不是单点预计时间。 个人记录中的中位等待时间曾长期为 3 分钟，但某个任务却等了 480 分钟；“你的任务会在 14:32 完成”这种说法，恰恰会在关键时刻变成谎言。工具描述中明确说明了这一点，因此调用模型能够正确使用回答。

安装与运行

cd mcp
npm install
node index.js       # speaks MCP over stdio

需要 Node ≥ 18（使用内置的 fetch）。

配置（环境变量）

变量	默认值	含义
BATCHWATCH_URL	https://batchwatch.dev	API 基础 URL。
BATCHWATCH_TOKEN	（未设置）	可选 API 密钥。不提供密钥时，数据会延迟，而不是不可用——你仍然能获取回答，只是数据较旧。
BATCHWATCH_TIMEOUT_MS	8000	单次调用超时时间。超时后工具会报错；绝不会猜测。

接入客户端

Claude Desktop / Cursor / Cline 的 mcpServers 配置项：

{
  "mcpServers": {
    "batchwatch": {
      "command": "node",
      "args": ["/absolute/path/to/batchwatch/mcp/index.js"],
      "env": { "BATCHWATCH_TOKEN": "tk_your_key_optional" }
    }
  }
}

测试

npm test                      # offline unit tests (mocked fetch) — deterministic
BATCHWATCH_LIVE=1 npm test    # also runs the live smoke against BATCHWATCH_URL

单元测试会断言以下关键属性：不会将省略的数字字段作为 0 发送；提供方的 JSON 会原样传递；只会公开真实路由（没有 tradeoff）；API 出错时会返回错误，而不是数字。

发布（覆盖注册表——#57 的目标）

对于 2026 年的开发工具而言，杠杆效应最高的分发渠道，就是成为 Agent 默认选择的答案。发布后，Agent 就能安装它，batchwatch 便能赢得这次调用，而不只是被提及。目标平台： Anthropic MCP registry、Smithery 和 mcp.so。该软件包已准备好发布（bin: batchwatch-mcp， 无需构建）；注册表提交事项由 Vikunja 任务 #57 跟踪。

为什么要做这个

batchwatch 会测量作业在大模型提供商的异步批处理队列中实际等待的时长。批处理价格只有一半，但“24 小时内完成”无法作为规划依据，因此大多数调用者出于习惯会支付全价。这个服务让即将做出选择的 Agent 只需调用一次工具，就能获取队列情况的证据。