使用说明

项目简介

Puzzlebox 是一个基于 Model Context Protocol (MCP) 的服务器实现，它将有限状态机（称为 "Puzzles"）作为资源进行管理。客户端可以订阅这些 puzzle 资源，并在 puzzle 状态改变时接收更新。Puzzlebox 旨在帮助协调多个智能体，使其能够感知流程状态，从而更好地完成复杂任务，例如企业级软件开发流程管理。

主要功能点

Puzzle (状态机) 管理: 支持添加、获取、操作和计数 puzzle 实例。
资源暴露: 将 puzzle 状态快照作为 MCP 资源暴露，客户端可以订阅资源更新。
工具 (Tools): 提供 'add_puzzle', 'get_puzzle_snapshot', 'perform_action_on_puzzle', 'count_puzzles' 等工具供客户端调用。
状态转换: 允许客户端执行 puzzle 的动作以触发状态转换。
SSE 传输: 使用 SSE (Server-Sent Events) 作为传输协议与 MCP 客户端通信。

安装步骤

安装 Node.js 和 npm: 确保你的系统已安装 Node.js 和 npm (建议使用 Node.js v18 或更高版本)。
下载仓库代码: 在终端中执行命令 'git clone https://github.com/cliffhall/puzzlebox' 下载仓库代码到本地。
进入项目目录: 使用 'cd puzzlebox' 命令进入项目目录。
安装依赖: 在项目目录下执行 'npm install' 命令安装项目依赖。
构建项目: 执行 'npm run build' 命令构建项目，生成服务器运行代码。

服务器配置

MCP 客户端需要配置以下 JSON 信息以连接 Puzzlebox MCP 服务器：

{
  "serverName": "puzzlebox",
  "command": "npm",
  "args": ["run", "start"]
}

'serverName': 为 MCP 服务器自定义的名称，例如 "puzzlebox"，用于在客户端中标识连接。
'command': 启动 Puzzlebox 服务器的命令，这里使用 'npm'，前提是你的环境中可以通过 'npm' 命令运行 Node.js 包管理器。
'args': 传递给 'npm' 命令的参数数组，'["run", "start"]' 指示 'npm' 运行 'package.json' 文件中定义的 'start' 脚本，该脚本负责启动 Puzzlebox 服务器。

基本使用方法

启动服务器: 在 puzzlebox 项目根目录下，执行命令 'npm run start' 启动 Puzzlebox 服务器。服务器默认监听 'http://localhost:3001/sse' 地址，使用 SSE 协议。
配置 MCP 客户端: 打开你的 MCP 客户端（例如 MCP Inspector），在服务器配置中，将 传输类型 (Transport Type) 设置为 'SSE'，URL 设置为 'http://localhost:3001/sse'，并填入上述服务器配置 JSON。
连接服务器: 在 MCP 客户端中点击 连接 (Connect) 按钮，客户端应成功连接到 Puzzlebox 服务器。
使用工具和资源: 连接成功后，你可以在 MCP 客户端中：
- 点击 List Tools 查看 Puzzlebox 提供的工具列表，例如 'add_puzzle', 'get_puzzle_snapshot', 'perform_action_on_puzzle', 'count_puzzles'。
- 调用工具，例如使用 'add_puzzle' 工具添加新的 puzzle 实例（需要提供符合 puzzle 结构的 JSON 配置作为参数）。
- 点击 List Resources 查看可用的资源模板，并根据模板订阅和读取 puzzle 资源，例如 'puzzlebox://puzzle/{puzzleId}'。
- 通过调用 'perform_action_on_puzzle' 工具，对指定的 puzzle 执行动作，观察 puzzle 状态的变化和资源更新通知。

关键词