cueport

cueport

cueport gives an MCP host or a terminal access to CueAPI, the coordination layer for agent work: schedule cues (recurring cron or one-time), fire them on demand, watch their executions, claim worker executions, keep a claim alive with heartbeats, and close the loop by reporting an outcome backed by evidence. One binary serves a command-line interface and a stdio MCP server.

An API key is required. Set CUEAPI_API_KEY to a key from your CueAPI account; every call sends it as Authorization: Bearer <key>, and a missing key fails before any request is attempted. Self-hosting or testing against another host? Set CUEAPI_BASE_URL alongside the key; when it is unset, calls go to https://api.cueapi.ai.

Install

npx @reneturcios/cueport list-cues

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/cueport

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

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

Commands print the upstream JSON payload. Exit codes: 0 on success, 1 when a call fails (including a missing API key or an upstream API error), 2 for usage errors.

Two behaviours are worth knowing. Pausing and resuming are not separate endpoints: both are a PATCH /v1/cues/{id} carrying only a status field (paused or active). And claim-next is a fan-out, not a single call: the claim endpoint has no task filter, so the tool first fetches the server-side filtered claimable list, picks the oldest entry, and then claims that execution by id.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/cueport mcp

MCP client configuration:

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

Add CUEAPI_BASE_URL to the env block to point the server at a different CueAPI-compatible host.

Tools

Tool	Input	What it does
cueapi_create_cue	name, schedule (required); optional description, callback, method, timezone, payload, task and platform fields	Create a recurring or one-time cue.
cueapi_list_cues	status, limit (optional)	List cues, filtered by status.
cueapi_get_cue	cue_id	Fetch one cue.
cueapi_fire_cue	cue_id; optional payload_override, merge_strategy (merge default, or replace)	Fire a cue immediately.
cueapi_update_cue	cue_id plus any mutable cue fields	Sparse update; only provided fields are sent.
cueapi_pause_cue	cue_id	Pause a cue (PATCH with status paused).
cueapi_resume_cue	cue_id	Resume a cue (PATCH with status active).
cueapi_delete_cue	cue_id	Delete a cue permanently.
cueapi_list_executions	cue_id, status, limit (optional)	List executions, filtered by cue and status.
cueapi_get_execution	execution_id	Fetch one execution, with state and outcome.
cueapi_list_claimable_executions	task, agent, limit (optional)	List unclaimed worker executions, filtered server-side.
cueapi_claim_execution	execution_id; optional worker_id	Atomically claim one execution.
cueapi_claim_next_execution	task_name, worker_id (optional)	Claim the oldest claimable execution.
cueapi_execution_heartbeat	execution_id, worker_id (both required)	Extend a claim lease; worker_id travels in the X-Worker-Id header.
cueapi_report_outcome	execution_id, outcome (required); optional evidence fields	Report a write-once outcome with evidence.

Development

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

License

MIT — see LICENSE.