puzzlebox

使用状态机协调代理

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

puzzlebox 解决了什么问题？

协作和协调是相关但不同的问题。协作适用于非平凡但相对简单的任务。为了解决长期任务，puzzlebox 解决了协调问题。

团队需要协调

将多个代理引导到一个大目标比仅仅将请求分解为任务、分配给可用代理并启用它们之间的协作要困难得多。

正如几个代理可以协作完成一个小项目一样，几组具有流程意识的代理需要在不同的项目阶段内操作，以应对长期任务。

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

一个大型软件项目通常需要经过多步骤的路径，偶尔会从概念到设计、构建、测试、文档、营销、生产等阶段回溯。
随着时间的推移，不同的团队会关注不同的方面，根据之前的经验进行调整，并根据学到的经验教训不断完善不断变化的目标。
即使在一个阶段内，团队也可能经历自己的阶段循环，比如敏捷冲刺。为冲刺范围确定一定量的工作，团队完成各自的部分，然后在冲刺结束时决定下一步要处理什么。它接受每个冲刺都可能改变未来开发的方向。这些循环也可以表示为谜题。

通过 puzzlebox，代理团队的成员可以具有流程意识，但流程本身不会受到幻觉的影响。

场景：团队交接

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

代理 1 正在指定领域语言。
代理 2 正在定义项目范围。
代理 3 正在生成规范文档。
代理们协作完成最终的规范文档。
一旦规范完成，代理 3 启动向“Design”状态的转换。
- 首先，规范由退出守卫（即 LLM 采样）检查其完整性。
  - 如果发现问题，状态转换被取消，团队继续工作。
  - 如果可接受，状态更改为“Design”。
    - “Specification”代理正在监控谜题，现在应该退出。
      - 他们长期（且昂贵）的上下文已被提炼为规范。
      - “Design”团队从这里接手，以规范为资源，他们的上下文是新鲜的且与角色相关。

什么是谜题？

谜题是一个有限状态机。只是更容易说、写和思考。

一个你可以操作的有状态事物

想象一下魔方谜题。它有 43 万亿个状态，要在它们之间转换，你通过旋转机制的交错平面来操作它。

谜题的属性

有限数量的离散状态，例如“系列概念和基调”、“世界构建”、“弧线绘制”、“集规划”、“情节线混合”、“集大纲”、“剧本写作”等。
每个状态可能有任意数量的操作（包括 0）可以启动向另一个状态的转换。
有一个初始状态。
有一个当前状态，可能在执行操作后发生变化。
转换可以通过状态退出和进入守卫取消，例如通过客户端采样请求咨询 LLM。

一个简单的例子

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

大多数 MCP 服务器与客户端是一对一的关系。puzzlebox 不同。

多个客户端共享动态资源

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

支持多个客户端连接，可以创建和监控共享的动态资源。
管理谜题实例
提供以下工具：
- 添加谜题
- 获取给定谜题的当前状态和可用操作的快照
- 对给定谜题执行操作，触发状态转换
将注册的谜题暴露为资源
- 客户端可以使用 Puzzle Snapshot 资源模板通过 ID 获取资源
- 资源 URI 为 puzzlebox:/puzzle/{puzzleId}
- 客户端可以订阅/取消订阅单个资源 URI

工作原理

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

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 对象

本地设置

在本地运行需要安装 Node 和 npm。然后按照以下步骤操作...

安装依赖

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 中：
- 确保 Transport Type 设置为 SSE
- 确保 URL 设置为 http://localhost:3001/sse
- 点击其 "Connect" 按钮以连接到 puzzlebox 服务器。
  - 您应该看到绿灯 🟢 和 "Connected" 消息。
- 点击其 List Tools 按钮

格式化

npm run format
在代码上运行 prettier，调整格式

类型检查

npm run typecheck
运行 tsc 检查并报告类型问题

代码检查

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

代码修复

npm run lint:fix
运行 eslint 检查并修复语法问题

测试

npm run test
运行单元测试

截图

这些截图显示了服务器实现的各种 MCP 工具和资源。

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

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