PuzzleboxBLOCK
An MCP server that hosts finite state machines as dynamic resources that multiple clients can subscribe to and be updated when their state changes.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Coordinating agents with state machines
An MCP server that hosts finite state machines as dynamic resources that clients can subscribe to and be updated when their state changes.
Feature Roadmap and Status
A work in progress. Much is done, a few bits remain to be done.
- [x] Unit tests for tool code
- [x] Integration tests for MCP server (both SSE and StreamableHttp)
- [x] SSE transport
- [x] StreamableHttp transport
- [x] Multiple simultaneous client connections (both transports)
- [x] Create puzzles (state machines) as dynamic resources
- [x] Subscribe to puzzles
- [x] Receive update notifications when puzzles change
- [x] Get puzzle snapshot (current state and available actions)
- [x] Change puzzle state by performing action on puzzle
- [ ] Resource creation by puzzle state (used by agents and guard prompts)
- [ ] Transition guard prompt creation (uses resources by state)
- [ ] Transition guard via sampling
- [ ] Command line REPL
- [ ] Demo via REPL
What problem does puzzlebox address?
Collaboration and coordination are related but different problems. Collaboration is good for non-trivial yet relatively simple tasks. To tackle long horizon efforts, puzzlebox solves for coordination.
Teams need coordination
Marshalling multiple agents toward a big goal is tougher than just breaking down a request into tasks, assigning them to available agents and enabling collaboration between them.
Just as a few agents can collaborate to complete a small project, several teams of process-aware agents need to operate within distinct project phases to tackle long horizon efforts.
Consider enterprise-level software development processes:
- A large software project typically moves th
17e2327d49ffOBSERVED · 2026-10-09Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add puzzlebox -- npx -y [email protected]
{
"mcpServers": {
"puzzlebox": {
"command": "npx",
"args": [
"-y",
"[email protected]"
]
}
}
}Exposed tools (5)
4 read · 1 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
add_puzzle | write | Add a puzzle |
calculator | read | A calculator |
count_puzzles | read | Count puzzles |
get_puzzle_snapshot | read | Get a snapshot of a puzzle (its current state and available actions). |
perform_action_on_puzzle | read | Perform an action on a puzzle (attempt a state transition). |
Trust audit
BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- none-observed
- Network
- declared (5 observation(s))
- Shell
- declared (1 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (13)
var makeValidate = new Function(
sse,streamable-http
.prettierignore
import { getTestPuzzleConfig } from "../../common/utils.ts";import { getTestPuzzleConfig } from "../../common/utils.ts";import { getTestPuzzleConfig } from "../../common/utils.ts";import { PuzzleConfig } from "../../common/schemas.js";import PuzzleStore from "../../stores/PuzzleStore.ts";
const decoded = JSON.parse(atob(base64));
const decodedCursor = parseInt(atob(cursor), 10);
@modelcontextprotocol/inspector, @modelcontextprotocol/sdk, @types/supertest, mcp-proxy, node-fetch, tsx, supertest, @types/cors
dist/sse.js
dist/streamableHttp.js
Gates applied: no_behavioural_pass.
17e2327d49fffull audit observations/trust-audit/mcp-server/cliffhall__puzzlebox.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-09 | 17e2327d49ff | BLOCK | D | 69 | first audit |
Questions
What is the 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.
What tools does Puzzlebox expose?
5 in total: 4 read-only, 1 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is Puzzlebox safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (69/100) and found 1 critical or high issue in the source. Each one is listed on this page with the file and line it is on.
What credentials does Puzzlebox need?
No credential environment variables were found in its source, so it appears to need none.
How does Puzzlebox run?
It speaks sse and streamable-http, so it runs as a service you connect to over the network. It is published on npm as puzzlebox at 1.0.0.
How current is this page?
The grade is for one exact copy of the source (17e2327d49ff), read on 2026-10-09. The repository is watched and re-audited when it changes.