mcp-state-sidecar

MCP State Sidecar Server

一款原生支持 MCP 的状态 Sidecar，可为分布式 Agent 部署提供外置工作流状态。

这个想法其实很简单：与其把状态存储在 Agent 内部（进程崩溃、横向扩展或跨多个框架时都会导致问题），不如让 Agent 通过 Model Context Protocol (MCP) 从这个 Sidecar 读取状态并写入状态。Sidecar 本身就是一个 MCP 服务；Agent 调用它的工具时，方式与调用其他任何工具完全相同！

该服务专为分布式环境打造，除了提供 Agent 之间通用的状态管理接口外，还原生支持并发、崩溃恢复能力和原子认领。

功能

• 持久化键值存储：支持 CRUD 操作和可选 TTL（生存时间）。
• 工作流生命周期注册表：为分布式多 Agent 工作进程提供集中协调（创建、认领、检查点和恢复），无需带外通信。
• 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 .
   

---

快速开始

运行服务

在多 Agent 分布式环境中，通常会将状态 Sidecar 作为 HTTP SSE 服务运行，以便多个远程 Agent 和客户端同时连接。

HTTP SSE 模式（分布式环境首选）

启动 SSE 服务并监听网络端口：

mcp-state-sidecar-http

默认情况下，服务绑定到 0.0.0.0 并监听端口 8000。MCP 端点位于 http://localhost:8000/mcp。

Stdio 模式（用于子进程／本地 Agent 执行）

通过标准输入／输出启动服务：

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?)：写入或更新可序列化为 JSON 的值，并可设置 TTL。
• 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?)：检索最近的 N 条状态转换记录，包括时间戳和写入者 ID。

第 5 组 — 可观测性

• sidecar_health()：获取存活状态、后端类型、运行时间和数据库指标。
• sidecar_reset()：不可逆地清除所有数据。

---

许可证

本项目基于 MIT License 授权。详情请参阅 LICENSE。