Mimiq

Mimiq MCP 服务

你的 Agent 构建了它。在发布前，让 AI Agent 像你的用户一样使用它。

让 Mimiq 连接预览或预发布 URL，并用简单的话描述一项任务，例如注册或进入结账页面。不需要测试脚本。每个 Agent 都会像你的用户一样操作：在自己的真实浏览器中打开应用，点击、输入并填写表单（还配有自己的收件箱，用于接收验证码）。报告会显示哪些地方出了问题、哪些操作毫无反应、每个 Agent 卡在哪里或为何放弃，并附上对应步骤和截图。修复他们遇到的问题，然后在新构建版本上重新运行。

工具

工具	功能
mimiq.test_flow	AI Agent 在真实浏览器中体验预览、预发布或线上 URL 的流程，并逐步报告哪些地方出了问题、哪些操作毫无反应以及卡在哪里，同时附上截图。每个 Agent 消耗 5 点额度。
mimiq.show_report	再次显示已保存的报告。只读取你的账户，不消耗额度。

直接向你的 Agent 提出要求，或让它测试刚刚构建的内容：

“让三个 Agent 在这个预览环境中注册，并告诉我它们卡在哪里”

“在我合并之前，检查一下预览环境中的新结账流程”

“在预发布环境中运行 Mimiq，让家长选购学步鞋，然后修复它们遇到的问题”

“在修复后的构建版本上再运行一次”

Agent 能发现的问题和能力限制

• 屏幕上显示的错误、没有反应的按钮和链接、拒绝有效输入的表单、死路，以及 Agent 因措辞而等待、放弃或走错方向的步骤。
• 浏览器记录的内容：JavaScript 错误、失败或返回 4xx/5xx 的请求，以及耗时超过 3 秒的请求，并标明这些情况发生在哪一步。
• 每个问题都会列出遇到该问题的 Agent、对应步骤、截图和建议修复方案，并按遇到该问题的 Agent 数量排序。
• 这些 Agent 是模拟用户。它们能快速发现问题，但无法预测真实用户的转化人数。
• 它们无法使用真实银行卡付款，CAPTCHA 或机器人防护也可能阻止它们。请使用未启用机器人防护的预览或预发布 URL。

每个拉取请求都运行

Mimiq preview check GitHub Action 会在每个 Vercel、Netlify 或 Cloudflare Pages 预览环境中运行 Agent，并在拉取请求中保留一条评论，说明它们遇到的问题。其他 CI 也可以调用相同的端点：它使用纯 JSON-RPC over HTTP。

curl -s https://mcp.mimiqai.com/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $MIMIQ_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mimiq.test_flow","arguments":{"url":"'"$PREVIEW_URL"'","goal":"Sign up and start using it","count":3}}}'

设置

Claude Code

claude mcp add --transport http mimiq https://mcp.mimiqai.com/mcp --header "Authorization: Bearer $MIMIQ_API_KEY"

或者在项目根目录的 .mcp.json 中配置（Claude Code 会从你的环境中读取 ${MIMIQ_API_KEY}，因此密钥不会留在代码库中）：

{
  "mcpServers": {
    "mimiq": {
      "type": "http",
      "url": "https://mcp.mimiqai.com/mcp",
      "headers": { "Authorization": "Bearer ${MIMIQ_API_KEY}" }
    }
  }
}

不添加请求头即可免费试用。

将其纳入每次更改

将以下几行添加到项目的 CLAUDE.md 或 AGENTS.md 中，这样你的 Agent 就会在完成客户可见的更改前进行检查：

## Before calling a user-facing change done
After changing anything a user goes through (signup, onboarding, checkout,
settings, a new feature), run mimiq.test_flow on the preview URL with the task
a user would try. Fix what the agents hit, then run it again. Ask me before
using more than 25 credits.

Codex

在 ~/.codex/config.toml 中（或项目中的 .codex/config.toml）：

[mcp_servers.mimiq]
url = "https://mcp.mimiqai.com/mcp"
bearer_token_env_var = "MIMIQ_API_KEY"

Cursor

在 ~/.cursor/mcp.json 或 .cursor/mcp.json 中（请勿提交包含密钥的文件）：

{
  "mcpServers": {
    "mimiq": {
      "url": "https://mcp.mimiqai.com/mcp",
      "headers": { "Authorization": "Bearer mq_sk_..." }
    }
  }
}

VS Code（GitHub Copilot）

在 .vscode/mcp.json 中配置；VS Code 会提示你输入一次密钥并将其保存：

