# @mciver87/cloud-agent-wrapper

CLI + MCP server for launching, resuming, and managing [Cursor Cloud Agents](https://cursor.com/docs/cloud-agent) from any terminal or MCP-capable agent.

Backed by [`@cursor/sdk`](https://cursor.com/docs/sdk/typescript). One shared core, two front-ends:

- **CLI** (`cloud-agent new|list|get|resume|cancel`) — for humans, shell scripts, CI, or any agent that can shell out.
- **MCP server** (`cloud-agent-mcp`) — exposes the same operations as native tools to Cursor Desktop, `cursor-agent` CLI, Claude Desktop, Codex, and any other MCP-capable client.

## Install

```bash
npm install -g @mciver87/cloud-agent-wrapper
export CURSOR_API_KEY="crsr_..."   # from https://cursor.com/t/<team>/api
```

## CLI usage

```bash
# Launch — auto-detects repo from `git remote get-url origin`
cloud-agent new "fix the lint failures and open a PR"

# Explicit repo + model + auto-PR
cloud-agent new --repo foo/bar --model opus-5.5 --pr "rebase onto main"

# List recent cloud agents
cloud-agent list
cloud-agent list --json --limit 50

# Fetch metadata
cloud-agent get bc-abc123

# Follow-up on an existing agent
cloud-agent resume bc-abc123 "also update the changelog"

# Cancel a running agent
cloud-agent cancel bc-abc123
```

### Exit codes

- `0` — run finished successfully
- `1` — startup / config / auth failure (couldn't even begin)
- `2` — run executed but completed with an error status

### JSON mode

Add `--json` to any command for machine-readable output. For `new` and `resume`, each line of stdout is one `SDKMessage` JSON object; for `list`/`get`/`cancel`, a single JSON object.

## MCP server usage

Register in your client's `mcp.json`. Example for Cursor (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "cloud-agent": {
      "command": "cloud-agent-mcp",
      "env": {
        "CURSOR_API_KEY": "crsr_..."
      }
    }
  }
}
```

After restarting the client, these tools become callable natively:

| Tool | What |
|---|---|
| `launch_cloud_agent` | New agent; returns ID, URL, and final assistant text |
| `list_cloud_agents` | List recent agents on your account |
| `get_cloud_agent` | Metadata for one agent |
| `resume_cloud_agent` | Follow-up prompt on existing agent |
| `cancel_cloud_agent` | Stop a running agent |

Clients that respect `inputSchema` get full argument validation (Zod schemas). Clients that don't still see rich descriptions in the tool list.

## Model shorthands

Any of these `--model` values map to full IDs:

| Shorthand | Resolves to |
|---|---|
| `opus-5.5`, `opus-5-5`, `opus` | `claude-opus-5-5` |
| `sonnet-5.5`, `sonnet` | `claude-sonnet-5-5` |
| `composer`, `composer-fast` | `composer-2.5` |
| `gpt-5.6`, `gpt` | `gpt-5-6-sol` |

Pass any other string through verbatim. If omitted, your team's default model is used.

## Repo resolution

If `--repo` is omitted, `cloud-agent` runs `git remote get-url origin` in the current directory and parses `owner/name` from the URL (both `git@github.com:owner/name` and `https://github.com/owner/name[.git]` forms work). Pass `--repo owner/name` or `--repo https://github.com/owner/name` to override.

## API key

Required: `CURSOR_API_KEY` env var. Generate at `cursor.com/t/<team>/api`. For long-term use, add to `~/.zshenv` (chmod 600) so every shell + subprocess inherits it.

Service-account keys work the same way; the Cursor backend decides whether PRs open as the key owner or the Cursor GitHub App.

## Development

```bash
git clone https://github.com/mciver87/cloud-agent-wrapper
cd cloud-agent-wrapper
npm install
npm run build
npm run typecheck
```

Source layout:

- `src/core.ts` — SDK wrapper (launch/list/get/resume/cancel). All SDK knowledge lives here.
- `src/cli.ts` — commander-based CLI, exits with 0/1/2 per the SDK skill convention.
- `src/mcp.ts` — MCP server, same operations as native tools.
- `bin/cloud-agent.mjs` + `bin/cloud-agent-mcp.mjs` — ESM shebang shims.

## License

MIT