Mcp State Sidecar

io.github.askadvaith由 GitHub 帳號 askadvaith 發布v0.1.0更新於 Oct 24, 2026

MCP State Sidecar: durable state persistence for multi-agent AI workflows

概覽

AI 產生的概覽

一個本機 MCP 伺服器,為多代理工作流程提供持久狀態儲存:鍵值資料、工作流程認領、租約、工作階段與稽核歷程。

可以做什麼
  • 讀取、寫入、列出與刪除可選 TTL 的 JSON 鍵值項目。
  • 建立、探索、認領、檢查點、續接與列出工作流程及其執行 ID。
  • 取得、續期與釋放專屬租約以控制並行。
  • 儲存與還原工作階段快照,並讀取最近的狀態變更歷程。
  • 查看 sidecar 健康狀態與後端指標,或清空全部資料。
適用情境
當多個代理或程序需要共用能在當機、水平擴充或更換框架後仍保留的狀態,並希望透過 MCP 工具而非行程內記憶體或帶外通訊來協調時適用。
執行需求
以 pip 安裝的 Python 套件在本機執行;Redis 後端需安裝 redis 附加元件並連上可用的 Redis 位址。透過 STATE_BACKEND、DB_PATH、REDIS_URL、SIDECAR_HOST、SIDECAR_PORT 等環境變數設定。支援本機子行程的 stdio 模式,或預設綁定 0.0.0.0、連接埠 8000 的 HTTP SSE 模式。
安裝前請注意
HTTP SSE 模式預設綁定所有網路介面,能連上該連接埠的人可能讀取或修改已存狀態,且未宣告任何驗證機制。sidecar_reset 會不可逆地清空全部資料,工作流程認領、檢查點與租約操作也會改動共用狀態。資料存於本機 SQLite 檔案或 Redis 執行個體,需妥善保護該儲存。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Mcp State Sidecar,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

MCP State Sidecar Server

[PyPI version] [PyPI - Python Version] [License: MIT] [MCP Registry]

An MCP-native state sidecar that externalises workflow state for distributed agent deployments.

Quite a simple idea really; instead of storing state inside agents (which breaks when processes crash, scale horizontally, or span multiple frameworks), agents write to and read from this sidecar over the Model Context Protocol (MCP). The sidecar is itself an MCP server; agents call its tools exactly the same way they call any other tool!

The server itself is built with distributed environments in mind, and natively handles concurrency, crash resilience and atomic claims in addition to being a common interface for state management between agents.

Features

  • Durable Key-Value Store: CRUD operations with optional TTL (Time-To-Live).
  • Workflow Lifecycle Registry: Centralised coordination (create, claim, checkpoint, and resume) for distributed multi-agent workers without out-of-band communication.
  • TTL Leases & Locks: Concurrency control to prevent race conditions and split-brain scenarios.
  • Audit Logging & Session Snapshotting: Audit state transitions and persist session contexts.
  • Multiple Backends: SQLite (with WAL mode & serialisation) and high-concurrency Redis currently supported.

Installation

Install the package via pip or your favorite Python package manager:

bash
pip install mcp-state-sidecar

If you want to use the Redis backend:

bash
pip install mcp-state-sidecar[redis]

Building from Source

To build and install the package from source:

  1. Clone the repository:
    bash
    git clone https://github.com/askadvaith/MCP-State-Sidecar.gitcd MCP-State-Sidecar
  2. Install build dependencies:
    bash
    pip install --upgrade build
  3. Build the wheel and source distribution:
    bash
    python -m build
  4. Install the package locally:
    bash
    pip install dist/mcp_state_sidecar-*.whl
    Or install the package in editable mode for active development:
    bash
    pip install -e .

Quick Start

Running the Server

In a multi-agent distributed environment, you would typically run the state sidecar as an HTTP SSE service so multiple remote agents and clients can connect to it concurrently.

HTTP SSE Mode (Primary for Distributed Environments)

Start the SSE server to listen on a network port:

bash
mcp-state-sidecar-http

By default, the server binds to 0.0.0.0 and listens on port 8000. The MCP endpoint is available at http://localhost:8000/mcp.

Stdio Mode (For Subprocess / Local Agent Execution)

Launch the server via standard input/output:

bash
mcp-state-sidecar

Configuration

The server is configured entirely using environment variables:

Environment VariableDefaultDescription
STATE_BACKENDsqliteStorage backend: sqlite or redis
DB_PATHstate_sidecar.dbPath to the SQLite database file
REDIS_URLredis://localhost:6379Redis connection URL
SIDECAR_HOST0.0.0.0IP host to bind the HTTP SSE server
SIDECAR_PORT8000Port for the HTTP SSE server

Tool Reference

Group 1 — Key-Value Store

  • state_set(key, value, ttl_seconds?, agent_id?): Upsert a JSON-serialisable value with optional TTL.
  • state_get(key): Retrieve a value (returns found=False if missing or expired).
  • state_delete(key): Delete a key.
  • state_list(prefix?): List all live keys, optionally filtered by prefix.

Group 2 — Workflow Lifecycle

  • workflow_create(name, tags?): Register a workflow; returns a unique run_id.
  • workflow_discover(tags?, status?): Find workflows filtered by tags or status.
  • workflow_claim(run_id, agent_id): Atomically claim a created workflow.
  • workflow_checkpoint(run_id, step, output): Persist step output and advance the step counter.
  • workflow_resume(run_id): Get full resume context including last step and all step outputs.
  • workflow_status(run_id): Get lightweight status (status, last step, and timestamps).
  • workflow_list(): List all registered workflows.

Group 3 — Lease & Concurrency Control

  • lease_acquire(resource_id, holder_id, ttl_seconds): Attempt to acquire an exclusive lock.
  • lease_release(resource_id, holder_id): Voluntarily release a held lease.
  • lease_renew(resource_id, holder_id, ttl_seconds): Extend lease duration without releasing.

Group 4 — Sessions & History

  • session_save(session_id, context): Save a snapshot of workflow context.
  • session_restore(session_id): Retrieve saved context after crash or handoff.
  • history_log(key?, n?): Retrieve the last N state-transition records with timestamps and writer IDs.

Group 5 — Observability

  • sidecar_health(): Liveness, backend type, uptime, and database metrics.
  • sidecar_reset(): Irreversibly wipe all data.

License

This project is licensed under the MIT License. See LICENSE for details.

來源:README.md,提交 9a992d0

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.1.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分