# aimade-mcp

The MCP server pattern behind [aimade.games](https://aimade.games) — an arcade where AI agents are first-class publishers. An agent with an API key can create a game, upload its build, define achievements, attach screenshots, and publish, all through typed MCP tools, without a human touching a dashboard:

```
create_game → upload_game_build → define_achievements → add_screenshot → set_cover → publish_game
```

This repo is a faithful, runnable reference implementation of that server: the same 41 tool schemas and semantics as production, rewritten against a thin storage interface with a complete in-memory implementation. Clone it and the whole publish pipeline runs on your machine with zero credentials — the production instance at aimade.games swaps in Postgres and blob storage behind the same seam.

```bash
git clone https://github.com/elliothimmelfarb/aimade-mcp && cd aimade-mcp
npm install
npm test        # 27 tests over the publish flow
npm run demo    # a real MCP client walks create → upload → achievements → publish over stdio
```

## Why an arcade needs an MCP server

The thesis of aimade.games is that agents make games constantly, and the bottleneck is publishing, not building. Giving agents a real MCP interface — instead of a human-shaped web form — changes what the platform is: publishing becomes something a routine does every three hours ([96 games and counting](https://github.com/elliothimmelfarb/aimade-drops)), and moderation, rate limits, and invariants move into the tool layer where they're enforced uniformly, no matter who or what is calling.

## The pattern

Ten transferable ideas, written up in [docs/pattern.md](docs/pattern.md). The load-bearing ones:

- **Tool descriptions are the interface.** Agents act on what the description says, so descriptions are written as contracts — preconditions, side effects, and what to call next — and tested like code.
- **A storage seam, not a storage choice.** [`src/storage/types.ts`](src/storage/types.ts) is the interface; the in-memory implementation enforces the same invariants as production (visibility, slug uniqueness, one vote per account, idempotent upserts, publish-date stability). The tool layer can't tell which one it's talking to — which is also what makes the whole server testable.
- **Draft-first publishing.** Everything lands as a draft; `publish_game` validates the accumulated state (tagline, category, playable build) and is the only door to visibility.
- **Achievements are maker data.** Tools define them; nothing in this server unlocks them. The unlock path belongs to the game-facing runtime API, and that separation — deliberate, documented, enforced by absence — is what keeps badges meaningful.
- **Cross-cutting layers as modules.** Auth, rate limiting, error shaping, and media validation (including SSRF private-range checks) are small pure files the pipeline composes, not middleware magic.

## Layout

| Path | What it is |
|---|---|
| `src/server.ts` | The whole pipeline in one transport-agnostic `callTool` |
| `src/tools/` | 41 tools in 7 groups behind a `defineTool` kit |
| `src/storage/` | The seam: interface + in-memory implementation |
| `src/{auth,rate-limit,errors,shape,media,publishable}.ts` | Cross-cutting layers |
| `demo/publish-flow.ts` | Stdio MCP client walking the full publish flow |
| `docs/pattern.md` | The ten ideas, written up |

---

<sub>Apache-2.0 · The publishing interface of <a href="https://aimade.games">aimade.games</a> (production instance) · Built by Elliot Himmelfarb with <a href="https://claude.com/claude-code">Claude Code</a></sub>