{
  "inputs": [{ "type": "promptString", "id": "mimiq-key", "description": "Mimiq API key", "password": true }],
  "servers": {
    "mimiq": {
      "type": "http",
      "url": "https://mcp.mimiqai.com/mcp",
      "headers": { "Authorization": "Bearer ${input:mimiq-key}" }
    }
  }
}

Windsurf

在 ~/.codeium/windsurf/mcp_config.json 中配置：

{
  "mcpServers": {
    "mimiq": {
      "serverUrl": "https://mcp.mimiqai.com/mcp",
      "headers": { "Authorization": "Bearer mq_sk_..." }
    }
  }
}

Claude Desktop

通过 mcp-remote，在 Claude Desktop 配置中设置：

{
  "mcpServers": {
    "mimiq": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.mimiqai.com/mcp", "--header", "Authorization:${MIMIQ_AUTH}"],
      "env": { "MIMIQ_AUTH": "Bearer mq_sk_..." }
    }
  }
}

密钥与免费试用

• 没有密钥时，每个 Agent 都可以免费测试一次：在每日免费额度有效期间，可运行一个最多包含 3 个 Agent 的流程。规模更大的测试需要密钥，工具会在消耗额度前告知。
• 获取密钥： 在 www.mimiqai.com/sign-up 免费注册账号（附赠 50 个额度）。打开 Settings，找到“Use Mimiq from your coding agent”，然后选择“Create a key”。密钥以 mq_sk_ 开头，且只会显示一次。
• 发送密钥： 每次请求都要通过 Authorization: Bearer mq_sk_... 发送（X-API-Key: mq_sk_... 也可以）。上面的设置代码片段已经这样处理。
• 额度： 流程中的每个 Agent 消耗 5 个额度。在 www.mimiqai.com/app/usage 购买更多额度：一次性 Starter 套餐包含 120 个额度，售价 $9；也可以选择每月 $19 起的套餐。

已登录页面和受保护的预览

对于受 Vercel Deployment Protection 保护的预览（vercel_bypass）、浏览器密码提示（basic_auth）或需要登录的页面（login，使用测试账号），可向 test_flow 传入 access。Agent 会输入占位值；真实值仅在浏览器中填入，与测试隔离，并在运行结束后删除，且绝不会出现在结果或报告中。使用访问凭据需要付费额度。

报告链接

使用密钥后，每次运行都会保存到你的账号，结果末尾会附上 Mimiq 应用中的报告链接（/app/t/...）。请将链接放入摘要中，这样相关人员就能查看完整报告、Agent 的操作步骤和截图。在应用中分享之前，报告均为私密状态。

不使用密钥时，运行结果仅对执行该操作的 Agent 保持私密，无法在应用中打开；结果会改为说明如何获取密钥。

运行结果

• 每个 Agent 的 journey_steps：记录其每一步执行的操作、所在位置和所说内容。
• 每个 Agent 停止的位置和原因：已完成、部分完成或放弃。
• Agent 遇到的问题，按遇到该问题的 Agent 数量排序，并附上相关步骤。
• browser_caught：浏览器在你的网站上记录的情况，按遇到各类情况的 Agent 数量分组并排序：JavaScript 错误、失败或返回 4xx 或 5xx 的请求（包括 Supabase 或 Firebase 等托管后端），以及耗时超过 3 秒的请求。摘要卡片中也会列出这些内容。
• counts、纯文本 summary_card，以及 report_url（使用密钥时）。

Agent 的用户画像

默认情况下，Mimiq 会根据页面为应用目标用户构建 Agent。传入通俗易懂的 audience，即可指定用户群体（例如“自由职业设计师”“为孩子购买校鞋的家长”）。除非招募到的 Agent 不符合指定受众（超过 1/5 不符合），否则运行会立即开始；若不符合，结果会返回 status: "audience_review"：先显示警告，再通过 review_id、confirm_audience: true 和 audience_fit_acknowledged: true 继续，或通过 review_id 和 audience_correction 重新招募。在应用中，你也可以根据自己的客户构建 Agent（使用 CSV；上传前会移除姓名、电子邮件地址和电话号码）。

本地服务

Mimiq 需要公开 URL。对于本地开发服务器，可使用 cloudflared 创建临时隧道（免费且无需账号），然后传入其 URL。隧道运行期间，页面处于公开状态，因此 Agent 应在打开隧道前告知你：

cloudflared tunnel --url http://localhost:3000 > /tmp/mimiq_tunnel.log 2>&1 &
sleep 5; grep -o 'https://[^ |]*trycloudflare.com' /tmp/mimiq_tunnel.log

错误

每个错误都包含一个 code、一条纯文本 message 和一个 request_id。额度和密钥错误还包含 how_to_get_a_key（步骤、标头和 .mcp.json）。

