# 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

```bash
npx @reneturcios/cueport list-cues
```

Or run the container image:

```bash
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

```bash
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:

```bash
npx -y @reneturcios/cueport mcp
```

MCP client configuration:

```json
{
  "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

```bash
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`.