batchwatch-mcp

batchwatch MCP サーバー

AI エージェントが推測するのではなく、batchwatch に「このジョブはバッチ処理にすべきですか？」と尋ねられるようにします。

開発者が Claude、Cursor、Cline、または MCP 対応エージェントに「この処理をバッチキューに送るべきですか、それとも同期的に実行すべきですか？」と尋ねたとき、このサーバーを使えば、エージェントは batchwatch を呼び出し、実際のキューの根拠を取得できます。測定された待ち時間の分布、現在の状況、段階評価された信頼度、そしてデータの鮮度を確認できます。

batchwatch の既存の読み取り用ルートを MCP ツールとしてラップします。これは薄く忠実なプロキシです。判断を下すことも、数値をでっち上げることもありません。すべての回答はプロバイダー自身の JSON であり、API が返す n、confidence、why、basis、freshness をそのまま渡します。API がダウンしている、または応答が遅い場合、ツールはエラーを返します。数値を捏造することはありません。

アクセスとティア — batchwatch の他の機能と同じゲート

忠実なプロキシであるため、このサーバーは batchwatch API と同じティアで動作します。MCP 専用プランも、MCP 用の優先レーンもありません。各ツールは BATCHWATCH_TOKEN を渡し、そのキーが他の場所で獲得するものとまったく同じティアを適用します。

• トークンなし → 15 分遅延の公開データを参照します。それでも、分布、状況、判定など、すべての回答を取得できます。公開 API が提供するデータの範囲で、最新の回答が得られます。
• トークンあり → エージェントは、そのキーのティアと鮮度、利用量、live の動作を適用します。実際のトラフィックを回答に基づいて振り分けられるのはライブ数値であり、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	自分のジョブはどのくらい待つ可能性がありますか？単一の ETA ではなく、分布を返します。
conditions	GET /v1/conditions	最近の標準値と比較した現在の状況。「自分の問題か、それとも相手側の問題か？」
distribution	GET /v1/distribution	測定された待ち時間の完全な分布（生の根拠）を返します。
coverage	GET /v1/coverage	どのプロバイダーとモデルの組み合わせにデータがあり、それぞれどの程度回答可能かを返します。
wait	GET /v1/wait	公開情報による「キューは今動いていますか？」の状況を返します（キーがない場合は遅延します）。

**batchwatch が報告するのは分布と現在の状況であり、点推定の ETA ではありません。**個人の履歴では中央値が 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 年の開発者向けツールにとって、最も効果的な配布チャネルは、エージェントがデフォルトで選ぶツールになることです。エージェントがインストールできるように公開すれば、batchwatch は単に名前を挙げられるだけでなく、実際に呼び出されるようになります。対象は Anthropic MCP レジストリ、Smithery、mcp.so です。パッケージは公開できる状態です（bin: batchwatch-mcp、ビルド手順不要）。レジストリへの申請は Vikunja のタスク #57 で管理しています。

このツールの目的

batchwatch は、LLM プロバイダーの非同期バッチキューでジョブが実際にどれだけ待機するかを測定します。バッチ処理は半額ですが、「24 時間以内に完了」という条件では計画を立てられないため、多くの呼び出し元は慣習的に通常料金を支払っています。このサーバーを使えば、その選択をしようとしているエージェントは、ツールを 1 回呼び出すだけでキューの状況を確認できます。