Prufa

prufa-mcp — 为你的氛围编码应用提供 QA Agent

氛围编码应用上线的速度，快到任何人都来不及审查。 2026 年 6 月，我们审查了 49 个刚发布的 Show HN 项目 — 其中 38 个在上线第一天就存在严重错误：注册功能损坏、控制台静默报错、分析事件从未触发、同意横幅毫无作用。

Prufa 是能在用户发现之前捕获这些问题的 Agent。向它提供一个 URL，它就会审查大家赶进度时容易忽略的问题——流程故障、JS 控制台错误、缺少跟踪、同意违规、安全标头、移动端点击目标、无障碍性——并返回经机器验证的发现，评级从 A 到 F。此仓库是开源 MCP 服务，可将这项审查直接接入你的编码 Agent。

30 秒演示

审查报告包含什么

让你的 Agent 执行 audit https://yourapp.com，prufa_run_audit 就会返回一份 JSON 报告。发现会按评级分组，每项发现都包含严重程度、影响（为何重要）和修复提示。实际输出示例，已精简：

{
  "url": "https://yourapp.com",
  "headline": "2 warnings found",
  "counts": { "critical": 0, "warning": 2, "info": 5 },
  "sections": [
    { "label": "Works",     "grade": "C", "counts": { "warning": 2, "info": 1 } },
    { "label": "Fast",      "grade": "A" },
    { "label": "Found",     "grade": "A" },
    { "label": "Compliant", "grade": "A" }
  ],
  "check_results": [
    {
      "check_id": "ux",
      "findings": [{
        "severity": "warning",
        "title": "2 javascript console error(s) during page load",
        "impact": "Errors at load time often mean broken features visitors never report.",
        "evidence": { "count": 2, "sample": [
          "Access to XMLHttpRequest at 'https://api.fontshare.com/...' blocked by CORS policy",
          "Failed to load resource: net::ERR_FAILED"
        ]}
      }]
    },
    {
      "check_id": "mobile",
      "findings": [{
        "severity": "warning",
        "title": "13 tap target(s) smaller than 24px",
        "impact": "Fingers are not cursors — undersized buttons mean mis-taps on exactly the elements you want pressed.",
        "fix_hint": "Give interactive elements at least 24x24px of hit area (WCAG 2.5.8)."
      }]
    },
    {
      "check_id": "security",
      "findings": [{
        "severity": "info",
        "title": "no Content-Security-Policy header",
        "impact": "Without a CSP, one injected script owns the page — and every third-party tag you load is trusted completely.",
        "fix_hint": "Start with a report-only CSP and tighten from real violation reports."
      }]
    }
  ],
  "report_url": "/r/G82RpzTi_zn-o71_XoMLCprP7uvCQP87"
}

report_url 是同一份报告的可分享 HTML 版本。完整负载还包含 tracking、consent、seo/aeo、a11y、forms 和检测到的用户流程——请参阅下文的 开源功能范围。

安装

此软件包已发布到 PyPI。使用 pipx 全局安装（推荐——使用隔离的 venv，并在 PATH 中提供 prufa-mcp 可执行文件），或使用 pip 安装到项目 venv 中：

# Recommended — global install, isolated venv
pipx install prufa-mcp

# Or, into your project venv
pip install prufa-mcp

# Pin a specific version with ==, e.g. pipx install prufa-mcp==0.1.3

# Verify the binary is on PATH
which prufa-mcp
# Should print something like: /Users/you/.local/bin/prufa-mcp

你还需要一个免费的 Prufa API 密钥。首次审查免费，无需信用卡。

1. 在 prufa.dev 登录（Google OAuth）
2. 在控制面板中创建 API 密钥

接入你的 Agent

MCP 服务以 stdio 子进程的形式运行，由你的 Agent 在首次使用时启动。 注册它最简单的方法是使用 claude mcp add（Claude Code 内置命令——它会将配置正确写入 ~/.claude.json，而 ~/.claude/mcp.json 路径则不会）。

Claude Code（推荐方式）

# Get the absolute path of the binary (use whatever `which prufa-mcp` returned)
PRUFA_BIN=$(which prufa-mcp)

