puzzlebox

• 工具代码的单元测试
• MCP 服务的集成测试（包括 SSE 和 StreamableHttp）
• SSE 传输
• StreamableHttp 传输
• 支持多个客户端同时连接（两种传输方式均支持）
• 将谜题（状态机）创建为动态资源
• 订阅谜题
• 在谜题发生变化时接收更新通知
• 获取谜题快照（当前状态和可用操作）
• 通过对谜题执行操作来改变其状态
• 根据谜题状态创建资源（供 Agent 和守卫提示词使用）
• 创建转换守卫提示词（使用按状态划分的资源）
• 通过采样执行转换守卫
• 命令行 REPL
• 通过 REPL 演示

团队需要协调

将多个 Agent 集结起来实现一个大目标，远不只是把请求拆解成任务、分配给可用的 Agent，并让它们协作那么简单。

正如少数 Agent 可以协作完成一个小型项目，多个具备流程意识的 Agent 团队也需要在不同项目阶段中开展工作，以应对长期工作。

以企业级软件开发流程为例：

• 一个大型软件项目通常会经历多个步骤，偶尔还会回退，从构思、设计、构建、测试、文档编写、营销到投产。

• 随着项目推进，不同团队会专注于不同方面；他们会参考以往的进展，并着眼于不断变化的目标，根据吸取的经验不断完善目标。

• 即使在一个阶段内，团队也可能像敏捷冲刺一样循环经历自己的各个阶段。团队为冲刺确定一定范围的工作，各自完成负责的部分，并在冲刺结束时决定下一步处理什么。团队需要接受，每个冲刺都可能改变未来开发的方向。这些循环也可以表示为谜题。

借助 puzzlebox，Agent 团队的成员可以具备流程意识，而流程本身不会受到幻觉影响。

场景：团队交接工作

三个 Agent 正在工作。他们共享的谜题当前处于“Specification”（规范）状态。

• Agent 1 正在定义领域语言。
• Agent 2 正在确定项目范围。
• Agent 3 正在编写规范文档。
• 这些 Agent 协作完成最终的规范文档。
• 规范完成后，Agent 3 会发起到“Design”（设计）状态的转换。
  • 首先，由退出守卫（即 LLM 采样）检查规范是否完整。
    • 如果发现问题，则取消状态转换，团队继续工作。
    • 如果检查通过，则状态变为“Design”。
      • “Specification”团队的 Agent 正在监控谜题，此时应该结束工作。
        • 它们漫长而昂贵的上下文已提炼进规范中。
        • “Design”团队从这里接手，使用规范作为资源，并以全新且针对各自角色的上下文开展工作。

谜题的属性

• 有限数量的离散状态，例如“系列概念与基调”、“世界构建”、“情节弧线规划”、“剧集规划”、“情节线融合”、“剧集大纲”、“剧本写作”等。
• 每个状态可以有任意数量的操作（包括 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 服务实现，具有以下功能：

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

工作原理

1. 客户端连接到 puzzlebox SSE 服务。
2. 客户端向服务注册谜题。
3. 客户端可以订阅指定谜题，以便在其状态发生变化时接收更新。
4. 客户端对谜题执行操作，这些操作可能会改变其状态和可用操作。
5. puzzlebox 服务会确保任何尝试的操作对于给定谜题的当前状态都是有效的。
6. 如果操作有效，则会启动向目标状态的转换。
7. 转换过程中，可选的退出和进入守卫可能会向客户端发送采样请求；请求结果可能导致转换取消（可将其视为利益相关者进行的验收测试）。
8. 如果守卫检查通过，状态转换便会完成。
9. 客户端收到资源更新通知后，可以读取资源，也可以使用 get_puzzle_snapshot 工具获取当前状态和可用操作。
10. 客户端根据新状态更新其 UI。

⚙️ 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
• 必须先启动，然后才能运行 Inspector

Inspector

• npm run inspector
• 运行 Model Context Protocol Inspector
• Inspector 界面将在此地址提供：http://localhost:5173
• 在 Inspector 界面中：
  • 确保 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 Inspector 进行了测试。

0 - 列出工具

1 - 添加拼图

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

3 - 对拼图执行操作

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

5 - 对拼图执行操作

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

7 - 列出资源

8 - 资源模板

9 - 未订阅的资源

10 - 已订阅的资源

11 - 资源更新通知