状态机协调服务

• [x] 工具代码的单元测试
• [x] MCP服务器的集成测试（SSE和StreamableHttp）
• [x] SSE运输
• [x] 流式Http传输
• [x] 多个同时进行的客户端连接（两种传输方式）
• [x] 创建谜题（状态机）作为动态资源
• [x] 订阅谜题
• [x] 谜题更改时接收更新通知
• [x] 获取拼图快照（当前状态和可用操作）
• [x] 通过在拼图上执行动作来更改拼图状态
• []按谜题状态创建资源（由代理和守卫提示使用）
• []创建过渡保护提示（按状态使用资源）
• []通过取样进行过渡保护
• []命令行REPL
• []通过REPL演示

团队需要协调

将多个代理编组到一个大目标上比将请求分解为任务、将它们分配给可用代理和 促进协作 他们之间。

正如少数代理可以协作完成一个小项目一样，几个具有流程意识的代理团队需要在不同的项目阶段进行操作，以处理长期工作。

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

• 大型软件项目通常会经历一个多步骤的过程，偶尔会回溯从开始到设计、构建、测试、文档、营销到生产的过程。

• 随着时间的推移，不同的团队专注于不同的方面，了解过去的情况，并着眼于根据经验教训不断完善的不断变化的目标。

• 即使在一个阶段内，团队也可能在自己的阶段中循环，比如敏捷冲刺。一定量的工作是为冲刺确定的，团队各司其职，在冲刺结束时，他们决定下一步要处理什么。它承认每一次冲刺都可能改变未来的发展进程。这些循环也可以表示为谜题。

有了puzzlebox，代理团队的成员可以意识到过程，但过程本身不会产生幻觉。

场景：传递火炬的团队

三名特工正在工作。他们共同谜题的当前状态是“规范”。

• 代理1正在指定域语言。
• 代理2正在定义项目范围。
• 代理3正在生成规范文件。
• 代理协作以达成最终规范文件。
• 一旦规范完成，代理3将启动向“设计”状态的转换。
  • 首先，通过出口防护（即LLM采样）检查规范的完整性。
    • 如果发现问题，状态转换将被取消，团队将继续。
    • 如果可以接受，状态将更改为“设计”。
      • “规范”代理正在监控这个谜题，现在应该下班了。
        • 它们漫长（且昂贵）的上下文已被提炼到规范中。
        • “设计”团队从这里开始选择，将规范作为资源，其上下文新鲜且特定于角色。

一个你可以采取行动的有状态的东西

想象一下魔方谜题。它有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服务器 实施：

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

运作原理

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

⚙️ add_puzzle

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

• 输入： 无
• 退货： 带布尔值的JSON对象 success 和 puzzleId

⚙️ get_puzzle_snapshot

获取拼图的快照（其当前状态和可用操作）。

• 输入： puzzleId
• 退货： JSON对象 currentState 和 availableActions 数组
• 注： 不支持资源订阅的MCP客户端可以轮询此工具以观察状态变化。

⚙️ perform_action_on_puzzle

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

• 输入： puzzleId 和 actionName
• 退货： JSON对象 currentState 和 availableActions 数组

⚙️ count_puzzles

获取已注册谜题的数量

• 输入： 无
• 退货： 当前JSON对象 count 已注册的谜题

再进行

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

构建

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

开始

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

检查员

• npm run inspector
• 运行 模型上下文协议检查器
• Inspector UI将在以下位置提供：http://localhost:5173
• 在检查器UI中：
  • 确保 Transport Type 设置为 SSE
  • 确保 URL 设置为http://localhost:3001/sse
  • 点击其 “连接” 按钮连接到益智箱服务器。
    • 你应该看到绿灯了🟢和 “已连接” 消息。
  • 点击其 列出工具 按钮

格式

• npm run format
• 跑 prettier 在代码上，调整格式

类型检查

• npm run typecheck
• 跑 tsc 使用args检查和报告类型问题

棉绒

• npm run lint
• 跑 eslint 非破坏性地检查和报告语法问题

LintFix

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

测试

• npm run test
• 运行单元测试

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

0-列出工具

1-添加拼图

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

3-在拼图上执行动作

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

5-在拼图上执行动作

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

7-列出资源

8-资源模板

9-未订阅的资源

10-已订阅资源

11-资源更新通知