Puzzlebox

拼图盒

使用状态机协调代理

MCP 服务器将有限状态机作为动态资源托管，客户端可以订阅该资源并在其状态发生变化时进行更新。

Puzzlebox 解决了什么问题？

团队需要协调

指挥多个代理完成一个大目标比仅仅将请求分解为任务、将它们分配给可用的代理并实现它们之间的协作要困难得多。

正如几个代理可以合作完成一个小项目一样，几个具有流程意识的代理团队需要在不同的项目阶段内运作，以应对长期工作。

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

• 大型软件项目通常会经历多个步骤，偶尔会回溯，从开始到设计到构建到测试到文档到营销到生产。
• 随着时间的推移，不同的团队会关注不同的方面，根据过去的经验，着眼于不断变化的目标，并根据经验教训不断改进。
• 即使在一个阶段内，团队也可能循环执行各自的阶段，就像敏捷冲刺一样。冲刺阶段会设定一定的工作量，团队会各自完成各自的部分，并在冲刺结束时决定下一步要解决的问题。它承认每个冲刺都可能改变未来的开发进程。这些循环也可以用谜题来表示。

通过 Puzzlebox，代理团队的成员可以感知流程，但流程本身不会受到幻觉的影响。

场景：团队传递火炬

三位智能体正在工作。他们共享的谜题的当前状态为“规范”。

• 代理 1 正在指定域语言。
• 代理 2 正在定义项目范围。
• 代理 3 正在制作规范文档。
• 代理商们齐心协力达成最终的规范文件。
• 一旦规范完成，代理 3 就会启动向“设计”状态的转换。
  • 首先，通过出口守卫（即 LLM 抽样）检查规范的完整性。
    • 如果发现问题，则取消状态转换并让团队继续工作。
    • 如果可以接受，状态将变为“设计”。
      • “规范”代理正在监控谜题，现在应该下班了。
        • 它们的长（且昂贵的）背景已被提炼到规范中。
        • “设计”团队从这里进行选择，以规范作为资源，其背景是新鲜的且特定于角色的。

什么是谜题？

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

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

谜题的属性

• 有限数量的离散状态，例如“系列概念和基调”、“世界构建”、“弧线情节”、“剧集规划”、“情节线融合”、“剧集大纲”、“剧本写作”等。
• 每个状态可以有任意数量的动作（包括 0）来启动向另一个状态的转换。
• 有一个初始状态。
• 对拼图执行操作后，当前状态可能会有所不同。
• 转换可以通过状态退出和进入保护来取消，例如，通过客户采样请求咨询 LLM。

一个简单的例子

什么是 Puzzlebox？

多客户端共享动态资源

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

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

工作原理

1. 客户端连接到 Puzzlebox SSE 服务器。
2. 客户端向服务器注册谜题。
3. 客户端可以订阅给定的谜题，以便在其状态发生变化时接收更新。
4. 客户端对谜题执行的操作可能会改变其状态和可用的操作。
5. 拼图盒服务器确保任何尝试的操作对于给定拼图的当前状态都是有效的。
6. 如果动作有效，则启动向目标状态的转换。
7. 在转换期间，可选的出口和进入保护可能会向客户端发送采样请求，其结果可能会导致转换取消（想想利益相关者的验收测试）
8. 如果守卫通过，状态转换就完成。
9. 当客户端收到资源更新通知时，他们可以读取资源或使用get_puzzle_snapshot工具获取当前状态和可用操作。
10. 客户端根据新状态更新其 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 对象

本地设置

安装依赖项

• cd /path/to/puzzlebox/
• npm install

建造

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

开始

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

检查员

• npm run inspector
• 运行模型上下文协议检查器
• 检查器 UI 可在以下网址访问： http://localhost:5173
• 在检查器 UI 中：
  • 确保Transport Type设置为SSE
  • 确保URL设置为http://localhost:3001/sse
  • 单击其**“连接”**按钮即可连接到 Puzzlebox 服务器。
    • 您应该会看到绿灯🟢和**“已连接”**消息。
  • 单击其列表工具按钮

格式

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

类型检查

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

皮棉

• npm run lint
• 运行eslint以非破坏性方式检查并报告语法问题

LintFix

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

测试

• npm run test
• 运行单元测试

截图

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

0 - 列出工具

1 - 添加拼图

2 - 获取拼图快照（初始状态）

3 - 对谜题执行操作

4 - 获取拼图快照（新状态）

5 - 对谜题执行操作

6 - 获取拼图快照（另一个新状态）

7 - 列出资源

8 - 资源模板

9 - 取消订阅的资源

10 - 订阅资源

11 - 资源更新通知