Ice Puzzle MCP Server

1

Add it to Claude Code

Run this in a terminal.

Run in terminal
claude mcp add ice-puzzle-mcp -- npx -y ice-puzzle-mcp serve
README.md

Build, validate, and publish Ice Puzzle levels with AI assistants.

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

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

Tools (6)

create_levelInitializes a new puzzle level for editing.
solve_levelRuns the solver to check if the level is solvable and returns path data.
analyze_difficultyAnalyzes the level for difficulty signals and direction balance.
validate_quality_gateRuns quality checks to ensure the level meets design standards.
check_publish_readinessChecks the level for any blockers preventing publication.
save_local_draftSaves the current level state to a local draft file.

Environment Variables

ICE_PUZZLE_FIREBASE_PROJECT_IDOptional override for the Firebase project ID.

Configuration

claude_desktop_config.json
{"mcpServers": {"ice-puzzle-mcp": {"command": "npx", "args": ["-y", "ice-puzzle-mcp", "serve"]}}}

Try it

→Create a new ice puzzle level and suggest a layout that incorporates warp plates.
→Run the solve_level tool on my current draft and tell me if it's solvable.
→Analyze the difficulty of this level and suggest changes to make it more challenging.
→Check if my current level is ready for publishing and list any blockers.
→Iterate on the current level design to ensure the par equals the shortest path.

Frequently Asked Questions

What are the key features of Ice Puzzle MCP?

Integrated solver-backed feedback for real-time design validation.. Over 60 tools for level editing, difficulty analysis, and quality checks.. Objective benchmarking of AI models on level-design tasks.. Support for offline-first design and local draft management.. Canonical publish checks including par integrity and shortcut diagnostics..

What can I use Ice Puzzle MCP for?

Rapidly prototyping puzzle levels with AI-assisted iteration.. Benchmarking different AI models on their ability to design solvable, high-quality game levels.. Validating level design quality before publishing to the public game platform.. Recovering from design mistakes using local snapshots and undo/redo tools..

How do I install Ice Puzzle MCP?

Install Ice Puzzle MCP by running: npm install -g ice-puzzle-mcp

What MCP clients work with Ice Puzzle MCP?

Ice Puzzle MCP works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Turn this server into reusable context

Keep Ice Puzzle MCP docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Need the old visual installer? Open Conare IDE.
Open Conare
View all ai-tools servers →

Related MCP Servers

Skill Seekers
The data layer for AI systems.
ai-tools11.1K stars
Context Mode
The other half of the context problem.
ai-tools5.6K stars
Semiotic
A React data visualization library designed for AI-assisted development.
ai-tools2.6K stars
RocketRide
Self-hosted, open-source AI pipeline platform for MCP tools
ai-tools1.6K stars
Context+
Semantic Intelligence for Large-Scale Engineering.
ai-tools1.5K stars
ShipSwift
AI-native SwiftUI component library — production-ready code for LLMs
ai-tools1.3K stars