Atlas MCP Gateway

ATLAS治理网关（第2阶段）

由FastMCP、Inngest和Modal提供支持的AI代理安全中间件。

这 ATLAS治理网关 是一个集中式中心，可以拦截AI Agent工具调用，使用通用LLM/SLM（托管在Modal.com上）评估潜在风险，并通过持久的方式管理“循环中的人”（HITL）升级 Inngest 工作流程。

逻辑归因：治理逻辑和数据集设计归因于 高安娜 （加州大学伯克利分校）。此实现严格遵循“approve->auto_approve”确定性流程，针对每个项目v3.0发现的低风险操作。

🚀 主要特点

• 持久治理：用途 Inngest 管理服务器重启后仍能运行的长时间人工审核工作流。
• FastMCP+FastAPI：暴露 模型上下文协议（MCP） 通过强大的通用web服务器提供工具。
• 风险评估：通过以下方式实时检查欧盟人工智能法案标准 atlas-welfare-v1 上 模态.
• 合规：通过暂停高风险行动直至获得人类批准来执行第14条。
• 安全部署：具有安全凭据管理的Docker化环境。

______________________________________________________________________

🛠️ 建筑

sequenceDiagram
    participant Agent as AI Agent (MCP Client)
    participant GW as Governance Gateway (FastAPI)
    participant Modal as Atlas Brain (Modal Evaluation)
    participant Inngest as Inngest Workflow
    participant Human as Sarah (Human-in-the-Loop)

    Agent->>GW: Call Tool (e.g. request_payment_extension)
    GW->>Inngest: Trigger Governance Event
    GW-->>Agent: Returns "PENDING REVIEW"
    
    Inngest->>Modal: Evaluate Risk (EU AI Act)
    Modal-->>Inngest: Risk Score (0-100)

    alt Risk Score >Inngest: Auto-Approve Action
    else Risk Score >= 70
        Inngest->>Inngest: PAUSE & Wait for Human
        Human->>GW: POST /webhook/approval (APPROVED)
        GW->>Inngest: Send Approval Event
        Inngest->>Inngest: Resume & Finalize
    end

该系统由三个主要部分组成：

1. 网关(gateway.py)A. 快速API 作为入口点的应用程序。

- MCP服务器：安装在 /mcp/sse 为代理工具提供服务(check_status, request_extension等等）。 - 先天终点：服务于 /api/inngest 处理工作流触发器和步骤执行。 - 网络钩子：收听 /webhook/approval 用于外部人类批准信号。

1. 工作流程(workflows.py)：定义持久的业务逻辑。

- handle_governance：核心工作流程： 1. 致电Modal评估风险。 1. 如果风险评分\=70，则发生事件。

1. 代理集成:

- 任何符合MCP的代理（Claude Desktop、游标或自定义脚本）都可以连接到网关。

______________________________________________________________________

📦 安装和设置

先决条件

• Docker桌面已安装并正在运行。
• （可选） python 3.10+ 如果不使用Docker在本地运行。

快速入门（Docker）

我们提供 setup.sh 用于自动配置和部署的脚本。

1. 运行安装脚本:

   ./setup.sh

1. 配置:

脚本将提示您：

- 模态函数名称：（默认值： nislam-mics/ATLAS-NIST-Measure) - AI后端：选择OpenAI或本地LLM（Ollama）。 - 万能钥匙：事件密钥和签名密钥（生产所需）。 - 模态凭据：令牌ID和密码。

*注意：脚本创建了一个 .env 文件自动。不要提交此文件。*

1. 用法:

该脚本将构建Docker镜像 atlas-gateway 并在港口运行它 8000.

______________________________________________________________________

🔌 端点

运行后，网关在上公开以下端点 http://localhost:8000:

______________________________________________________________________

🧪 测试治理流程

1.手动验证

检查网关是否正在运行：

curl http://localhost:8000/
# Expected: {"status": "ATLAS Governance Gateway Running", ...}

2.端到端模拟

我们包括一个剧本 test_handshake.py 无需外部代理即可模拟整个流程。

1. 确保网关正在运行（通过Docker或本地）。

1. 运行测试脚本：

   python test_handshake.py

1. 流动:

- 脚本模拟Agent调用 request_payment_extension （高风险）。 - 网关返回 PENDING REVIEW. - Inngest触发工作流运行（检查 Inngest仪表板). - 脚本等待。..然后发送 批准 信号至 /webhook/approval. - 工作流完成。

🤖 AI代理提示指令

为确保您的AI代理正确使用治理网关，请在代理的 系统提示:

### 🛑 治理协议 1. 这种环境由 ATLAS治理网关. 1. 当您调用支付或高风险工具时，网关可能会返回一条以以下开头的消息 PENDING REVIEW (Ref: evt_...). 1. 不要 假设操作失败。 1. 做 通知用户该请求已排队等待人工治理审查，并提供参考ID。 1. 不要 立即重试呼叫；等待系统处理后台工作流。

______________________________________________________________________

🔄 详细治理程序调用

当调用高风险工具时，会发生以下顺序。

1.初始工具请求（代理->网关）

端点: SSE /mcp/sse （流式传输）

• 请求 （JSON-RPC）：

  {
    "method": "tools/call",
    "params": {
      "name": "request_payment_extension",
      "arguments": { "beneficiary_id": "BEN-123", "reason": "Hardship" }
    }
  }

• 网关响应:

  PENDING REVIEW (Ref: evt_48f1fb4b). Action queued subject to governance checks.

2.风险评估（固有->模态）

端点: Modal.com (Inference API)

• 输入：工具名称和参数。

• 评估结果:

  { "risk_score": 85, "classification": "HIGH_RISK", "action": "PAUSE" }

3.案例A：需要HITL（风险>=70）

如果 阿特拉斯大脑 如果确定该操作具有高风险，则会向人工审阅者发送通知(莎拉).

• Sarah的工作流程:

1. Sarah通过Inngest/Webhook收到通知。 1. Sarah评论 reason 和 beneficiary_id. 1. Sarah同意： POST /webhook/approval

  { "decision": "APPROVED", "event_id": "evt_48f1fb4b" }

• 工作流结果：工作流恢复并将工具执行标记为 AUTHORIZED.

4.案例B：自动审批（风险\<70）

如果该行为被视为低风险（例如，标准状态检查或记录良好的低值扩展），系统将跳过人为干预。

• 工作流结果：工作流程立即完成，无需等待外部信号。
• 审计日志：“根据第14条合规性的风险评分\[X\]自动批准。”

5.工作流解决方案（Inngest）

这 atlas/sarah.decision 事件将恢复工作流。最终授权记录在Inngest仪表板中。

______________________________________________________________________

📂 项目结构

• gateway.py：主服务器入口点（FastAPI+FastMCP）。
• workflows.py：固有的工作流定义和客户端初始化。
• setup.sh：自动设置和部署脚本。
• Dockerfile：容器定义（安全，没有秘密）。
• requirements.txt：Python依赖关系。
• test_handshake.py：验证实用程序。

______________________________________________________________________

🔒 安全说明

• 秘密：切勿将API键烘焙到Docker映像中。始终通过 --env-file 或运行时的环境变量。
• 最佳签名：生产部署必须验证 INNGEST_SIGNING_KEY 以防止未经授权的工作流触发。这在 workflows.py.