ice-puzzle-mcp
Provides a suite of tools for managing remote level data via Firebase, including operations for saving, loading, and listing remote drafts, as well as publishing and unpublishing levels to the community platform.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ice-puzzle-mcp Analyze the difficulty of my current level and check if it's ready to publish."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Gear
Quick Start (Codex / Claude)
1) Install
npm install -g ice-puzzle-mcpOr run without global install:
npx -y ice-puzzle-mcp setup2) Get an API key (required for remote drafts, preview, publish)
Open
Settings > Developer.Sign in with Google.
Click generate API key.
Copy the key (
ipk_...) and keep it private.
3) Run setup
ice-puzzle-mcp setupIf you did not install globally, use:
npx -y ice-puzzle-mcp setupSetup will:
Validate your API key by exchanging it once.
Save config to
~/.ice-puzzle-mcp/config.jsonwith0600permissions.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 --jsonYou 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_puzzleapp solver/runtime.Enforces canonical publish checks:
par == shortest, timeout death atmoves >= 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-mcpRun
npx ice-puzzle-mcp serveOptional Auth Setup (for remote drafts + publishing)
Sign in with Google.
Go to
Settings > Developerand generate an API key.Run setup and paste your key when prompted:
npx ice-puzzle-mcp setupBy 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 --advancedSetup 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.
Give each model the same prompt and constraints.
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.
Require the same build loop: edit one mechanic at a time and run
solve_levelafter each change.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)
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)
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_levelget_levelsave_local_draftload_local_draftlist_draftsdelete_draftimport_levelexport_levelrename_levelclear_level
History + Recovery (3)
undoredorevert_to_last_solvable
Tile + Region Operations (6)
place_tileremove_tilemove_tileplace_tiles_batchfill_regionclear_region
Grid + Positions (5)
set_grid_sizeset_startset_goalset_parset_par_to_shortest
Special Elements (10)
add_warp_pairremove_warpadd_thin_iceremove_thin_iceadd_pushable_rockremove_pushable_rockset_pressure_plateremove_pressure_plateset_barrierremove_barrier
Solver + Validation (10)
solve_leveltest_placementreachable_fromsuggest_stop_pointssimulate_movesimulate_playthroughanalyze_difficultyvalidate_quality_gatecheck_publish_readinessvisualize_level
Layout Seeding (2)
seed_layout_patternsuggest_skeleton_layout
Rules + Docs (4)
get_game_rulesget_tile_typesget_level_requirementsinteraction_faq
Campaign Examples (2)
list_campaign_examplesget_campaign_example
Firebase / Publishing (11)
save_draftload_draftlist_remote_draftsdelete_remote_draftlist_my_published_levelsget_my_published_levelunpublish_levelrestore_published_levelpublish_levelpreview_levelauth_status
Canonical Rules Enforced
Non-tutorial levels may have tied optimal paths, but shortest optimal length must equal
par.Any path shorter than
paris a hard failure.Timeout death is strict: if moves
>= parand goal not reached, run fails (WASTED).Warp behavior: stepping on warp teleports to pair and ends movement.
Hot Coals/hot tile behavior:
-5 HPon landing and-5 HP/secwhile 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_levelfor staging links andcheck_publish_readinessbeforepublish_level.Published level lifecycle tools are available via
list_my_published_levels,get_my_published_level,unpublish_level, andrestore_published_level.
Development
npm install
npm run build
npm testLicense
MIT
Available Tools
63 toolsadd_pushable_rockC
Add pushable rocks
Inputs: positions (required).
add_thin_iceC
Add thin ice tiles (break after crossing)
Inputs: positions (required).
add_warp_pairC
Add a warp portal pair connecting two positions
Inputs: x1 (required), y1 (required), x2 (required), y2 (required).
analyze_difficultyC
Analyze current level difficulty and characteristics
Inputs: no named parameters.
auth_statusB
Check Firebase authentication status
Inputs: no named parameters.
check_publish_readinessB
Check publish blockers: auth status + strict quality gate
Inputs: no named parameters.
clear_levelB
Clear all elements from the level, keeping grid size
Inputs: no named parameters.
clear_regionA
Clear all tiles in a rectangular region. Auto-solves.
Inputs: x1 (required), y1 (required), x2 (required), y2 (required).
create_levelB
Create a new empty ice puzzle level
Inputs: name (required), width, height.
delete_draftC
Delete a locally saved draft snapshot
Inputs: draftId (required).
delete_remote_draftB
Delete a remote draft from Firebase by ID
Inputs: draftId (required).
export_levelB
Export the current working draft as PuzzleData JSON
Inputs: no named parameters.
fill_regionB
Fill a rectangular region with a tile type. Auto-solves.
Inputs: x1 (required), y1 (required), x2 (required), y2 (required), +1 more.
get_campaign_exampleC
Get one campaign level example (by level number or ID) with solution and optional PuzzleData
Inputs: levelNumber, levelId, includePuzzleData.
get_game_rulesB
Get comprehensive ice puzzle game rules and design guide
Inputs: no named parameters.
get_levelB
Get the current working draft level with details and visualization
Inputs: no named parameters.
get_level_requirementsB
Get requirements for publishable levels
Inputs: no named parameters.
get_my_published_levelB
Get one of your published marketplace levels by ID
Inputs: levelId (required).
get_tile_typesB
Get all tile types with behavior descriptions
Inputs: no named parameters.
import_levelC
Import a level from PuzzleData JSON
Inputs: puzzleData (required).
interaction_faqC
Get quick-reference interaction outcomes for adjacent mechanic combinations
Inputs: no named parameters.
list_campaign_examplesB
List campaign level examples by difficulty tier (easy/medium/hard) with solver solutions
Inputs: difficulty, includeSolutions, includePuzzleData.
list_draftsB
List all locally saved draft snapshots
Inputs: no named parameters.
list_my_published_levelsB
List your marketplace levels with status filter, sorting, and pagination
Inputs: statusFilter, sortBy, limit, cursor.
list_remote_draftsB
List all remote drafts from Firebase
Inputs: no named parameters.
load_draftC
Load a draft from Firebase by ID
Inputs: draftId (required).
load_local_draftC
Load a locally saved draft snapshot by ID
Inputs: draftId (required).
move_tileC
Move one tile/special element from one coordinate to another. Auto-solves.
Inputs: fromX (required), fromY (required), toX (required), toY (required).
place_tileC
Place a tile (rock, lava, hot_coals, or spike) at position. Auto-solves.
Inputs: x (required), y (required), type (required).
place_tiles_batchC
Place multiple tiles at once. Auto-solves.
Inputs: tiles (required).
preview_levelB
Create or update a shareable preview link without publishing to marketplace
Inputs: name, description.
publish_levelC
Publish the current draft as a marketplace level
Inputs: name, description.
reachable_fromC
Analyze all reachable landing positions from a starting coordinate
Inputs: x (required), y (required).
redoB
Redo the most recently undone operation
Inputs: no named parameters.
remove_barrierC
Remove the barrier
Inputs: no named parameters.
remove_pressure_plateC
Remove the pressure plate
Inputs: no named parameters.
remove_pushable_rockC
Remove pushable rocks
Inputs: positions (required).
remove_thin_iceC
Remove thin ice tiles
Inputs: positions (required).
remove_tileB
Remove any tile at position. Auto-solves.
Inputs: x (required), y (required).
remove_warpC
Remove a warp pair by ID
Inputs: warpId (required).
rename_levelC
Rename the current working draft without recreating it
Inputs: name (required).
restore_published_levelA
Restore an unpublished marketplace level back to ACTIVE status
Inputs: levelId (required).
revert_to_last_solvableB
Restore the latest known solvable state
Inputs: no named parameters.
save_draftA
Save the current draft to Firebase (requires authentication)
Inputs: no named parameters.
save_local_draftA
Save a snapshot of the current draft in local MCP memory
Inputs: no named parameters.
seed_layout_patternC
Apply a starter rock skeleton pattern to bootstrap solvable layout design
Inputs: pattern (required), difficulty, clearExisting.
set_barrierB
Set barrier position (kills if pressure plate not activated)
Inputs: x (required), y (required).
set_goalC
Set the goal position (can be on edge/wall)
Inputs: x (required), y (required).
set_grid_sizeB
Resize the level grid. Elements outside new bounds are removed.
Inputs: width (required), height (required).
set_parC
Set explicit par (target shortest optimal move count) for the current draft
Inputs: par (required).
set_par_to_shortestB
Solve and set par to the current solver shortest path length
Inputs: no named parameters.
set_pressure_plateC
Set pressure plate position (deactivates barrier)
Inputs: x (required), y (required).
set_startC
Set the player start position
Inputs: x (required), y (required).
simulate_moveC
Simulate a single slide move from a position
Inputs: direction (required), fromX, fromY.
simulate_playthroughC
Simulate a full sequence of moves
Inputs: moves (required).
solve_levelB
Run BFS solver on current level with direction balance and unsolvable diagnostics
Inputs: no named parameters.
suggest_skeleton_layoutB
Suggest starter rock skeleton plans without modifying the current draft
Inputs: difficulty.
suggest_stop_pointsB
Suggest blocker placements to stop a slide at intermediate points
Inputs: fromX (required), fromY (required), direction (required).
test_placementA
Dry-run placing one tile and solve without modifying the draft
Inputs: x (required), y (required), type (required).
undoB
Undo the last edit operation
Inputs: no named parameters.
unpublish_levelC
Unpublish (soft-delete) one of your marketplace levels by ID
Inputs: levelId (required), reason.
validate_quality_gateC
Run canonical parity/quality checks (par-shortest, timeout rule, warp parity, hot coals shortcut diagnostics)
Inputs: requirePar.
visualize_levelB
Show ASCII art visualization of current level
Inputs: showSolution, showCoords, showStepNumbers.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 63 tools
Most tools have distinct purposes, but some overlap exists, such as 'clear_level' and 'clear_region' both clearing elements, and 'place_tile' and 'place_tiles_batch' differing only in batch size. Descriptions help differentiate, but minor confusion could occur in selection.
Tool names follow a highly consistent snake_case pattern with clear verb_noun structures, such as 'add_pushable_rock', 'remove_tile', and 'simulate_move'. This predictability aids agent understanding and reduces errors.
With 63 tools, the count is excessive for an ice puzzle level editor, leading to potential overwhelm and redundancy. A more focused set of 15-30 tools would better suit the domain without sacrificing functionality.
The toolset provides comprehensive coverage for ice puzzle level creation, including CRUD operations (e.g., create, edit, delete), simulation, solving, publishing, and validation. No obvious gaps exist for the intended purpose.
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
AI tool directory MCP server, live since July 2026. Tools, agents, models, companies, services.
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server for the Pyxel retro game engine that enables AI models to autonomously run, verify, and iterate on retro game programs. It includes tools for visual verification through screenshots, sprite and layout analysis, and audio rendering.8281 PyPI32MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to directly run, inspect, modify, and debug Godot game development projects through 110+ tools covering scenes, scripts, resources, runtime debugging, and asset management.333MIT

multivon-mcpofficial
AlicenseAqualityBmaintenanceMCP server that gives AI coding agents direct access to evaluation tools.23Apache 2.0- AlicenseNot gradedqualityBmaintenanceAn MCP server that enables AI agents to read, edit, analyze, procedurally generate, and preview Celeste .bin map files without the Lönn editor.1MIT