mcp-state-sidecar

MCP State Sidecar Server

分散エージェント環境向けに、ワークフローの状態を外部化するMCPネイティブな状態サイドカーです。

実にシンプルなアイデアです。プロセスのクラッシュや水平スケーリング、複数のフレームワークにまたがる運用で問題が起きるエージェント内部に状態を保存するのではなく、エージェントは**Model Context Protocol（MCP）**経由でこのサイドカーに状態を書き込み、読み取ります。サイドカー自体がMCP サーバーであり、エージェントは他のツールとまったく同じ方法でそのツールを呼び出します。

サーバーは分散環境を念頭に構築されており、エージェント間の状態管理に共通インターフェースを提供するだけでなく、並行処理、クラッシュ耐性、アトミックなロック取得をネイティブに処理します。

機能

• 永続的なキー・バリューストア：TTL（Time-To-Live）を任意で指定できるCRUD操作。
• ワークフローライフサイクルレジストリ：分散マルチエージェントワーカー間の連携（作成、ロック取得、チェックポイント、再開）を一元管理し、帯域外通信を不要にします。
• TTLリースとロック：競合状態やスプリットブレインシナリオを防ぐための並行制御。
• 監査ログとセッションスナップショット：状態遷移を監査し、セッションコンテキストを永続化します。
• 複数のバックエンド：SQLite（WALモードとシリアライズ対応）および高並行性のRedisを現在サポートしています。

---

インストール

pipまたは任意のPythonパッケージマネージャーを使ってパッケージをインストールします。

pip install mcp-state-sidecar

Redisバックエンドを使用する場合：

pip install mcp-state-sidecar[redis]

ソースからのビルド

ソースからパッケージをビルドしてインストールするには：

1. リポジトリをクローンします。

   git clone https://github.com/askadvaith/MCP-State-Sidecar.git
   cd MCP-State-Sidecar
   

2. ビルド依存関係をインストールします。

   pip install --upgrade build
   

3. wheelとソースディストリビューションをビルドします。

   python -m build
   

4. パッケージをローカルにインストールします。

   pip install dist/mcp_state_sidecar-*.whl
   

   または、開発中にパッケージを編集可能モードでインストールします。

   pip install -e .
   

---

クイックスタート

サーバーの起動

マルチエージェントの分散環境では、通常、複数のリモートエージェントとクライアントが同時に接続できるよう、状態サイドカーをHTTP SSEサービスとして実行します。

HTTP SSEモード（分散環境での主な実行方法）

SSEサーバーを起動し、ネットワークポートで待ち受けます。

mcp-state-sidecar-http

デフォルトでは、サーバーは0.0.0.0にバインドし、ポート8000で待ち受けます。MCPエンドポイントはhttp://localhost:8000/mcpで利用できます。

Stdioモード（サブプロセス／ローカルエージェントでの実行）

標準入出力経由でサーバーを起動します。

mcp-state-sidecar

---

設定

サーバーは環境変数のみで設定します。

環境変数	デフォルト	説明
STATE_BACKEND	sqlite	ストレージバックエンド：sqliteまたはredis
DB_PATH	state_sidecar.db	SQLiteデータベースファイルのパス
REDIS_URL	redis://localhost:6379	Redis接続URL
SIDECAR_HOST	0.0.0.0	HTTP SSEサーバーをバインドするIPホスト
SIDECAR_PORT	8000	HTTP SSEサーバーのポート

---

ツールリファレンス

グループ1 — キー・バリューストア

• state_set(key, value, ttl_seconds?, agent_id?)：TTLを任意で指定して、JSONシリアライズ可能な値を挿入または更新します。
• state_get(key)：値を取得します（キーが存在しないか期限切れの場合はfound=Falseを返します）。
• state_delete(key)：キーを削除します。
• state_list(prefix?)：有効なキーをすべて一覧表示します。プレフィックスでの絞り込みもできます。

グループ 2 — ワークフローのライフサイクル

• workflow_create(name, tags?): ワークフローを登録し、一意の run_id を返します。
• workflow_discover(tags?, status?): タグまたはステータスでフィルタリングしたワークフローを検索します。
• workflow_claim(run_id, agent_id): created 状態のワークフローをアトミックに確保します。
• workflow_checkpoint(run_id, step, output): ステップの出力を保存し、ステップカウンターを進めます。
• workflow_resume(run_id): 最後のステップとすべてのステップ出力を含む、再開用の完全なコンテキストを取得します。
• workflow_status(run_id): 簡易ステータス（ステータス、最後のステップ、タイムスタンプ）を取得します。
• workflow_list(): 登録済みのすべてのワークフローを一覧表示します。

グループ 3 — リースと同時実行制御

• lease_acquire(resource_id, holder_id, ttl_seconds): 排他ロックの取得を試みます。
• lease_release(resource_id, holder_id): 保持中のリースを自発的に解放します。
• lease_renew(resource_id, holder_id, ttl_seconds): リースを解放せずに有効期間を延長します。

グループ 4 — セッションと履歴

• session_save(session_id, context): ワークフローコンテキストのスナップショットを保存します。
• session_restore(session_id): クラッシュまたは引き継ぎ後に保存済みコンテキストを取得します。
• history_log(key?, n?): タイムスタンプと書き込み元 ID を含む、直近 N 件の状態遷移記録を取得します。

グループ 5 — 可観測性

• sidecar_health(): 稼働状況、バックエンドの種類、稼働時間、データベースのメトリクスを取得します。
• sidecar_reset(): すべてのデータを元に戻せない形で消去します。

---

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細は LICENSE を参照してください。