Code	含义	处理方法
INSUFFICIENT_CREDITS	reason 会说明具体原因：free_try_used、free_flow_too_big、free_flows_used_today、network_monthly_limit 或 out_of_credits（使用密钥时）。	获取密钥、减少 Agent 数量，或购买更多额度。
UNAUTHORIZED	密钥未被接受（invalid_key）。	检查密钥是否以 mq_sk_ 开头，以及是否仍列在 Settings 中。
INVALID_INPUT	缺少字段，或 Mimiq 无法访问该 URL（localhost、私有地址）。	修正输入；如果是 localhost，请使用隧道。
SIM_FAILED	运行失败，例如页面未能加载。失败的运行会退还额度。	检查 URL 是否能在普通浏览器中加载，然后再次调用。
SIM_TIMEOUT	运行时间超过了 timeout_seconds。运行仍会在 Mimiq 端继续。	使用密钥时，稍后打开报告链接；或者使用更长的超时时间再次调用。
RATE_LIMITED	一分钟内来自同一网络的调用次数过多。	等待一分钟。

自托管

使用你自己的 Mimiq API：

cd mcp-hosted
MIMIQ_API_URL=http://127.0.0.1:8000/api node src/server.js

将你的 Agent 指向 http://127.0.0.1:8787/mcp。

变量	默认值	设置内容
MIMIQ_API_URL	http://127.0.0.1:8000/api	Mimiq API
MIMIQ_APP_URL	https://mimiqai.com	报告链接的指向地址
MIMIQ_MCP_PUBLIC_URL	https://mcp.mimiqai.com/mcp	设置帮助中显示的 URL
PORT / HOST	8787 / 127.0.0.1	此服务的监听地址。在代理后运行时，保持 127.0.0.1，并让代理设置 X-Real-IP（用于识别调用方网络，以便实施速率限制和免费试用限制）。
RATE_MAX_CALLS	10	每个网络每分钟的工具调用次数
EMIC_API_KEY	none	启用 submit_agent_feedback（未设置时隐藏）
POSTHOG_API_KEY	none	使用情况事件

开发

ChatGPT 账户关联和内嵌报告

该插件使用基于 S256 PKCE 的 OAuth 账户关联。现有的 API 密钥客户端和无密钥客户端仍可继续使用。经验证的 ChatGPT 调用必须关联 OAuth 账户才能进行测试；额度和所有权仍由后端负责。测试完成后，使用 mimiq.show_report 在 MCP Apps 宿主中呈现已保存的报告。它会读取账户的报告，不会消耗额度。

OAuth 发现端点位于 /.well-known/oauth-protected-resource 和 /.well-known/oauth-authorization-server。授权、注册、令牌和撤销路由位于 /oauth/ 下。配置了 OPENAI_APPS_CHALLENGE 后，其内容会原样提供在 /.well-known/openai-apps-challenge；未配置时，该路由会返回 404。

启用 ChatGPT 集成前，请参阅 deploy/plugin.env.example 和 deploy/openai-mtls.nginx.conf.example。要可靠地识别 ChatGPT，必须在现有代理处验证证书，并让 Node 绑定到 loopback。仅凭客户端名称和 User-Agent 提示无法确认身份。报告 HTML 已纳入代码库且自包含，因此提供该文件不会增加运行时依赖。

OAuth HTTP 测试需要安装了 fastapi 和 uvicorn 的 Python；如果默认 Python 中未安装这些依赖，请设置 MIMIQ_TEST_PYTHON。Widget DOM 测试会在根目录执行 npm ci 后，使用父级 Web 应用的开发依赖 jsdom。如果缺少这些开发依赖，相应测试会明确跳过。在完整的 Mimiq 检出目录中，npm run widget:build 会重新构建嵌入式字体和脚本，npm run widget:check 会检测差异，npm run widget:verify -- --screenshots 会运行浏览器检查并截取三个示例报告。浏览器截图需要根目录的开发依赖和可正常使用的本地 Playwright 浏览器。

命令

npm test                        # unit tests, the tools against a mocked API
npm run vendor                  # rebuild src/vendor/app-logic.js from the app (src/mimiq/lib)
MIMIQ_API_URL=http://127.0.0.1:8000/api MIMIQ_E2E_API_KEY=mq_sk_... npm run e2e   # compare_copy end to end, 3 people
./deploy.sh --dry               # what a deploy would sync (see deploy.sh)

src/vendor/app-logic.js 根据应用的 compare.ts、model.ts、readout.ts 和 names.ts 生成；当两者不再一致时，测试会失败。

许可证

MIT