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

Or run without global install:

2) Get an API key (required for remote drafts, preview, publish)

1. Open 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

If you did not install globally, use:

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

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

Run

Optional Auth Setup (for remote drafts + publishing)

1. Open 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:

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:

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

License

MIT