Ice Puzzle

You can use Ice Puzzle MCP to build, validate, and publish Ice Puzzle levels with AI-assisted feedback. This MCP server lets you edit designs, test solvability, compare AI models, and publish stages with confidence through preview and readiness checks. It supports offline work, design-assist workflows, and a broad set of editing and validation tools that mirror the Ice Puzzle solver and runtime.

How to use

You interact with the MCP server through an MCP client that communicates with the server using the supported commands. The server exposes a suite of tools for level management, editing, validation, layout seeding, and publishing. You can run edits, test solvability, analyze difficulty, and confirm readiness before publishing.

How to install

Prerequisites: make sure you have Node.js and npm installed on your machine.

Install the MCP CLI globally or run setup via npx.

Steps to install and start the MCP server

# Install the MCP CLI globally
npm install -g ice-puzzle-mcp

# Or run setup without a global install
npx -y ice-puzzle-mcp setup

Run the MCP server locally

Start the MCP server using the standard CLI flow. If you installed globally, you can start directly with the serve command. If you used npx, run the serve command via npx.

npx ice-puzzle-mcp serve

# If using a local installation or a different invocation, you may also use:
ice-puzzle-mcp serve

Optional auth setup for remote drafts and publishing

If you want to work with remote drafts and publishing, you can enable authentication by obtaining an API key from the settings page of the Ice Puzzle game web app. Then run the setup flow and provide the key when prompted.

Notes on configuration and discovery

Setup stores its configuration in your home directory and can auto-discover relevant AI clients and paths. It registers the MCP with available AI clients when possible and updates related configuration files as needed.

Additional sections

The server supports offline-first operation, meaning many tools work without authentication. For remote workflows, a valid API key enables drafts, previews, and publishing. The server also provides local snapshots, preview staging, and Firebase publishing capabilities for managed workflows.

Configuration and security

Your configuration is stored in your home directory with restricted permissions to protect sensitive keys. Keep API keys private and avoid sharing configuration files that contain secrets.

Development

If you are developing or testing the MCP server locally, you can install dependencies, build, and run tests to ensure everything works before you publish your levels.

Available tools

create_level

Create a new level entry, optionally providing a title and initial layout.

get_level

Fetch details of a level by identifier including current draft state.

save_local_draft

Save the current local level draft to local storage.

load_local_draft

Load a previously saved local level draft.

list_drafts

List all locally stored drafts for quick access.

delete_draft

Remove a local draft from storage.

import_level

Import a level from an external source for editing within the MCP toolset.

export_level

Export the current level to a portable format.

rename_level

Change the name of a level draft for clarity.

clear_level

Clear the current level design workspace.

undo

Undo the last design action to revert changes.

redo

Redo the last undone action.

revert_to_last_solvable

Return the design to the last solvable state.

place_tile

Place a single tile at a specified position.

remove_tile

Remove a tile from a specified position.

move_tile

Move a tile from one position to another.

place_tiles_batch

Place multiple tiles in a single operation.

fill_region

Fill a defined region with a chosen tile type.

clear_region

Clear all tiles within a defined region.

set_grid_size

Define the grid dimensions for the level.

set_start

Set the start position for the level’s solver.

set_goal

Set the goal position for the level’s solver.

set_par

Set the optimal path length (par) for the level.

set_par_to_shortest

Automatically set par to the shortest possible path length.

add_warp_pair

Create a linked pair of warp tiles.

remove_warp

Remove a warp tile or pair from the level.

add_thin_ice

Add thin ice tiles to the level, enabling dynamic movement rules.

remove_thin_ice

Remove thin ice from the level.

add_pushable_rock

Add a rock that can be pushed by the solve agent.

remove_pushable_rock

Remove a pushable rock from the level.

set_pressure_plate

Place a pressure plate that triggers an action when stepped on.

remove_pressure_plate

Remove a pressure plate from the level.

set_barrier

Place a barrier that blocks movement.

remove_barrier

Remove a barrier from the level.

solve_level

Run the solver to determine solvability and optimal path.

test_placement

Validate whether a specific placement is valid within rules.

reachable_from

Compute all positions reachable from a starting point.

suggest_stop_points

Suggest optimally placed stop points for challenge balance.

simulate_move

Simulate a single move to analyze behavior.

simulate_playthrough

Run a full playthrough simulation to detect issues.

analyze_difficulty

Provide signals indicating level difficulty and balance.

validate_quality_gate

Check level against quality gates for publishing readiness.

check_publish_readiness

Assess blockers and prerequisites for publishing.

visualize_level

Render a visual representation of the level and path layouts.

seed_layout_pattern

Apply a preset layout pattern to seed a level.

suggest_skeleton_layout

Propose a minimal viable layout to start design.

get_game_rules

Return the game rules governing level construction.

get_tile_types

List available tile types and their behaviors.

get_level_requirements

Describe the necessary conditions for publishing.

interaction_faq

Provide answers to common interaction questions.

list_campaign_examples

List example campaigns available for testing and inspiration.

get_campaign_example

Fetch a specific campaign example for study.

save_draft

Save a draft to remote storage if configured.

load_draft

Load a draft from remote storage.

list_remote_drafts

List drafts stored remotely.

delete_remote_draft

Delete a draft stored remotely.

list_my_published_levels

List levels you have published.

get_my_published_level

Fetch a published level by identifier.

unpublish_level

Remove a published level from public access.

restore_published_level

Restore a previously unpublished level.

publish_level

Publish a level after validation.

preview_level

Create a staging preview link for a level.

auth_status

Check your authentication status for remote operations.