Metadata-Version: 2.4
Name: astrocade-creator-mcp
Version: 0.1.2
Summary: Astrocade Creator MCP — pull and edit your Astrocade games locally over MCP (stdio).
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.11.0
Requires-Dist: pydantic<3,>=2
Requires-Dist: PyJWT[crypto]<3,>=2.10
Requires-Dist: requests<3,>=2.31
Requires-Dist: aiohttp<4,>=3.10
Requires-Dist: html5lib==1.1
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: mypy==1.17.0; extra == "dev"

# Astrocade Creator MCP

A local (stdio) [MCP](https://modelcontextprotocol.io) server that lets a creator pull, edit,
push, and publish the games already on their Astrocade account — as ordinary local files.

## Add to your MCP client

Point your MCP client (Claude Code, Claude Desktop, …) at it — no install step, `uvx` fetches it
from PyPI on demand:

```json
{
  "mcpServers": {
    "astrocade": {
      "command": "uvx",
      "args": ["astrocade-creator-mcp@latest"]
    }
  }
}
```

Or via the Claude Code CLI: `claude mcp add astrocade -- uvx astrocade-creator-mcp@latest`.

Targets **prod** by default — a creator sets nothing. To point at stage instead, add
`"env": { "ASTROCADE_CREATOR_MCP_ENV": "stage" }` to the entry.

### Sign-in

Nothing to configure. The **first tool call** opens a browser to sign in with **Google or
Apple**, caches the tokens under `~/.astrocade`, and silently refreshes them afterward. Login is
lazy (not at startup) so the browser flow never blocks the MCP stdio handshake.
Username/password Astrocade accounts aren't supported yet.

Optional — sign in ahead of time so the first call has no delay:
```bash
uvx astrocade-creator-mcp login
```
`uvx astrocade-creator-mcp logout` clears the cached tokens (e.g. to switch accounts).
Token cache dir: `~/.astrocade` (override with `ASTROCADE_TOKEN_CACHE_DIR`).

## Tools

- `list_my_games` — your games (drafts included).
- `pull_game` / `push_game` — check a game out (files + metadata, as JSON), save edits back as a draft. `push_game` can also update metadata (`title`, `description`, `thumbnail_url`).
- `publish_game` — first-time publishing submits the game for review; on an already-published game it pushes the saved draft live. Returns the play URL.
- `upload_asset` — upload a local image/audio/3D file to the Astrocade CDN and get its URL. Asset URLs in `asset_map.json` must come from here — external / `data:` URLs are rejected on push.
- `check_wish_status` — poll an AI "wish" that's in flight (wishes are submitted on astrocade.com; `push_game`/`pull_game` surface the request id when one is running).
- `list_lib_apis` / `get_lib_api` — browse the Astrocade `lib` API reference.

### The editing session

The first `pull_game` is a checkout: write the returned files (`game_code.html`,
`game_config.json`, `asset_map.json`, plus `persistent_storage_config.json` when the game uses
persistent storage) to a local folder together with a `.astrocade.json` session
file (`{game_id, sync_token, env}`). Add `.astrocade.json` to the folder's `.gitignore` — it's
per-machine session state, not project content. Edit the files with your normal tools, then
`push_game` the changed ones, passing the session's `sync_token` as `expected_version` so a
concurrent change upstream is usually caught (a stale write surfaces as a conflict to reconcile,
rather than silently overwriting the other change). Every successful push returns a new
sync token — update `.astrocade.json` with it.

Note: an MCP client may cap the size of an inline tool argument (roughly tens of KB), so a very
large `game_code` string can be rejected by the client before it reaches the server. When that
happens, drive this package's stdio server from a short script instead — read the file off disk and
send `push_game` over the server's stdin (reusing the `~/.astrocade` login), so the payload never
passes through the client's inline-argument path. config / asset / metadata edits are unaffected.
