# ice-puzzle-mcp
MCP (Model Context Protocol) server for building, validating, and publishing Ice Puzzle levels with AI assistants.
## Why Use This
- Build puzzle levels quickly with solver-backed feedback after each edit.
- Keep design fun: sketch an idea, ask the AI to iterate, and immediately test solvability and quality gates.
- Compare AI (Codex vs Claude Code) models on the same level-design task with objective outputs (`solve_level`, `analyze_difficulty`, `validate_quality_gate`, `check_publish_readiness`).
- Publish with confidence using preview + readiness checks instead of one-shot blind publishing.
## Quick Start (Codex / Claude)
### 1) Install
```bash
npm install -g ice-puzzle-mcp
```
Or run without global install:
```bash
npx -y ice-puzzle-mcp setup
```
### 2) Get an API key (required for remote drafts, preview, publish)
1. Open [https://ice-puzzle-game.web.app/settings](https://ice-puzzle-game.web.app/settings).
2. Open `Settings > Developer`.
3. Sign in with Google.
4. Click generate API key.
5. Copy the key (`ipk_...`) and keep it private.
### 3) Run setup
```bash
ice-puzzle-mcp setup
```
If you did not install globally, use:
```bash
npx -y ice-puzzle-mcp setup
```
Setup will:
- Validate your API key by exchanging it once.
- Save config to `~/.ice-puzzle-mcp/config.json` with `0600` permissions.
- Register MCP in Codex and Claude when available.
- Auto-discover Codex CLI from PATH and standard app locations (including `/Applications/Codex.app/Contents/Resources/codex`).
### 4) Verify registration
```bash
codex mcp list --json
```
You should see an `ice-puzzle-mcp` entry. Restart your AI client after setup.
## What It Does
- Exposes **63 tools** for level editing, solve diagnostics, design assistance, layout seeding, quality gates, campaign examples, local snapshots, preview staging, and Firebase publishing.
- Mirrors gameplay mechanics from the `ice_puzzle` app solver/runtime.
- Enforces canonical publish checks: `par == shortest`, timeout death at `moves >= par`, warp-stop semantics, and hot coals shortcut diagnostics.
- Adds design-assist workflow helpers: dry-run placement tests, reachability maps, stop-point suggestions, layout seeding, undo/redo, and revert-to-last-solvable recovery.
- Supports offline-first design (all local tools work without auth).
## Install
```bash
npm install ice-puzzle-mcp
```
## Run
```bash
npx ice-puzzle-mcp serve
```
## Optional Auth Setup (for remote drafts + publishing)
1. Open [https://ice-puzzle-game.web.app/settings](https://ice-puzzle-game.web.app/settings).
2. Sign in with Google.
3. Go to `Settings > Developer` and generate an API key.
4. Run setup and paste your key when prompted:
```bash
npx ice-puzzle-mcp setup
```
By default, setup uses the correct exchange URL automatically and does not prompt for it.
Only use advanced mode if you need to override it:
```bash
npx ice-puzzle-mcp setup --advanced
```
Setup stores config at `~/.ice-puzzle-mcp/config.json` with mode `0600`, registers `ice-puzzle-mcp` in Codex via `codex mcp add` when Codex is installed (including app-bundle fallback discovery at `/Applications/Codex.app/Contents/Resources/codex`), and updates your Claude MCP config (`~/.claude/.mcp.json` or `~/.claude/mcp.json`) using a unique server key (`ice-puzzle-mcp`, `ice-puzzle-mcp-2`, ... if needed).
Firebase client config is no longer hardcoded in the package. By default, it is loaded from
`https://<project-id>.web.app/__/firebase/init.json` (project ID from config/env, default `ice-puzzle-game`),
or you can provide explicit `ICE_PUZZLE_FIREBASE_*` environment variables / `firebase` overrides in config.
## AI Model Comparison Workflow
Use this project as a repeatable level-design benchmark between models.
1. Give each model the same prompt and constraints.
2. Require title provenance in every generated level name:
- Prefix with `[Claude]` for Claude-generated levels.
- Prefix with `[Codex]` for Codex-generated levels.
- Example: `[Codex] L14 - Warp Plate Gauntlet`.
3. Require the same build loop: edit one mechanic at a time and run `solve_level` after each change.
4. Collect objective outputs:
- `solve_level` (solvable, shortest path, moves)
- `analyze_difficulty` (difficulty signals, direction balance)
- `validate_quality_gate` (pass/fail checks)
- `check_publish_readiness` (publish blockers)
5. Compare results on:
- Correctness (solvable, no shortcuts, par integrity)
- Design quality (path structure, mechanic integration, anti-shortcut robustness)
- Efficiency (how many edits/iterations needed to pass all checks)
6. Optionally publish or preview top candidates and run playthrough feedback.
This makes AI-vs-AI comparisons concrete instead of subjective.
## Tool Categories
### Level Management (10)
- `create_level`
- `get_level`
- `save_local_draft`
- `load_local_draft`
- `list_drafts`
- `delete_draft`
- `import_level`
- `export_level`
- `rename_level`
- `clear_level`
### History + Recovery (3)
- `undo`
- `redo`
- `revert_to_last_solvable`
### Tile + Region Operations (6)
- `place_tile`
- `remove_tile`
- `move_tile`
- `place_tiles_batch`
- `fill_region`
- `clear_region`
### Grid + Positions (5)
- `set_grid_size`
- `set_start`
- `set_goal`
- `set_par`
- `set_par_to_shortest`
### Special Elements (10)
- `add_warp_pair`
- `remove_warp`
- `add_thin_ice`
- `remove_thin_ice`
- `add_pushable_rock`
- `remove_pushable_rock`
- `set_pressure_plate`
- `remove_pressure_plate`
- `set_barrier`
- `remove_barrier`
### Solver + Validation (10)
- `solve_level`
- `test_placement`
- `reachable_from`
- `suggest_stop_points`
- `simulate_move`
- `simulate_playthrough`
- `analyze_difficulty`
- `validate_quality_gate`
- `check_publish_readiness`
- `visualize_level`
### Layout Seeding (2)
- `seed_layout_pattern`
- `suggest_skeleton_layout`
### Rules + Docs (4)
- `get_game_rules`
- `get_tile_types`
- `get_level_requirements`
- `interaction_faq`
### Campaign Examples (2)
- `list_campaign_examples`
- `get_campaign_example`
### Firebase / Publishing (11)
- `save_draft`
- `load_draft`
- `list_remote_drafts`
- `delete_remote_draft`
- `list_my_published_levels`
- `get_my_published_level`
- `unpublish_level`
- `restore_published_level`
- `publish_level`
- `preview_level`
- `auth_status`
## Canonical Rules Enforced
- Non-tutorial levels may have tied optimal paths, but shortest optimal length must equal `par`.
- Any path shorter than `par` is a hard failure.
- Timeout death is strict: if moves `>= par` and goal not reached, run fails (`WASTED`).
- Warp behavior: stepping on warp teleports to pair and ends movement.
- Hot Coals/hot tile behavior: `-5 HP` on landing and `-5 HP/sec` while standing.
- Thin ice behavior: crossing marks tile broken; entering broken thin ice is fatal.
- Draft payload parity: thin ice and pushables must use dedicated fields (`thinIceTiles`, `pushableRocks`).
## Local + Remote Drafts
- Local snapshots are in-memory (this MCP process).
- Remote drafts/publishing use Firebase (`draftLevels`, `communityLevels`, `notifications`).
- Use `preview_level` for staging links and `check_publish_readiness` before `publish_level`.
- Published level lifecycle tools are available via `list_my_published_levels`, `get_my_published_level`, `unpublish_level`, and `restore_published_level`.
## Development
```bash
npm install
npm run build
npm test
```
## License
MIT
