PuzzleBox 状态机协调器

@cliffhall/puzzlebox

0 Stars 377 次浏览 cliffhall 更新于 2026-08-23

一个MCP服务器，通过共享的有限状态机（谜题）实现代理之间的协调，客户端可以创建、监控和触发有状态资源的状态转换。

知识管理与记忆开发者工具

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

puzzlebox

用状态机协调代理

一个 MCP 服务器，托管有限状态机作为动态资源，客户端可以订阅这些资源，并在它们的状态发生变化时得到更新。

puzzlebox 解决了什么问题？

团队需要协调

将多个代理协调到一个大目标上，比仅仅将请求分解成任务、分配给可用的代理并启用协作要复杂得多。

正如几个代理可以协作完成一个小项目一样，多个过程感知的代理团队需要在不同的项目阶段内运作，以应对长期的努力。

考虑企业级软件开发流程：

一个大型软件项目通常会经过从概念到设计、构建、测试、文档、营销再到生产的多步骤路径，有时还会回溯。
不同的团队在不同时间专注于不同的方面，根据之前的成果进行调整，并且始终关注不断变化的目标，该目标会根据所学到的经验进行完善。
即使在一个阶段内，团队也可能经历自己的阶段循环，如敏捷冲刺。一定数量的工作被规划到冲刺中，团队成员各自工作，在冲刺结束时决定下一步要做什么。它接受每个冲刺都可能改变未来开发方向的事实。这些循环也可以表示为谜题。

使用 puzzlebox，代理团队的成员可以变得过程感知，但过程本身不会产生幻觉。

场景：团队传递火炬

三个代理正在工作。他们共享的谜题当前状态是“规范”。

代理 1 正在指定领域语言。
代理 2 正在定义项目范围。
代理 3 正在生成规范文档。
代理们协作以完成最终的规范文档。
一旦规范完成，代理 3 将启动向“设计”状态的转换。
- 首先，规范由退出守卫（即 LLM 抽样）检查完整性。
  - 如果发现问题，状态转换将被取消，团队继续工作。
  - 如果通过，则状态变为“设计”。
    - “规范”代理正在监控谜题，现在应该下班。
      - 他们的长时间（且昂贵）的上下文已经被提炼到规范中。
      - “设计”团队从此处接手，以规范为资源，他们的上下文是新鲜且角色特定的。

什么是谜题？

你可以对其采取行动的有状态事物

想象一下魔方谜题。它有43京种状态，要在这之间转换，你需要通过旋转机制中的相交平面来操作它。

谜题的属性

有限数量的离散状态，例如，“系列概念和基调”、“世界观构建”、“故事弧线规划”、“集数计划”、“情节融合”、“集数大纲”、“剧本写作”等。
每个状态可能有任意数量的动作（包括0）来启动到另一个状态的转换。
存在一个初始状态。
当前状态在对谜题执行动作后可能会有所不同。
通过状态退出和进入守卫可以取消转换，例如，通过客户端采样请求咨询大语言模型。

一个简单的例子

{
  "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" }
      }
    }
  }
}

什么是puzzlebox？

多个客户端共享动态资源

Puzzlebox是一个MCP服务器实现，它：

支持多个客户端连接，这些客户端可以创建并监控共享的、动态的资源。
管理谜题实例
提供工具用于：
- 添加谜题
- 获取盒中给定谜题的状态快照及其可用动作
- 在盒中的给定谜题上执行触发状态转换的动作
将注册的谜题作为资源暴露出来
- 客户端可以使用Puzzle Snapshot资源模板按ID获取资源
- 资源URI为puzzlebox:/puzzle/{puzzleId}
- 客户端可以订阅/退订个别资源URI

工作原理

客户端连接到puzzlebox SSE服务器。
客户端向服务器注册谜题。
客户端可以订阅特定谜题以接收其状态更改时的通知。
客户端在谜题上执行可能导致状态及可用动作变化的动作。
puzzlebox服务器确保尝试执行的动作对于给定谜题的当前状态是有效的。
如果动作有效，则启动到目标状态的转换。
在转换过程中，可选的退出和进入守卫可能会向客户端发送采样请求，结果可能导致转换被取消（类似于利益相关者的验收测试）。
如果守卫通过，则状态转换完成。
当客户端收到资源更新通知时，他们可以选择读取资源或使用get_puzzle_snapshot工具获取当前状态及可用动作。
客户端根据新状态更新其用户界面。

MCP工具

⚙️ `add_puzzle`

添加一个新的谜题实例（有限状态机）。

输入： 无
返回： 包含布尔值success和puzzleId的JSON对象

⚙️ `get_puzzle_snapshot`

获取谜题的快照（其当前状态及可用动作）。

输入: puzzleId
返回: 包含 currentState 和 availableActions 数组的 JSON 对象
注意: 不支持资源订阅的 MCP 客户端可以通过轮询此工具来监视状态变化。

⚙️ `perform_action_on_puzzle`

在谜题上执行一个动作（尝试状态转换）。

输入: puzzleId 和 actionName
返回: 包含 currentState 和 availableActions 数组的 JSON 对象

⚙️ `count_puzzles`

获取已注册谜题的数量

输入: 无
返回: 包含当前已注册谜题数量 count 的 JSON 对象

本地设置

安装依赖

cd /path/to/puzzlebox/
npm install

构建

npm run build
在 /dist/index.js 构建 MCP 服务器运行时

启动

npm run start
在端口 :3001 上启动基于 SSE/MCP 的服务器，端点为 /sse
必须在运行检查器之前启动

检查器

npm run inspector
运行 Model Context Protocol Inspector
检查器 UI 将在 http://localhost:5173 可用
在检查器 UI 中：
- 确保 传输类型 设置为 SSE
- 确保 URL 设置为 http://localhost:3001/sse
- 点击其 “连接” 按钮以连接到 puzzlebox 服务器。
  - 您应该看到绿灯 🟢 和 “已连接” 消息。
- 点击其 列表工具 按钮

格式化

npm run format
使用 prettier 调整代码格式

类型检查

npm run typecheck
使用参数运行 tsc 来检查并报告类型问题

代码检查

npm run lint
非破坏性地使用 eslint 检查并报告语法问题

修复代码检查问题

npm run lint:fix
使用 eslint 检查并修复语法问题

测试

npm run test
运行单元测试

屏幕截图

服务器测试是使用官方参考客户端 - MCP 检查器完成的。

0 - 列表工具

0. list_tools

1 - 添加谜题

1. add_puzzle

2 - 获取谜题快照（初始状态）

2. get_puzzle_snapshot

3 - 在谜题上执行动作

3. perform_action_on_puzzle

4 - 获取谜题快照（新状态）

4. get_puzzle_snapshot

5 - 在谜题上执行动作

5. perform_action_on_puzzle

6 - 获取谜题快照（另一个新状态）

6. get_puzzle_snapshot

7 - 列表资源

7. list resources

8 - 资源模板

8. resource_template

9 - 未订阅的资源

9. unsubscribed resource

10 - 已订阅的资源

10. unsubscribed resource

11 - 资源更新通知

11. subscribed resource updated

注意：在“10 - 已订阅的资源”部分，原英文中的图片描述似乎有误（仍为"unsubscribed resource"），但根据上下文，这里假设应翻译为“已订阅的资源”。如果需要保持原文，请告知我进行相应调整。

查看源码项目主页