cueport

cueport

cueport は、MCP ホストやターミナルから、エージェントの作業を調整するレイヤーである CueAPI にアクセスできるようにします。キュー（定期的な cron または一度限り）をスケジュールし、必要に応じて実行し、実行状況を監視し、ワーカーの実行を確保し、ハートビートで確保状態を維持し、証拠に基づく結果を報告して処理を完了できます。1 つのバイナリで、コマンドラインインターフェースと 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、呼び出しに失敗した場合（API キーがない場合や上流 API エラーを含む）は 1、使用方法のエラーの場合は 2 です。

知っておくべき動作が 2 つあります。一時停止と再開は別々のエンドポイントではありません。どちらもステータスフィールド（paused または active）のみを含む PATCH /v1/cues/{id} です。また、claim-next は単一の呼び出しではなく、複数の呼び出しで構成されます。確保エンドポイントにはタスクフィルターがないため、ツールはまずサーバー側でフィルターされた確保可能な一覧を取得し、その中から最も古い項目を選んで、ID でその実行を確保します。

MCP サーバー

1 つのバイナリで両方のインターフェースを提供します。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/cueport mcp

MCP クライアントの設定：

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

別の CueAPI 互換ホストをサーバーの接続先にするには、env ブロックに CUEAPI_BASE_URL を追加してください。

ツール

ツール	入力	機能
cueapi_create_cue	name、schedule（必須）；省略可能な description、callback、method、timezone、payload、task、platform フィールド	定期または一度限りのキューを作成します。
cueapi_list_cues	status、limit（省略可能）	ステータスでフィルターしたキューの一覧を取得します。
cueapi_get_cue	cue_id	1 件のキューを取得します。
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	状態と結果を含む 1 件の実行を取得します。
cueapi_list_claimable_executions	task、agent、limit（省略可能）	サーバー側でフィルターした、未確保のワーカー実行の一覧を取得します。
cueapi_claim_execution	execution_id；省略可能な worker_id	1 件の実行をアトミックに確保します。
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 を参照してください。