GuardRails-MCP

GuardRails-MCP

提示词的更改真的让效果变好了吗？

一个小型评测与提示词回归跟踪器，提供本地 MCP 接口。使用六个带标签的虚构外联案例比较两个提示词，检查失败情况和用量，并保留证据，供人工做出发布决策。

v0.1.1 · 本地原型 · 无部署权限 · 不会自动发送邮件

发表于 2026 年 10 月 16 日：PyPI v0.1.1 · 官方 MCP 注册表记录。注册表示已通过列表收录和所有权检查，并不代表通过安全认证。

为什么要开发它

提示词更改经常在没有证据的情况下发布。有人编辑提示词，看到几个输出看起来没问题，就直接上线。GuardRails-MCP 为团队提供可重复、可审查的记录，展示更改内容和出现的问题，供人工签字批准之前查阅。

适用对象： 构建 Agent 或大模型工作流、需要发布证据的团队，以及必须要求提供这些证据的 AI 保证、风险和治理审核人员。

它不是： 审批机构。它提供证据，由人工做出发布决策。

工作原理

flowchart LR
    A[Baseline prompt] --> C[Six labeled cases]
    B[Candidate prompt] --> C
    C --> D[Deterministic checks]
    D --> E[Run record: prompt hashes, suite hash, evaluator version, outputs]
    E --> F{Phrase match only?}
    F -- yes --> G[Flag: review required]
    F -- no --> H[Pass or hard fail]
    G --> I[Human reviews evidence]
    H --> I
    I --> J[Release decision<br/>outside this tool]

治理概览

由代码强制执行	由人工负责
架构、带标签的决策、空的保留项、非空草稿、引用存在性、来源 ID 成员关系、简短的禁用模式列表	发布决策
实时运行最多限制为 12 次调用（重复运行时为 24 或 36 次），每次调用最多输出 2,000 个 token，超时为 45 秒，不自动重试	判断短语匹配是否构成真实的不安全声明
付费实时运行需要 --acknowledge-cost；MCP 调用方无法启动此类运行	声明覆盖范围和事实依据
仅提供四个本地 MCP 工具：不能任意读取文件、执行 shell 命令、部署或审批	添加留出案例并检查是否过拟合
每次运行都会记录提示词文本及其哈希、测试套件快照及哈希、评测器版本、模型、输出和逐案例检查结果	记录保留与不可篡改性（本地记录可编辑）
提供商故障与提示词回归分开报告	跨日支出限额（没有全局每日上限）

NIST AI RMF 1.0 映射（示例）

此处介绍的是小型评测原型的设计，不代表合规、认证或对整个框架的覆盖。完整表格（包括 OWASP LLM Top 10 视角）见 docs/GOVERNANCE.md。

职能	已实现的证据或控制	已知差距
治理	已记录评测边界；MCP 无法授权部署或消耗 API 额度	没有经过身份验证的角色、指定的组织负责人或策略执行机制
映射	六个带标签的虚构外联案例，以及明确的预期行为	没有利益相关方或影响评估；仅涉及一个工作流
衡量	案例检查、来源快照、延迟和返回的 token 数量、成对回归检查	没有语义真实性验证器、置信区间、全面的对抗性测试集或实时准确率基准
管理	明确的 CLI 成本选择、请求与输出限制、错误可见性	没有每日预算、监控或告警、自动修复或发布门禁

仪表盘预览

使用 6 个虚构案例的预置演示：基线为 6/6，故意引入回归的候选版本为 3/6。这些是手工编写的测试数据，并非测得的模型性能。

已记录运行的详细信息、审核指南和已知缺陷

界面会显示评估器版本、提示词来源、审核指南和已知缺陷。这张截图展示了指南和运行元数据；不会显示针对单个短语匹配的评估。

从免费演示开始

Python 3.11+，在已激活的虚拟环境中：

python -m pip install "guardrails-mcp[dashboard]==0.1.1"
guardrails run --mode demo
guardrails-dashboard

打开 http://127.0.0.1:7861。演示结果由人工编写：基线通过 6/6；故意引入回归的候选版本通过 3/6。这用于测试评分和报告流程，而非模型性能。Gradio 在本地运行；无需 Hugging Face 账户或托管订阅。

你的 .env 可以包含 OPENAI_API_KEY 和 OPENAI_MODEL=gpt-5-mini。演示模式或 MCP 工具无需密钥。切勿提交 .env。

如需进行源代码开发，请克隆此仓库，并使用 python -m pip install -e '.[dev,dashboard]' 安装。

检查内容

案例	预期行为
受支持的报告工作流	草拟内容并附上来源引用
勿联系	阻止操作并且不返回外联内容
缺少工作流证据	暂停处理并且不返回外联内容
联系人角色冲突	暂停处理并且不返回外联内容
不受支持的卖家历史记录	避免使用指定的虚构历史短语
来源文本中的指令	避免使用指定的注入式承诺

检查会验证架构、标注的决策、暂停处理时内容为空、草拟内容非空、引用是否存在、来源 ID 是否属于指定集合，以及一份简短的禁用模式列表。**这些检查不能证明声明已完整覆盖、事实有依据、能够抵御一般性注入，或语义等价。**有一项测试明确展示了这些检查未能发现的虚假声明。

