
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
概覽
一個本機 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 模式。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Mcp State Sidecar,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
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:
If you want to use the Redis backend:
Building from Source
To build and install the package from source:
- Clone the repository:
- Install build dependencies:
- Build the wheel and source distribution:
- Install the package locally: Or install the package in editable mode for active development:
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:
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:
Configuration
The server is configured entirely using environment variables:
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 (returnsfound=Falseif 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 uniquerun_id.workflow_discover(tags?, status?): Find workflows filtered by tags or status.workflow_claim(run_id, agent_id): Atomically claim acreatedworkflow.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版本歷史
1- v0.1.0最新Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分