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.
puzzlebox MCP Server
@cliffhall
Basic information
About puzzlebox MCP Server
An MCP server that hosts finite state machines as dynamic resources that multiple clients can subscribe to and be updated when their state changes.
puzzlebox MCP Server config
No standard config provided
This server doesn't expose a parseable MCP config block in its README. See the repository for install instructions.
Repositorypuzzlebox MCP Server tools
Tool list not available yet
This listing does not currently have a tool list to display. This does not mean the server has no tools; check its documentation for supported capabilities.
We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.
Overview
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
Frequently asked questions
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.
More Other MCP servers
Blender
ahujasidOpen-source MCP to use Blender with any LLM
23.6K
FastMCP v2 🚀
jlowin🚀 The fast, Pythonic way to build MCP servers and clients.
26.0K
P
PickFu MCP
PickFu MCP is a Model Context Protocol (MCP) server that connects AI assistants, developers, marketers, product managers, and AI agents to PickFu's consumer research platform. It enables users to create surveys, conduct
EverArt
modelcontextprotocolModel Context Protocol Servers
88.1K
Hindsight
vectorize-ioHindsight: Agent Memory That Learns
50.4K
Comments