# puzzlebox

> MCP Server

Puzzlebox is an MCP server hosting finite state machines as dynamic resources, enabling clients to subscribe and receive updates on state changes, facilitating agent coordination for complex, long-term projects.

## Overview

- **Category:** Communication
- **Language:** TypeScript
- **Stars:** 31
- **Forks:** 0
- **Owner:** cliffhall
- **GitHub:** https://github.com/cliffhall/puzzlebox
- **Created:** 2025-03-01T15:53:28+00:00
- **Updated:** 2025-03-27T15:20:07+00:00
- **Source:** https://model-context-protocol.com/servers/mcp-server-finite-state-machine-updates

## Setup

## Setup

Running locally requires [Node and npm be installed](https://nodejs.org/en/download).

### Install Dependencies

- `cd /path/to/puzzlebox/`
- `npm install`

### Build

- `npm run build`
- Builds the MCP server runtime at `/dist/index.js`

### Start

- `npm run start`
- Launches an SSE-based/MCP server on port `:3001` with endpoint `/sse`
- **MUST BE LAUNCHED BEFORE RUNNING INSPECTOR**

### Inspector

- `npm run inspector`
- Runs the [Model Context Protocol Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
- The Inspector UI will be available at: http://localhost:5173
- In the Inspector UI:
  - Make sure `Transport Type` is set to `SSE`
  - Make sure `URL` is set to http://localhost:3001/sse
  - Click its **"Connect"** button to connect to the puzzlebox server.
    - You should see Green light 🟢and **"Connected"** message.
  - Click its **List Tools** button

### Format

- `npm run format`
- Runs `prettier` on the code, adjusting formatting

### Typecheck

- `npm run typecheck`
- Runs `tsc` with args to check and report type issues

### Lint

- `npm run lint`
- Runs `eslint` to non-destructively check for and report syntax problems

### LintFix

- `npm run lint:fix`
- Runs `eslint` to check for and fix syntax problems

### Test

- `npm run test`
- Run the unit tests

## Tools

## Available Tools

1.  `add_puzzle` (Add a new instance of a puzzle (finite state machine)).
2.  `get_puzzle_snapshot` (Get a snapshot of a puzzle (its current state and available actions)).
3.  `perform_action_on_puzzle` (Perform an action on a puzzle (attempt a state transition)).
4.  `count_puzzles` (Get the count of registered puzzles).
5.  Puzzle instances management (Manages puzzle instances).
6.  Resource exposure (Exposes registered puzzles as resources via `puzzlebox:/puzzle/{puzzleId}`).
7.  Client subscription (Clients can subscribe/unsubscribe to individual resource URIs).