パズルボックス

エージェントとステートマシンの連携

クライアントがサブスクライブして状態の変化に応じて更新できる動的リソースとして有限状態マシンをホストするMCP サーバー。

Related MCP server: A2AMCP

パズルボックスはどのような問題に対処しますか?

チームには連携が必要

複数のエージェントを大きな目標に向けてまとめることは、リクエストをタスクに分割し、それらを利用可能なエージェントに割り当て、エージェント間のコラボレーションを可能にすることよりも困難です。

少数のエージェントが協力して小規模なプロジェクトを完了できるのと同様に、プロセスを認識しているエージェントの複数のチームが、長期にわたる取り組みに取り組むために、個別のプロジェクトフェーズ内で活動する必要があります。

エンタープライズ レベルのソフトウェア開発プロセスを検討します。

• 大規模なソフトウェア プロジェクトは通常、構想から設計、構築、テスト、ドキュメント作成、マーケティング、生産まで、複数のステップを経て、場合によっては後戻りしながら進みます。

• それぞれのチームが、過去の経験に基づいて、学んだ教訓に基づいて改善される常に変化する目標に目を向けながら、時間の経過とともにさまざまな側面に焦点を当てます。

• フェーズ内でも、チームはアジャイルスプリントのように、独自のフェーズを循環させることがあります。スプリントには一定の作業範囲が設定され、チームは担当する作業に取り組み、スプリント終了時に次の作業を決定します。各スプリントが将来の開発の方向性を変える可能性があることを前提としています。これらのサイクルは、パズルとして表現することもできます。

パズルボックスを使用すると、エージェントチームのメンバーにプロセスを認識させることができますが、プロセス自体は幻覚の対象にはなりません。

シナリオ: チームがバトンを渡す

3人のエージェントが作業中です。共有パズルの現在の状態は「仕様」です。

• エージェント 1 はドメイン言語を指定しています。

• エージェント 2 はプロジェクトの範囲を定義しています。

• エージェント 3 は仕様書を作成しています。

• エージェントは協力して最終的な仕様書を作成します。

• 仕様が完成すると、エージェント 3 は「設計」状態への移行を開始します。

  • まず、仕様は終了ガード (つまり、LLM サンプリング) によって完全性がチェックされます。

    • 問題が見つかった場合、状態遷移はキャンセルされ、チームは続行されます。

    • 承認された場合、状態は「設計」に変わります。

      • 「仕様」エージェントはパズルを監視しており、今すぐ退勤する必要があります。

        • それらの長い（そして高価な）コンテキストは仕様に凝縮されています。

        • 「設計」チームは、仕様をリソースとして、コンテキストを新しく役割に応じてここから選択します。

パズルとは何ですか？

アクションを実行できる状態のもの

ルービックキューブを想像してみてください。43京通りの状態があり、それらの状態間を遷移させるには、キューブの交差面を回転させる必要があります。

パズルの特性

• 有限の数の個別の状態、例:「シリーズのコンセプトとトーン」、「世界の構築」、「アークのプロット」、「エピソードの計画」、「プロットラインのブレンド」、「エピソードのアウトライン」、「脚本の執筆」など。

• 各状態には、別の状態への遷移を開始する任意の数のアクション (0 を含む) を設定できます。

• 初期状態があります。

• パズルに対してアクションを実行した後には、現在の状態が変化する可能性があります。

• 遷移は、状態の終了ガードと開始ガードによってキャンセルできます。たとえば、クライアント サンプリング要求を介して LLM に相談します。

簡単な例

パズルボックスとは何ですか?

動的なリソースを共有する多くのクライアント

Puzzlebox は、次の機能を備えたMCP サーバー実装です。

• 共有の動的リソースを作成および監視できる複数のクライアント接続をサポートします。

• パズルのインスタンスを管理する

• 次のツールを公開します:

  • パズルを追加する

  • ボックス内の特定のパズルの状態と利用可能なアクションのスナップショットを取得する

  • ボックス内の特定のパズルに対して状態遷移を引き起こすアクションを実行する

• 登録したパズルをリソースとして公開する

  • クライアントは、 Puzzle Snapshotリソーステンプレートを使用して、IDでリソースを取得できます。

  • リソースURIはpuzzlebox:/puzzle/{puzzleId}です

  • クライアントは個々のリソースURIをサブスクライブ/アンサブスクライブできる

仕組み

1. クライアントはパズルボックス 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でSSEベース/MCPサーバーを起動します。

• INSPECTORを実行する前に起動する必要があります

検査官

• npm run inspector

• モデルコンテキストプロトコルインスペクタを実行します

• インスペクターUIは次の場所で利用できます: http://localhost:5173

• インスペクター UI の場合:

  • Transport TypeがSSEに設定されていることを確認してください

  • URLがhttp://localhost:3001/sseに設定されていることを確認してください

  • **「接続」**ボタンをクリックして、パズルボックス サーバーに接続します。

    • 緑色のライト🟢と**「接続済み」**メッセージが表示されます。

  • リストツールボタンをクリックします

形式

• 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 - リソース更新通知