puzzlebox MCP Server

What is puzzlebox?

puzzlebox is an MCP server that hosts finite state machines (called “puzzles”) as dynamic resources. It enables multiple clients to create, subscribe to, and coordinate shared puzzles, making it ideal for orchestrating multi-agent workflows where agents must follow defined phases and handoffs.

How to use puzzlebox?

Install dependencies with npm install, build with npm run build, and start the SSE server on port 3001 with npm run start. Connect via the MCP Inspector at http://localhost:5173 (SSE transport, URL http://localhost:3001/sse). Use the tools add_puzzle, get_puzzle_snapshot, perform_action_on_puzzle, and count_puzzles to manage and interact with puzzles.

Key features of puzzlebox

• Supports multiple simultaneous client connections (SSE and StreamableHttp)
• Puzzle instances as dynamic resources with subscription and update notifications
• Tools: add puzzle, get snapshot, perform action, count puzzles
• State transition validation with optional exit/enter guards via sampling
• Two transport options: SSE and StreamableHttp

Use cases of puzzlebox

• Coordinating multi‑agent workflows with distinct phases (e.g., specification → design → implementation)
• Managing process‑aware agents across enterprise software development lifecycles
• Implementing approval gates between project stages (exit/enter guards)
• Enabling state‑based collaboration and handoffs between different agent teams