# spaceship-mcp

An [MCP](https://modelcontextprotocol.io) server over the
[Spaceship.dev API](https://docs.spaceship.dev/), scoped to **DNS record management**.

Lets an AI agent read and change DNS records through reviewable tool calls with a
preview step — instead of clicking around a registrar console.

---

## Why the surface is deliberately small

The Spaceship API exposes around 50 operations. A server that surfaced all of them
would hand a connected agent the ability to:

| Operation | Effect |
|---|---|
| `DELETE /v1/domains/{domain}` | delete a domain |
| `GET /v1/domains/{domain}/transfer/auth-code` | return the EPP auth code — **whoever holds it can transfer the domain away** |
| `PUT /v1/domains/{domain}/transfer/lock` | unlock a domain for transfer |
| `PUT /v1/domains/{domain}/nameservers` | repoint the entire domain |
| `POST /v1/domains/{domain}`, `/renew`, `/restore` | spend money |
| `/v1/sellerhub/*` | list your domains **for sale** |
| `/v1/hyperlift/*` | scale, restart and rewrite app environment variables |

None of that is exposed here. Six tools ship, and there is no code path from this
server to the destructive half of the API. If you need those operations, use the
console — the blast radius is too large to sit behind a tool call.

## Tools

| Tool | Writes? | Notes |
|---|---|---|
| `list_domains` | no | paginated |
| `get_domain` | no | status, expiry, nameservers |
| `list_dns_records` | no | not gated by the allowlist — reading is safe |
| `add_dns_records` | **yes** | allowlisted domains only, two-step confirm |
| `delete_dns_records` | **yes** | deletes exactly the records passed, never a zone |
| `get_async_operation` | no | poll a long-running change |

## Safety model

Four independent layers, strongest first. Note that the strongest one is not code:

**1. Scope the API key.** Spaceship lets you choose scopes when minting a key.
Create this one with **DNS scopes only**. If the key cannot delete a domain, no
bug in this server can either. Nothing below substitutes for this.

**2. Domain allowlist.** `SPACESHIP_ALLOWED_DOMAINS` is checked on every write.
**Unset means writes are disabled entirely** — failing closed is the right default
for something that can take a site offline.

**3. Two-step confirm.** Write tools called without `confirm: true` change nothing.
They return a preview:

- the exact payload that would be sent
- which sensitive record types it touches (`MX`, `NS`, `CAA`, `TXT`, `SOA` — the
  ones that silently break mail or certificate issuance)
- the current zone, for comparison

**4. `force` is never sent.** The API documents this flag as *"turn-off conflicts
resolution checker and force zone update"* — it disables the server-side check that
stops a malformed payload clobbering a live zone. There is no code path here that
sets it.

Access to the server itself is separate and also fails closed: with `MCP_AUTH_TOKEN`
unset, **every request is rejected** rather than serving DNS write tools openly.
The bearer comparison is constant-time.

## Why HTTP, not stdio

A stdio MCP server only helps a client that can already reach `spaceship.dev` from
its own network. Sandboxed agent environments frequently cannot — egress is often
restricted to an allowlist, and the connection fails at the proxy before it reaches
the API.

Hosting this over HTTP and registering it as a **remote MCP connector** means the
connection is brokered by the MCP host rather than the agent's sandbox, which is
what makes it usable from a restricted environment at all.

## Configuration

```bash
cp .env.example .env
```

| Variable | Required | Notes |
|---|---|---|
| `SPACESHIP_API_KEY` | yes | mint with **DNS scopes only** |
| `SPACESHIP_API_SECRET` | yes | paired with the key |
| `MCP_AUTH_TOKEN` | yes | bearer token clients present; **unset = reject all** |
| `SPACESHIP_ALLOWED_DOMAINS` | for writes | comma-separated; **unset = writes disabled** |
| `PORT` | no | default `8080` |
| `SPACESHIP_BASE_URL` | no | default `https://spaceship.dev/api` |

## Running

```bash
npm install
npm run build
npm start
```

Or containerised:

```bash
docker build -t spaceship-mcp .
docker run --rm -p 8080:8080 --env-file .env spaceship-mcp
```

Health check — reports whether writes are enabled without revealing configuration:

```bash
curl -s localhost:8080/health
# {"status":"ok","server":{...},"protocolVersions":[...],"writesEnabled":true}
```

## Usage

Always preview first:

```jsonc
// tools/call → add_dns_records   (no confirm)
{
  "domain": "example.com",
  "records": [
    { "type": "A", "name": "api", "address": "203.0.113.10", "ttl": 3600 }
  ]
}
```

```jsonc
// → returns, without changing anything
{
  "status": "preview",
  "wouldWrite": [ ... ],
  "sensitiveTypesIncluded": [],
  "currentZone": [ ... ],
  "next": "Re-run with confirm=true to apply."
}
```

Re-send with `"confirm": true` to apply.

### Record shapes

Records follow the API's discriminated union on `type`:

| Type | Value field |
|---|---|
| `A` | `address` (IPv4) |
| `AAAA` | `address` (IPv6) |
| `CNAME` | `cname` |
| `MX` | `exchange` + `preference` |
| `TXT` | `value` |
| `NS` | `nameserver` |

`name` is the host part only — `"@"` for the apex. `ttl` is optional, 60–3600.

## Protocol

Streamable HTTP MCP, JSON-RPC 2.0 over `POST /`. Supported protocol versions:
`2025-06-18`, `2025-03-26`, `2024-11-05` — the client's requested version is echoed
back when supported. Old versions are kept deliberately; removing one silently
breaks any client pinned to it.

Implemented methods: `initialize`, `notifications/initialized`, `ping`,
`tools/list`, `tools/call`. Batch requests are rejected explicitly rather than
half-supported.

## Verified behaviour

Exercised against a locally running instance:

- `initialize` echoes the client's requested protocol version when supported
- unauthenticated `POST` → `401`
- write to a non-allowlisted domain → refused, naming the allowlist
- `ttl: 99999` → refused, quoting the offending value
- allowlist unset → `writesEnabled: false`, writes refused

**Not verified: any live call against Spaceship.** That needs real credentials.
Two things a first real call should confirm:

- **DELETE body shape.** The spec sends the record array bare for delete but
  wrapped as `{ items: [...] }` for save. That asymmetry is implemented as
  specified, but is the kind of detail that stays wrong until a real request
  proves otherwise.
- **Validation depth.** `type`, `name` and `ttl` are validated locally;
  type-specific value fields are not, so an `A` record missing `address` fails at
  the API rather than here.

Neither is a safety hole — the allowlist, confirm step and `force` omission all sit
in front of them.

## Licence

MIT