# Add the MCP server. The token stays out of your shell history.
read -s -p "Prufa API token: " PRUFA_TOKEN && echo
claude mcp add \
  --scope user \
  --env "PRUFA_API_TOKEN=$PRUFA_TOKEN" \
  prufa \
  -- "$PRUFA_BIN"

重启 Claude Code（配置会在启动时读取），然后验证：

/mcp

你应该会看到 prufa 显示为已连接，并且 prufa_run_audit 和 prufa_get_report 显示为可用工具。

Cursor / Cline / Continue（手动编辑 .mcp.json）

在项目根目录或 ~/.config/Claude/ 等目录中：

{
  "mcpServers": {
    "prufa": {
      "command": "/Users/you/.local/bin/prufa-mcp",
      "env": {
        "PRUFA_API_TOKEN": "your-prufa-api-key"
      }
    }
  }
}

重启宿主应用。命令路径必须是绝对路径（不能使用 ~ 或 $()）——它们不会在 MCP 配置中展开。

更喜欢使用配置文件而非环境变量？将令牌放入 ~/.config/prufa/mcp.json 即可——参阅 ADVANCED.md。

使用方法

在你的 Agent 中：

> audit https://my-vibe-coded-app.com and show me the criticals
> run prufa on my staging deploy
> fetch the report for the audit I just ran

默认情况下，prufa_run_audit 使用 wait=true，会一直阻塞到审查完成，并直接返回 JSON 报告——对于公开页面，通常需要 25–60 秒。如果设置 wait=false，调用会立即返回排队状态以及一个 share_token，你可以使用 prufa_get_report 轮询获取结果。

你能获得什么——完整的 Agent 功能

prufa-mcp 通过 MCP 暴露完整产品功能（44 个工具）。将你的 Agent 接入 Prufa，它就能审查页面、执行多步骤流程、监控回归、运行混沌测试、执行全自动发现，并管理工作区和账单——无需往返控制面板。免费/匿名工具无需信用卡；如果你尚未订阅套餐，Pro 工具会返回 API 的 402 响应及结账链接（工具仍可见，付费墙由服务端控制）。

审计与报告

工具	功能说明
prufa_run_audit(url, wait=true)	一次性审计公开页面；阻塞等待并返回发现结果 JSON。
prufa_get_report(run_id?, share_token?)	通过 UUID 或 /r/ 路径标识获取报告。
prufa_get_run(run_id)	轮询运行状态。
prufa_list_runs(limit)	工作区中的近期运行记录。
prufa_get_finding(run_id, finding_key?)	已持久化的发现结果，采用机器可读格式。
prufa_list_alerts()	警报记录（最新的排在前面，含抑制记录）。

工作区、用量与转换

工具	功能说明
prufa_setup_workspace(owner_email, name?)	创建免费、无需银行卡的 agent_temp 工作区（7 天试用），并仅返回一次 API 令牌。如果已设置令牌，则返回实际工作区及试用状态。
prufa_get_workspace()	当前工作区，附带内嵌用量信息和 trial 区块。
prufa_get_usage()	用量对象及 trial/upsell 区块——计量操作前请调用。
prufa_workspace_settings(...)	用量 Webhook、自动充值、电子邮件/Slack 开关。
prufa_set_notifications(cells)	9 种事件 × {电子邮件、Slack} 路由矩阵。

账单（返回供用户打开的 URL——绝不会要求提供银行卡）

工具	功能说明
prufa_upgrade_plan(tier)	付费方案（starter/pro/team）的 Stripe 结账 URL。
prufa_buy_credits(credits)	一次性积分包的 Stripe 结账 URL。
prufa_billing_portal()	Stripe 客户门户 URL（银行卡、发票、取消订阅）。

流程（描述一次操作过程 → 可供审核的规范 → 运行）

工具	功能说明
prufa_create_flow(url, test_case, name?)	将纯文本测试用例编译为草稿规范。
prufa_confirm_flow(flow_id, spec?)	批准草稿——只有已确认的流程才会运行。
prufa_run_flow(flow_id, credentials?)	执行已确认的流程。
prufa_set_flow_credentials(flow_id, credentials)	存储 {{VAR}} 值（仅写入）。
prufa_edit_flow(flow_id, spec)	编辑规范（并将其恢复为草稿）。
prufa_get_flow · prufa_list_flows · prufa_delete_flow	读取 · 列出 · 删除。