短语匹配需要审核

字面模式匹配并不代表存在不安全声明。新记录会包含 phrase_matches，其中包括字段、模式、匹配文本、偏移量和周边摘录；还会包含 review_required；以及值为 pass、review 或 fail 的 assessment。仅短语匹配导致的失败会标记为 review；其他确定性失败仍标记为 fail，即使也匹配到短语。此功能不会自动批准否定句或引述内容。

原始的 passed、failures 和回归计数仍保持保守，含义不变：每项检查都必须通过。摘要中的 review_only 计数会标识这些原始失败中仅由短语匹配导致的案例。hard_failures 不包括短语匹配，但这并不意味着经过了语义验证。新运行会记录评估器版本 0.1.1。现有记录绝不会被自动重新评分或改写，旧运行记录也不包含新增的审核字段。

请参阅首次实时运行审核，了解观察到的误报及其解读的局限性。

实时比较——明确选择启用

guardrails run --mode live --acknowledge-cost

单次运行最多进行 12 次调用（6 个案例 × 2 个提示词），不进行网络搜索或调用工具，每次调用最多输出 2,000 个 token，请求超时为 45 秒，且不会自动重试。可选的 --repeats 2 或 --repeats 3 会将上限提高到 24 或 36 次调用。没有全局每日支出上限。输入包含虚构证据；模型不会看到预期标签和检查模式。

此处有意提供了一个较弱的候选版本，但不保证能在实时运行中发现回归。编辑 guardrails_mcp/prompts.py，即可比较其他候选版本。记录会保留两版提示词文本及其哈希值、测试套件快照及其哈希值、模型标识符、输出、各案例检查结果、耗时和返回的 token 数。请将耗时视为单次运行的观测值。失败的请求可能产生未报告的用量。提供方故障会单独报告，不计为提示词回归。

结果保存在 .guardrails/runs.sqlite3 中（设置 GUARDRAILS_DATA_DIR，即可在 CLI、MCP 和仪表板之间共享一个绝对目录）。这些是可编辑的本地记录，并非不可变的审计档案。进程意外崩溃时，可能会留下状态为 running 的记录；这些不算已完成的通过结果。

MCP

提供四个本地 stdio 工具：list_cases、run_demo、list_runs、get_run。MCP 调用方不能启动付费的实时运行、读取任意文件、运行 shell 命令、部署更改或批准发布。SDK 限定为经过测试的 v1 API 版本线（mcp<2）；迁移到 v2 属于单独工作。

以下是支持 mcpServers 格式的客户端配置示例。请将路径替换为你自己的路径：

{
  "mcpServers": {
    "guardrails": {
      "command": "/path/to/your/.venv/bin/guardrails-mcp",
      "env": {
        "GUARDRAILS_DATA_DIR": "/path/to/your/.guardrails"
      }
    }
  }
}

此配置中不应包含 API 密钥。协议行为已通过 MCP SDK 客户端进行测试，维护者也通过 OpenAI 桌面应用验证了 list_cases、run_demo 和 get_run，包括 v0.1.1 版本。这是 stdio 服务，不是托管的 ChatGPT 连接器。尚未测试通过注册表列表安装；请参阅验证。

SignalDesk 集成

python scripts/check_signaldesk.py --checkout /path/to/signaldesk

此操作会加载实际的 SignalDesk 检出版本，使用临时数据库创建其应用，使用此评估器评估其 Meridian 固定测试数据，并验证 API 会拒绝批准被抑制的 Brightfield 固定测试数据。它不会打开真实的 SignalDesk 数据库，也不会调用任何模型。这是离线集成测试工具，不是运行时钩子，也不是对 SignalDesk 生产提示词的完整评估。比较测试套件使用的是 SignalDesk 风格的案例，并非其完整的网络研究流程。

Linux 容器

docker compose up --build

仪表板：http://127.0.0.1:7861。命名卷 results 会独立于主机上的 .guardrails 目录保留容器记录。容器以非 root 用户运行，默认不会收到 API 密钥。CLI 工作进程可通过 docker compose run --rm dashboard guardrails run --mode demo 运行。维护者已验证 Docker 演示以及容器重启后的数据持久性。此前一次原因不明的容器退出（代码 137）已记录在验证中；其原因尚未确认。

证据与已知不足

请参阅验证、治理映射、发布说明和注册表列表。

我们不声称提供统计准确度估计、语义漂移评分、模型评判、安全认证、自主持续监控、身份验证、托管服务或发布门禁。测试套件公开且规模较小；提示词作者可能会针对它过度拟合。在将结果用于重大决策前，请添加留出案例并进行人工审核。

路线图

尚未构建。以下是上文所述的待完善之处，列为候选后续步骤：

• 留出用例与可见测试套件分开，以减少过拟合。
• 可选的模型评审检查，明确标注并与确定性检查分开。
• 不可变的审计日志，确保运行记录事后无法编辑。
• 用于检查主张覆盖情况和事实依据的语义检查，超越短语匹配。
• 为实时运行设置每日支出上限。

测试

python -m pytest -q

许可证

根据 MIT License 授权。版权所有 © 2026 Tracy Anne Griffin Manning。