Skip to main content
Glama
deenesjakoruzh
marvinjbb

agent-mcp-workflow-platform

by marvinjbb
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Agent 与 MCP 工作流平台

一个需审批的故障处理工作流，通过只读 MCP 工具收集证据，执行一个精确的幂等操作，验证结果，并保留持久的审计追踪。

概述

Agent 工作流带来的风险超出了普通的请求/响应 API：外部工具的输出可能带有恶意，重试可能导致重复的副作用，审批可能过期，而成功的工具响应可能并不反映已持久化的状态。

本项目围绕这些故障模式实现了一个有界的事件响应工作流。一个确定性规划器通过模型上下文协议 (MCP) 发现并调用已批准的只读工具，提出一个工单，等待人工审批，将该审批绑定到一个 SHA-256 操作摘要，执行一次幂等的数据库写入，并验证存储的结果。它不使用 LLM；重点在于可靠的编排和控制边界。

Related MCP server: mcp-policy-gateway

主要特性

  • 通过 JSON-RPC stdio 进行 MCP 工具发现和调用

  • 独立的只读 MCP 服务器，提供 service-status 和 runbook-search 工具

  • 独立于 MCP 工具发现的应用级允许列表

  • 显式的工作流状态机，带有步骤预算强制执行

  • 在产生副作用的写入之前进行人工批准或拒绝

  • SHA-256 摘要将审批绑定到完整的提议操作

  • 稳定的幂等键，防止重试期间重复创建工单

  • 写入后独立验证 SQLite

  • 持久的运行、审批、工单和有序的审计事件

  • 使用 Bearer 认证的 FastAPI 端点、CLI 工作流、CI 和确定性测试

架构

flowchart LR
    C[API Client] --> A[FastAPI]
    A --> W[Workflow Service]
    W --> P[Deterministic Planner]
    W --> M[MCP Stdio Client]
    M --> S[Read-Only MCP Server]
    W --> D[(SQLite Store)]
    H[Human Approver] --> A
    A --> W
    W --> T[Idempotent Ticket Write]
    T --> D
    D --> V[Verification]
    V --> W

MCP 对等体可以提供观察结果，但没有写入权限。工单创建仍在应用程序内部进行，并且只有在提交的审批哈希与当前提议匹配时才能发生。

工作流状态机

