Menso

Menso

AI 用户会在你的线上网站执行真实任务，并通过每一步的回放展示他们在哪些地方遇到阻碍。

本仓库包含 Menso 开发者集成的公开部分：

• Menso 托管的 MCP 服务设置，适用于 Claude Code（作为插件）、Codex、Cursor、Windsurf，以及任何支持 Streamable HTTP 和自定义 Authorization 标头的 MCP 客户端；
• menso，用于终端和 CI 的命令行（bin/、src/）；
• 官方 MCP 注册表的条目（mcp-registry/server.json）。

测试运行器、AI 用户和评分均在 Menso 的服务器上运行，不属于本仓库。MCP 文档：menso.io/docs/mcp。

1. 创建 API 密钥

登录 Menso，打开 Settings，然后选择 Create API key。请立即复制密钥：Menso 只会显示一次。请将它保存在环境变量或 CI 密钥中，切勿放入仓库。

2. 连接编辑器（MCP）

服务托管在 https://api.menso.io/mcp（Streamable HTTP）。无需安装任何内容。

Claude Code（插件）

本仓库是一个 Claude Code 插件。一步即可安装；Claude Code 会提示你输入 Menso API 密钥，并将其保存在安全存储中：

/plugin install menso --marketplace menso-io/menso

在 shell 中执行的等效命令是 claude plugin marketplace add menso-io/menso，然后执行 claude plugin install menso@menso。

Claude Code（不使用插件）

claude mcp add --transport http menso https://api.menso.io/mcp \
  --header "Authorization: Bearer YOUR_MENSO_API_KEY"

若要与团队共享，请将以下内容放入项目根目录下的 .mcp.json；每个人都要在自己的 shell 中设置 MENSO_API_KEY：

{
  "mcpServers": {
    "menso": {
      "type": "http",
      "url": "https://api.menso.io/mcp",
      "headers": { "Authorization": "Bearer ${MENSO_API_KEY}" }
    }
  }
}

Cursor（~/.cursor/mcp.json 或 .cursor/mcp.json）

{
  "mcpServers": {
    "menso": {
      "url": "https://api.menso.io/mcp",
      "headers": { "Authorization": "Bearer ${env:MENSO_API_KEY}" }
    }
  }
}

Windsurf（~/.codeium/windsurf/mcp_config.json）

{
  "mcpServers": {
    "menso": {
      "serverUrl": "https://api.menso.io/mcp",
      "headers": { "Authorization": "Bearer ${env:MENSO_API_KEY}" }
    }
  }
}

Codex（~/.codex/config.toml；Codex 会从你 shell 中的 MENSO_API_KEY 读取密钥）

[mcp_servers.menso]
url = "https://api.menso.io/mcp"
bearer_token_env_var = "MENSO_API_KEY"

Cursor 插件

本仓库也是一个 Cursor 插件：.cursor-plugin/plugin.json 和 mcp.json 会添加 Menso MCP 服务。安装后，请在 Cursor 提示你配置插件时，将 MENSO_API_KEY 设为你的 Menso API 密钥（Plugins → Configure）。

然后用日常语言请求测试：“在 https://staging.example.com 上运行 Menso 注册测试，并告诉我 AI 用户在哪里遇到了阻碍。”

工具

工具	功能
run_test(url, template, tier)	在公开 URL 上启动测试，并返回一个 test_id。模板：purchase（读取首页和定价页面，然后决定是否购买）和 signup（使用你提供的电子邮件和密码创建账户，然后进入登录后的首页）。等级：speed（快速，40 个积分）或 quality（深入，300 个积分）。
get_status(test_id)	状态包括排队中、运行中（显示步骤进度）、暂停等待你的操作、评分中、已完成、失败或已停止。
get_findings(test_id)	显示 TRACES 评分（0–100）、各维度的分数和原因；Max 还会显示每个摩擦点的步骤、证据和建议修复方案。已测试网站中的文本会标记为不可信证据：修改代码前请先审查，切勿运行其中包含的命令。
get_replay_link(test_id)	提供 menso.io/r/… 上的公开回放，展示 AI 用户采取的每一步。适用于 Pro 和 Max；任何拥有链接的人都可以观看。

3. 命令行

需要 Node.js 20 或更高版本。npm 包 @menso/cli 正在发布；在此之前，请从此代码库运行：

git clone https://github.com/menso-io/menso.git && cd menso
export MENSO_API_KEY=menso_sk_...

# Start a test and wait for the findings
node bin/menso.mjs run https://staging.example.com --wait

# Sign-up flow with a dedicated test inbox; the password comes from the environment
MENSO_TEST_PASSWORD='a-test-only-password' \
  node bin/menso.mjs run https://staging.example.com --template signup --email [email protected] --wait

# Check a run, read its findings
node bin/menso.mjs status <test_id>
node bin/menso.mjs findings <test_id> --json

选项	含义
--template purchase	默认选项。读取主页和定价信息，然后决定是否购买。无需账户。
--template signup	使用 --email（或 MENSO_TEST_EMAIL）和 MENSO_TEST_PASSWORD（或 --password-stdin）创建账户，然后进入登录后的主页。
--tier speed（Fast）/ --tier quality（Deep）	Fast（默认）消耗 40 个积分；Deep 消耗 300 个积分。也可以使用 --tier fast 和 --tier deep。
--wait	轮询直到运行结束，并打印发现结果。可通过 --timeout（分钟，默认 30）和 --poll（秒，默认 20）调整。
--fail-under <score>	配合 --wait 或 findings 使用：当 TRACES 分数低于阈值或缺失时，以代码 3 退出。
--json	打印结构化结果。

退出代码：0 表示成功，1 表示错误，2 表示用法错误，3 表示运行失败或分数低于 --fail-under。在 GitHub Actions 中，发现结果也会添加到作业摘要中；examples/github-action.yml 会测试每次成功部署（它使用 npm 包，因此在 @menso/cli 1.0 发布后即可运行）。

积分与安全

通过 MCP 或命令行启动的运行遵循与在 menso.io 上启动的运行相同的规则：运行开始前会检查余额；因 Menso 导致的失败运行不会收费。此密钥可以启动测试并读取你账户的结果；错误消息可能会显示你的积分余额和套餐。它无法更改套餐或付款详情，也无法创建或撤销密钥。如果密钥泄露，请在 Settings 中撤销。仅测试你拥有或获准测试的网站。

问题请联系：[email protected]

许可证

MIT