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 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

npm install -g ice-puzzle-mcp

Or run without global install:

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/.
2. Sign in with Google.
3. Open Settings > Developer.
4. Click generate API key.
5. Copy the key (ipk_...) and keep it private.

3) Run setup

ice-puzzle-mcp setup

If you did not install globally, use:

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

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

npm install ice-puzzle-mcp

Run

npx ice-puzzle-mcp serve

Optional Auth Setup (for remote drafts + publishing)

1. Open https://ice-puzzle-game.web.app/.
2. Sign in with Google.
3. Go to Settings > Developer and generate an API key.
4. Run setup and paste your key when prompted:

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:

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

npm install
npm run build
npm test

License

MIT