Skip to main content
Glama

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

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

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.

  1. Require the same build loop: edit one mechanic at a time and run solve_level after each change.

  2. 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)

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

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

Available Tools

63 tools
add_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

    B3/5.0

    Scored across 63 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      An 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.
      8
      281 PyPI
      32
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      33
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that enables AI agents to read, edit, analyze, procedurally generate, and preview Celeste .bin map files without the Lönn editor.
      1
      MIT