n them, you act upon it by rotating the intersecting planes of the mechanism. ### Properties of a puzzle - A finite number of discrete states, e.g., "Series Concept and Tone", "World Building", "Arc Plotting", "Episode Planning", "Plotline Blending", "Episode Outline", "Script Writing" etc. - Each state may have any number of actions (including 0) that initiate transition to another state. - There is an initial state. - There is a current state that may differ after actions have been performed on the puzzle. - Transitions can be canceled by state exit and enter guards, e.g., Consult LLM via client sampling request. ### A Simple Example ```json { "initialState": "LOBBY", "states": { "LOBBY": { "name": "LOBBY", "actions": { "START_GAME": { "name": "START_GAME", "targetState": "PLAYING" } } }, "PLAYING": { "name": "PLAYING", "actions": { "END_GAME": { "name": "END_GAME", "targetState": "GAME_OVER" } } }, "GAME_OVER": { "name": "GAME_OVER", "actions": { "RESTART": { "name": "RESTART", "targetState": "PLAYING" } } } } } ``` ## What is puzzlebox?

Most MCP servers have a one-to-one relationship with the client. Puzzlebox is different.

### Many clients sharing dynamic resources Puzzlebox is an **MCP Server** implementation that: - Supports multiple client connections that can create and monitor shared, dynamic resources. - Manages puzzle instances - Exposes tools for: - Adding puzzles - Getting a snapshot of the state and available actions for a given puzzle in the box - Performing actions on a given puzzle in the box that trigger state transitions - Exposes registered puzzles as resources - Clients can use the `Puzzle Snapshot` resource template to fetch the resource by ID - Resource URI is `puzzlebox:/puzzle/{puzzleId}` - Clients can subscribe/unsubscribe to individual resource URIs ### How It Works 1. Clients connect to a puzzlebox SSE server. 2. Clients register puzzles with the server. 3. Clients can subscribe to a given puzzle to receive updates when its state changes. 4. Clients perform actions on puzzles that may change their state and available actions. 5. The puzzlebox server ensures that any attempted action is valid for the current state of the given puzzle. 6. If an action is valid, a transition to the target state is initiated. 7. During transition, optional exit and enter guards may send sampling requests to the client, the results of which could lead to cancellation of the transition (think acceptance testing by stakeholders) 8. If guards pass, the state transition completes. 9. When a client receives a resource updated notification, they can either read the resource or use the `get_puzzle_snapshot` tool to get the current state and available actions. 10. Clients update their UI based on the new state.

## MCP Tools

These functions are exposed to the agents for managing puzzles.

### ⚙️ **`add_puzzle`** #### Add a new instance of a puzzle (finite state machine). - **Inputs:** None - **Returns:** JSON object with boolean `success` and `puzzleId` ### ⚙️ **`get_puzzle_snapshot`** #### Get a snapshot of a puzzle (its current state and available actions). - **Inputs:** `puzzleId` - **Returns:** JSON object with `currentState` and `availableActions` array - **Note:** MCP clients that don't support resource subscriptions can poll this tool to watch for state changes. ### ⚙️ **`perform_action_on_puzzle`** #### Perform an action on a puzzle (attempt a state transition). - **Inputs:** `puzzleId` and `actionName` - **Returns:** JSON object with `currentState` and `availableActions` array ### ⚙️ **`count_puzzles`** #### Get the count of registered puzzles - **Inputs:** None - **Returns:** JSON object with current `count` of registered puzzles

## Local Setup

Running locally requires Node and

puzzlebox

Comments