puzzlebox

Coordinating agents with state machines

Puzzlebox is an MCP server that hosts finite state machines as dynamic resources. Clients can subscribe to these resources and receive updates when their state changes, facilitating coordination among agents.

What problem does puzzlebox address?

Puzzlebox addresses the challenge of coordinating multiple agents toward a common goal, particularly in long-horizon efforts like enterprise software development. It enables teams to be process-aware without being subject to hallucination. Agents can transition through states like "Specification" to "Design", with exit guards ensuring completeness before moving forward.

What is a puzzle?

A puzzle is a finite state machine with discrete states and actions that trigger transitions. Transitions can be canceled by state exit and enter guards.

What is puzzlebox?

Puzzlebox is an MCP Server implementation that supports multiple client connections, manages puzzle instances, and exposes tools for adding puzzles, getting snapshots, and performing actions. Clients can subscribe to puzzle resources via puzzlebox:/puzzle/{puzzleId} to receive updates.

MCP Tools

Puzzlebox exposes tools like add_puzzle, get_puzzle_snapshot, perform_action_on_puzzle, and count_puzzles for managing puzzles.

Local Setup

The README provides instructions for local setup, including installing dependencies, building the server, and running the Model Context Protocol Inspector.

Screenshots

The README includes screenshots demonstrating the various MCP tools and resources implemented by the server, showcasing interactions with the MCP Inspector.