监控器（按计划监视 URL 或流程）

工具	功能说明
prufa_start_monitor(url, cadence?, flow_id?)	一键创建监控器；仅返回一次部署钩子密钥。
prufa_trigger_monitor(monitor_id)	立即运行（有速率上限）。
prufa_pause_monitor · prufa_resume_monitor · prufa_get_monitor · prufa_list_monitors · prufa_delete_monitor	生命周期管理。
prufa_rotate_monitor_webhook(monitor_id)	轮换部署钩子密钥。
prufa_list_monitor_deliveries(monitor_id)	部署钩子投递日志和 CI 代码片段。

Gremlin（混沌 QA）

工具	功能说明
prufa_run_gremlin(url, persona?, direction?, credentials?)	模拟难以应对的用户；检测器会验证故障情况。除非获得授权，否则变更仅试运行；绝不会执行支付。
prufa_rerun_gremlin(run_id)	使用相同意图和已保存的登录信息重新运行过往的 gremlin。
prufa_authorize_domain(host, allow_mutation?)	允许在你拥有的主机上执行真实（非支付）写入操作。
prufa_list_gremlin_domains()	列出变更授权。
prufa_gremlin_saved_logins()	重用先前的登录信息（仅限所属工作区——敏感操作）。
prufa_promote_gremlin_path(share_token, path_index)	将复现出的 Bug 路径转换为流程草稿。

发现（全自动——抓取、推断流程并生成草稿）

工具	功能说明
prufa_register_discovery_domain(domain)	注册域名并获取要发布的 DNS TXT 记录。
prufa_verify_discovery_domain(domain_id)	验证 DNS 证明。
prufa_list_discovery_domains · prufa_revoke_discovery_domain	管理已授权的域名。
prufa_run_discovery(url)	抓取已验证的网站并生成其有意义流程的草稿。
prufa_get_discovery(discovery_id)	运行状态及发现的流程。

另有 prufa_health_check()（探测服务/API）。

免费试用，以及何时升级

prufa_setup_workspace 会创建一个免费的 agent_temp 工作区：无需信用卡，可试用 7 天，并附带一定额度的积分。试用期间可以使用监控、发现和完整长度的 gremlin 运行；试用结束后则需要付费套餐。

MCP 会向你的 Agent 清楚地说明这些信息：prufa_get_usage、prufa_setup_workspace 和每个按用量计费的结果都会包含一个 trial 区块（剩余天数和积分），当积分不足或试用即将结束时，还会包含一个 upsell 区块，其中有 Agent 可以转达给用户的 message_for_human，以及需要调用的具体工具（prufa_upgrade_plan / prufa_buy_credits）。如果在未订阅套餐的情况下调用 Pro 工具，402 响应会附带 checkout_url 返回——不会静默失败，也不会产生意外费用。

示例

examples/ 中有三个可运行的脚本：

• examples/nextjs-app/ — 审核已部署的 Next.js 应用
• examples/vite-spa/ — 审核 Vite SPA（重点检查客户端路由）
• examples/stripe-checkout/ — 审核 Stripe 结账页面（验证支付流程）

每个示例都是可直接复制粘贴的演示：

export PRUFA_API_TOKEN=...
python examples/nextjs-app/audit.py https://your-nextjs-app.com

GitHub Action

当 Prufa 发现严重回归时，让 PR 检查失败：

# .github/workflows/prufa-scan.yml
name: Prufa scan
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install prufa-mcp
      - name: Run audit
        env:
          PRUFA_API_TOKEN: ${{ secrets.PRUFA_API_TOKEN }}
        run: |
          python -c "
          import asyncio, sys
          from prufa_mcp.audit import run_audit
          report = asyncio.run(run_audit(url='${{ secrets.STAGING_URL }}', wait=True))
          print(report.get('headline', 'audit complete'))
          criticals = report.get('counts', {}).get('critical', 0)
          if criticals:
              print(f'::error::Prufa found {criticals} critical finding(s)', file=sys.stderr)
              sys.exit(1)
          "

完整模板请参阅 examples/prufa-scan.yml。

许可证

Apache-2.0。请参阅 LICENSE。欢迎贡献 — 请参阅 CONTRIBUTING.md。