created -> gathering -> awaiting_approval -> executing -> verifying -> completed
                |              |               |            |
                v              v               v            v
              failed        cancelled        failed       failed
                                                 |
                                                 `-- resume with matching approval

API

方法

端点

目的

GET

/health

报告服务存活状态

GET

/v1/tools

发现 MCP 服务器的只读工具

POST

/v1/runs

收集证据并创建待审批的提议

GET

/v1/runs/{run_id}

读取持久化的工作流状态

GET

/v1/runs/{run_id}/events

读取有序的审计追踪

POST

/v1/runs/{run_id}/approval

批准或拒绝确切的操作用户哈希

POST

/v1/runs/{run_id}/resume

使用现有的匹配审批重试失败运行

所有 /v1 端点都需要 Authorization: Bearer <AGENT_API_TOKEN>。

技术栈

技术

目的

Python 3.12

类型化工作流、MCP 客户端/服务器和持久化逻辑

FastAPI / Uvicorn

认证的工作流 API 和 OpenAPI 文档

Pydantic / pydantic-settings

工作流契约和环境配置

SQLite

持久的运行、审批、工单和审计事件

JSON-RPC / MCP

通过 stdio 进行工具发现和只读工具调用

Pytest / HTTPX

工作流、MCP、持久化和 API 测试

Ruff / mypy

代码检查和静态类型检查

GitHub Actions

自动化的代码检查、类型检查和测试流水线

工作原理

  1. 客户端为某个服务和报告的症状创建一个运行。

  2. 工作流发现 MCP 工具，与其自身的只读允许列表取交集，并收集有界的观察结果。

  3. 工具输出作为不可信证据存储，且永远不会被解释为工作流指令。

  4. 应用程序创建一个提议的工单操作、一个稳定的幂等键和一个规范的 SHA-256 操作哈希。

  5. 工作流持久化 awaiting_approval 状态并返回，不执行写入。

  6. 人工提交对确切哈希的批准或拒绝。已更改或过期的提议将被拒绝并返回 HTTP 409。

  7. 已批准的操作幂等地创建工单，从 SQLite 读回，并在验证后标记运行为完成。

  8. 如果批准后执行失败，/resume 可以安全地重试，因为幂等键保持不变。

工程决策

  • 发现不等于授权。 工作流将 MCP 结果与硬编码的只读允许列表取交集，因此对等体无法通过宣传另一个工具来获得权限。

  • 外部观察结果只是数据。 工具输出有长度限制，在审计事件中标记为不可信，并且仅用作工单证据。

  • 审批是内容寻址的。 规范 JSON 和 SHA-256 将审批绑定到提议操作的每个字段，并防止负载替换。

  • 写入是幂等且可验证的。 唯一的幂等键处理重试歧义，而单独的读取确认持久化的记录。

  • 状态持久地跨越副作用边界。 在审批、执行、验证、失败和完成之前和之后，都会写入状态和审计事件。

  • 规划器是故意确定性的。 这保持了安全模型的可检查性，同时为未来评估模型的使用保留了可替换的规划器边界。

项目结构

agent-mcp-workflow-platform/
|-- src/agent_platform/
|   |-- workflow.py          # State machine, planner, approval, execution, verification
|   |-- tools.py             # MCP stdio client and deterministic test client
|   |-- mcp_server.py        # Local read-only MCP server
|   |-- database.py          # SQLite schema and durable workflow store
|   |-- models.py            # Typed run, action, approval, event, and tool contracts
|   |-- api.py               # Authenticated FastAPI endpoints
|   |-- settings.py          # Environment-based configuration
|   `-- cli.py               # Database, MCP discovery, demo, and server commands
|-- tests/                   # Workflow safety, retry, MCP, and API tests
|-- docs/                    # Architecture and API reference
|-- .github/workflows/ci.yml
|-- SECURITY.md
|-- CONTRIBUTING.md
`-- pyproject.toml

开始使用

前提条件：Python 3.12+。

cd agent-mcp-workflow-platform
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
agent-workflow init-db
agent-workflow mcp-tools
agent-workflow serve

API 运行在 http://127.0.0.1:8000；交互式文档位于 /docs。

使用示例

创建一个运行：

curl -X POST http://127.0.0.1:8000/v1/runs \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"service":"payments-api","symptom":"Elevated 5xx responses"}'

响应包含运行 ID、完整的提议操作和 action_hash。审查后，批准该确切操作：

curl -X POST http://127.0.0.1:8000/v1/runs/RUN_ID/approval \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"approved":true,"action_hash":"HASH_FROM_PROPOSAL"}'

检查可重放的事件历史：

curl http://127.0.0.1:8000/v1/runs/RUN_ID/events \
  -H "Authorization: Bearer change-me"

测试

pytest
ruff check .
mypy

该套件验证了认证、MCP 发现和调用、审批不匹配拒绝、拒绝行为、不可信输出处理、输出和步骤限制、重复执行预防、幂等工单创建、故障恢复、独立验证和有序审计历史。

本项目展示的内容

  • 持久的 Agent 工作流和状态机设计

  • MCP 集成和 JSON-RPC 进程边界

  • 对产生副作用的操作进行人工在环审批控制

  • 幂等性、故障恢复和后置条件验证

  • 对不可信工具输出的安全处理

  • 类型化 API 和 SQLite 持久化设计

  • 自动化测试和基于 CI 的质量保证

路线图

  • 将开发用的 Bearer 令牌替换为 OIDC 认证和基于角色的授权

  • 通过幂等适配器将写入边界连接到真实的工单系统

  • 将执行迁移到具有并发控制的持久化后台工作者

  • 添加指标、追踪、结构化操作日志和告警

  • 在授予 LLM 有界的规划职责之前，对照确定性基线评估 LLM 规划器

更多详情请参见 架构、API 参考 和 安全策略。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Aegis

    nithyajangam
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables governing tenant-aware MCP tools with policy enforcement, scoped access, human approval workflows, and tamper-evident audit logging.
    -

  • mcp-policy-gateway

    jcorrego
    A
    license
    A
    quality
    C
    maintenance
    Enables policy-governed MCP interactions with deterministic authorization, tenant isolation, minimized PII exposure, and human approval gates for sensitive mutations, while producing structured audit events.
    3
    MIT

  • agentops-incident-commander

    SahanaReddy5
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides MCP-compatible safe read tools for incident investigation, enabling evidence collection and operational data access while keeping risky actions under human approval.
    MIT