pipeflow-mcp

PipeFlow MCP Server —— AI Agent 任务的被动状态跟踪容器。

注意：本项目是实验 / demo 性质的学习作品，作者发布它用于代码评审与学习，真实场景下的实用价值尚未确证，不保证有用。

这是什么

pipeflow-mcp 是一个基于 Model Context Protocol (stdio JSON-RPC) 的 MCP 服务器。它把 agent 的工作流执行过程记录到一个由 FSM 驱动的 pipeline 账本里，提供：

• FSM 状态机：5 状态 × 5 action，pending / running / succeeded / failed / skipped，由 transitions 库实现

• 审计完整性：reset 保留所有 annotations + reports，delete 是 soft-delete，events 表 append-only

• 重试与时间预算：retry 计数器 lifetime，stage-level time_budget_seconds 派生 time_status

• 16 个 pipeflow_* 工具：声明 / 状态推进 / 读取 / 注解 / 报告 / 仪表盘 / 健康检查，其中 pipeflow_stage_advance 是唯一的状态变更入口

• Cursor 分页：4 个 list 工具共享 base64-urlsafe(last_id + filter_fingerprint) 不透明 cursor，filter 改变即 cursor 失效

• 静态 HTML 仪表盘：导出产物含 7 个 section —— Pipeline Overview / Decision Chain / Reflection Trace / Iteration Compare / Metric Analysis / Deliverables / Events Stream，Jinja2 autoescape 防 XSS，导出路径白名单

• 错误脱敏：客户端消息只含 pipeline_id / stage_id / 错误类名，SQL 片段 / 文件路径 / 堆栈仅走 stderr 结构化日志

• Schema 校验：5 个 ReportType —— decision / reflection / metric_report / deliverable / iteration_summary，对应 JSON Schema，启动时注册

• 类型化响应：8 个 Pydantic v2 view model，FastMCP outputSchema 自动填充字段契约，extra='forbid' 锁定公开 JSON 契约

完整 API 文档见 docs/api.md。

Related MCP server: Subconductor

状态

安装与运行

MCP 客户端

从 GitHub 直接安装：

uvx --from git+https://github.com/AstralVoidZ/pipeflow-mcp pipeflow-mcp

或者从本地源码 checkout 启动：

git clone https://github.com/AstralVoidZ/pipeflow-mcp.git
cd pipeflow-mcp
uv venv --python 3.14 .venv
uv pip install -e ".[dev]"
uvx --from . pipeflow-mcp    # dev 模式

Server 通过 stdio 监听 JSON-RPC，stdout 保留给 JSON-RPC，所有日志走 stderr。

客户端配置示例

Claude Code，~/.claude/mcp_servers.json：

{
  "mcpServers": {
    "pipeflow": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/AstralVoidZ/pipeflow-mcp", "pipeflow-mcp"],
      "env": {
        "PIPEFLOW_DB_PATH": "~/.pipeflow_mcp/state.db",
        "PIPEFLOW_LOG_LEVEL": "INFO"
      }
    }
  }
}

opencode，项目级 .opencode/config.json：

{
  "mcp": {
    "pipeflow": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/AstralVoidZ/pipeflow-mcp", "pipeflow-mcp"],
      "environment": {
        "PIPEFLOW_DB_PATH": "~/.pipeflow_mcp/state.db",
        "PIPEFLOW_LOG_LEVEL": "INFO"
      },
      "enabled": true
    }
  }
}

工具矩阵

完整参数 / 返回 schema / 错误清单见 docs/api.md。

配置

pipeflow-mcp 不接受任何 CLI 参数，无 --db-path 之类的 flag。所有配置通过环境变量传入，客户端在 MCP server 配置的 env 块里设置即可。误传 --db-path 只会在 cwd 留下一个同名空文件。

所有日志写入 stderr，stdout 保留给 JSON-RPC 通信。

架构

5 层严格单向依赖：

protocol (MCP tools / server.py)
   → view layer (Pydantic v2 view models, extra='forbid')
      → persistence orchestration (orchestration/ — advance, create, append, reset, delete, snapshot, annotate, reports, queries, ...)
         → { FSM layer (fsm/machine.py) , Spec layer (yaml_parser, report_registry, result_validator) }
            → data contract layer (models/*.py — dataclasses only)
               → error layer (errors/*.py)

侧模块，storage/ (DB + DAO + migrations) · pagination/ (cursor codec) · export/ (Jinja2 + 8 模板) · tools/ (16 薄封装) · config.py (env + logging)。

不变量

1. stdout = JSON-RPC，stderr = logs，任何 stdout 写入会破坏 MCP 客户端

2. DAO 是 SQL 边界，orchestration / fsm / spec / tools / pagination / export 永不 import pipeflow_mcp.storage.dao

3. 单写者假设，SQLite WAL 在单 host + 单 writer 下安全，多进程并发写超出设计范围

4. user_version 降级拒绝，永不静默 forward-migrate，启动时抛 RuntimeError 是正确行为

5. Annotation 列表不含 data，list 返回 AnnotationSummary，data 只能通过 get 取得

6. reset append-only，保留 annotations + reports + 历史 events，只追加 type='reset' event

7. View 单向投影，tools → views → models 是唯一允许方向，反向 import 被 test_views_have_no_dao_imports 强制禁止

开发

本地验证

ruff check src/pipeflow_mcp/ tests/
mypy src/pipeflow_mcp/
pytest tests/ -v --cov=pipeflow_mcp --cov-fail-under=85

打包

本地构建 wheel + sdist 到 release/ 目录，.gitignore 排除。

./scripts/build.sh            # clean + lint + type + test + build
./scripts/build.sh --wheel    # 只构建 wheel
./scripts/build.sh --check    # 跳过 clean，直接基于当前 venv 构建

产物 release/pipeflow_mcp-<version>-*.whl 和 release/pipeflow_mcp-<version>.tar.gz，用于个人 GitHub Release 上传。

许可证

MIT，见 LICENSE。