面向变更业务状态的智能体的安全 MCP 模式

一个极简 MCP 服务器，演示了三种让 AI 智能体安全写入真实业务系统的模式：阶段门控、变更前校验 和 结构化审计日志。

这是一个演示，不是产品。该领域（一个玩具级库存 + 采购订单系统）的存在只是为了给这些模式提供具体的应用场景——模式本身才是重点，而且它们与领域无关。

为什么存在

AI 智能体越来越多地被授予对真实系统（订单、库存、CRM 记录、预测）的写入权限。常见的失败模式并不是底层 LLM 在某种抽象意义上不可靠，而是实现往往信任模型会"做正确的事"，背后没有任何结构性护栏。当智能体幻觉出一个状态、被提示注入操纵，或者只是搞错了操作顺序，结果就是对系统的一次静默的错误写入，而人类事后不得不去发现、诊断并修复它。

下面这三种模式并非新颖的研究——它们是针对任何触及生产状态的事务的标准工程纪律，专门应用于智能体工具调用。

Related MCP server: commerce-ops-harness

三种模式

1. 阶段门控。 变更操作（submit_purchase_order）只有在同一会话中先发生了相应的读取/预览操作（draft_purchase_order）时才能成功。这是在代码中强制执行的——一个硬错误，而不是模型可以忽略或被说服放弃的提示指令。错误消息会准确告诉调用者下一步该做什么，这正是让智能体能够自我纠正而不是直接失败的原因。

2. 变更前校验。 每项检查——SKU 是否存在、数量是否合理、是否超过合理的订单阈值——都在写入任何内容之前，针对提议变更的纯表示运行。校验永远不会产生副作用。关键是：所有检查都会运行，无论之前的检查是否失败，因此调用者能一次性看到所有问题，而不是修复一个、重新提交、再遇到下一个。

3. 结构化审计日志。 每次工具调用都会被记录——包括被阻止和被拒绝的调用，而不仅仅是成功的变更。对拒绝的尝试保持沉默的审计轨迹，恰恰缺失了最值得事后审查的事件：智能体尝试了什么而被阻止，以及为什么。

演示

• examples/happy_path.md — 草稿 → 审查 → 提交，附真实捕获的输出

• examples/blocked_paths.md — 安全层实际阻止错误调用的五种方式，同样附真实输出

亲自尝试

pip install -r requirements.txt
pytest tests/ -v          # 17 tests, exercises every pattern above
python server.py          # runs the MCP server over stdio

测试才是真正的证明，而不是上面的文字。如果你想验证本 README 中的某个说法，相应的测试比我对其的描述更可靠。

结构

server.py              # MCP tool definitions — thin, delegates everywhere
safety/
  phases.py             # session state + the phase gate itself
  validation.py         # pure validation functions
  audit.py               # structured logging, including failures
domain/
  inventory.py           # toy in-memory "database"
  purchase_orders.py    # draft/commit data + transformations
tests/                   # one file per pattern, ~17 tests total
examples/                 # real captured walkthroughs

safety/ 和 domain/ 不会以你预期"业务逻辑"与"护栏"拆分时会反转的方向互相导入：领域层完全不知道会话或审批的存在。门控完全位于其外部，在 safety/phases.py 中，它决定 domain.purchase_orders.commit_draft() 是否会被触达。这种分离是刻意的——正是它使得可以在不同时推理库存逻辑的情况下推理安全属性。

这不是什么

不是生产代码。没有真实数据库——库存是一个 Python 字典。没有身份验证。会话状态是内存中的、单进程的。它的存在是为了让安全模式可以被独立检查和测试，而不是一个任何人应该部署的系统。

背景

我在 Eli Lilly 实习期间设计并构建了生产级 MCP 服务器（Go、Kubernetes），包括阶段门控工具访问以及在任何状态变更部署操作之前进行强制校验。这个演示是全新构建的，处于不同领域，没有使用那些代码中的任何部分——它隔离了相同的底层模式，使它们可以在无需访问任何专有内容的情况下被阅读、运行和测试。