# MiraDock

> MiraDock is a game platform. Creators and their AI coding agents build browser Games as one self-contained HTML file and publish them over MCP. Players play instantly in a sandbox; the injected window.MiraDock SDK provides saves, leaderboards, multiplayer rooms, a Store with entitlements, and tips.

## Connect
- MCP endpoint (Streamable HTTP): https://miradock.com/mcp
- Write token: create one at https://miradock.com/app/mcp and send Authorization: Bearer <YOUR_WRITE_TOKEN>. Configure it in your MCP client, never in Game HTML.
- Or use OAuth 2.1 with mcp:read and mcp:write; discover authorization at https://miradock.com/.well-known/oauth-protected-resource and https://miradock.com/.well-known/oauth-authorization-server.
- Read credentials can read the spec and validate. Managing Games requires write access and is owner only.

## No account yet
An agent can start without a human account. Send this request (details in https://miradock.com/auth.md):

```http
POST https://miradock.com/agent/auth
Content-Type: application/json

{
  "type": "anonymous",
  "requested_credential_type": "mcp_write_token",
  "agent_label": "optional agent name"
}
```

The 201 response's credential is a sandbox MCP write token for up to three draft Games. Before publishing, the human claims the sandbox by email at https://miradock.com/agent/auth/claim.

## Publish a Game, in order
1. get_game_sdk_spec — read the complete contract; start from the minimal compliant Game in section 12.
2. validate_game — send { html }, fix errors, and repeat until ok is true. Review warnings.
3. publish_game — send HTML and metadata with publish: false; keep gameId and playUrl. Self-test playUrl in an owner-signed-in browser if available; validate and update_game any fixes.
4. set_game_leaderboards — declare every board the Game uses (boards: [] for none).
5. set_game_skus — define SKUs and prices in USD cents, minimum 50 (skus: [] for none). Never place prices in Game HTML.
6. set_game_monetization — set tips and shop. Enabling either requires payout onboarding at https://miradock.com/app/earnings and platform payments enabled; otherwise leave both false.
7. update_game — set status: "published" after configuration and testing; return the playUrl.

Before changing an existing Game, call get_game (owner-only, read scope) for its current metadata, image, leaderboards, SKUs, monetization flags, version, staged version, access mode, and review status.

## Update a live Game
Call update_game with stage: true so Players keep the live version: only the owner can play the staged version at playUrl?version=staged. Then publish_staged makes it live (archiving the previous version), or discard_staged drops it.

Also available: set_game_image (owner-only card and share image: PNG, JPEG or WebP, at most 5 MB, at least 320x180; an upload always replaces a MiraDock.snapshot() image), get_game_stats (owner-only plays, Players, leaderboard sizes, and metrics; revenue is currently null), get_game_reports (owner-only Player reports, read scope), update_game_report (owner-only report status and Creator note, write scope), set_game_access (everyone or selected members), add_game_member and remove_game_member (members by username), and report_issue (send a bug report to MiraDock). Before updating a Game, call get_game_reports and address open bugs; resolve them with a note after publishing the fix.

## Hard rules
- One self-contained HTML file, at most 2 MiB after sanitization; inline scripts and styles only.
- Include <meta name="miradock-sdk" content="1">.
- No network calls (fetch, XMLHttpRequest, WebSocket); use window.MiraDock.
- No browser storage (localStorage, sessionStorage, indexedDB, cookies); use MiraDock.save.
- Call MiraDock.ready() within 10 seconds of load. Every SDK call except the interactive report.open sheet times out after 10 seconds.
- Call MiraDock.snapshot(canvas.toDataURL()) once the first meaningful frame is on screen, so the Game gets a card image when its Creator plays it.
- Never place prices, credentials, or payment UI in Game HTML. Check MiraDock.capabilities before using optional features.
- Publishing is free. Claimed accounts share 30 HTML writes per hour and 200 per day across publish_game and update_game, with 500 MiB of Game storage.

## SDK at a glance
- Saves: MiraDock.save.set/get/delete/list — 32 keys, 64 KiB per value, 512 KiB total, 60 calls per minute. Guest saves last for the page session.
- Leaderboards: MiraDock.leaderboard.submit/top/me on boards declared with set_game_leaderboards. Signed-in Players only for submit; 10 submissions per minute.
- Store: MiraDock.shop.list/entitlements/purchase/consume. Kinds are item, access, and consumable; gate content on ctx.entitlements and the entitlements event.
- Tips: MiraDock.tip.open({ suggestedCents }) opens the tip sheet (donate.open is the original name and still works), alongside the host's "Tip the creator" button. Tips are for the Game being played; a tip grants the supporter entitlement.
- Reports: MiraDock.report.open({ category?, note? }) opens the host report sheet; capabilities.report is true. Players and guests can also use the host's Report a problem control.

## Multiplayer
Host-relayed rooms support 2–16 Players. Signed-in Players create; guests may join by six-character code or invite link. Game state lives in clients; the relay is not authoritative and paid rewards must never depend on room outcomes. Limit sends to 20 per second and 4 KiB of JSON each. Only the last 200 messages are retained. Rooms expire after 30 idle minutes at the next 15-minute cleanup.

The complete multiplayer reference is [Two-player Tap Duel](https://miradock.com/play/two-player-tap-duel), with source at https://miradock.com/docs/samples/two-player-tap-duel.html.

Event order: `players` arrives before any `message` from the same membership change; during host migration the host change arrives before further messages; messages arrive in `seq` order per room.

Fast action: `MiraDock.capabilities.multiplayer.realtime` enables `const rt = await room.realtime()`. The host browser owns a star of WebRTC pairs; the Game remains sandboxed. `rt.send(payload, { to: playerId | "all", fast: true })` sends JSON or ArrayBuffer up to 16 KiB, with 60 fast or 20 reliable messages per second per peer. Peers send only to the host. Listen for data, peers, and host migration; `rt.stats()` reports RTT and transport. Pair connectivity falls back to room relay after 10 seconds. The host can cheat; never grant paid rewards from realtime outcomes. [Arena Dash](https://miradock.com/play/arena-dash), source https://miradock.com/docs/samples/arena-dash.html, is the 2–6 player realtime reference.

Two-player turn passing (creator starts; joiner sets myTurn = false):
```js
const ctx = await MiraDock.ready();
const room = await MiraDock.multiplayer.create({ maxPlayers: 2 }); // friend: join(room.joinCode)
if (room.status !== "signin_required") {
  let myTurn = true;
  await room.on("message", ({ from, payload }) => {
    if (from !== ctx.player.id && payload?.type === "pass") myTurn = true;
  });
  async function passTurn() {
    if (!myTurn) return;
    await room.send({ type: "pass" });
    myTurn = false;
  }
}
```

## Docs
- [Getting started](https://miradock.com/docs/getting-started)
- [Game SDK](https://miradock.com/docs/game-sdk)
- [Multiplayer](https://miradock.com/docs/multiplayer)
- [Store and tips](https://miradock.com/docs/store)
- [MCP tools reference](https://miradock.com/docs/reference/mcp-tools)
- [Connect an agent](https://miradock.com/docs/connect/agents)
- [OAuth](https://miradock.com/docs/security/oauth)
- [Write tokens](https://miradock.com/docs/security/tokens)
- [Complete SDK spec, plain text](https://miradock.com/llms-full.txt)
- [Build a Game skill — full workflow](https://miradock.com/.well-known/agent-skills/build-game.md)
- [Agent skills index](https://miradock.com/.well-known/agent-skills/index.json)
- [Reference Game source: tap-counter](https://miradock.com/docs/samples/tap-counter.html)
- [Reference Game source: two-player-tap-duel](https://miradock.com/docs/samples/two-player-tap-duel.html)
- [Reference Game source: arena-dash](https://miradock.com/docs/samples/arena-dash.html)

## Optional
- [Play Games](https://miradock.com/games)
- [Terms](https://miradock.com/legal/terms)
- [Privacy](https://miradock.com/legal/privacy)
- [Balance terms](https://miradock.com/legal/balance-terms)