puzzlebox

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

FAQ from puzzlebox

What is a puzzle?

A puzzle is a finite state machine with a finite number of discrete states, actions that transition between states, an initial state, and a current state. Each action may optionally be guarded by exit/enter checks.

Does puzzlebox support multiple clients?

Yes, the server supports multiple simultaneous client connections over both SSE and StreamableHttp transports, and all clients can share and monitor the same puzzle instances.

How do clients receive updates when a puzzle changes?

Clients can subscribe to a puzzle’s resource URI (puzzlebox:/puzzle/{puzzleId}). When the puzzle state changes, the server sends a resource updated notification, prompting the client to fetch the new snapshot via the get_puzzle_snapshot tool or resource template.

Are state transitions guarded?

Yes, puzzlebox supports optional exit and enter guards that can send sampling requests to the client. If a guard fails (e.g., LLM‑based validation rejects the transition), the state change is canceled.

Is puzzlebox feature‑complete?

No, the project is a work in progress. Remaining features include dynamic resource creation by puzzle state, guard prompt creation, guard via sampling, a command‑line REPL, and a demo.