mp-test-setup

mp-test-setup

此技能是创建测试用户的唯一入口。之所以需要它，是因为测试模式经常令人困惑——测试凭据分为两种不同类型，前缀也各不相同。

---

前置检查 — 创建测试用户前确认准备就绪

你现在处于集成流程的 第 4 步，共 7 步： 1. 创建应用 · 2. 获取 TEST 凭据 · 3. 搭建框架 · 4. 创建测试用户 ← 当前步骤 · 5. 端到端测试 · 6. /mp-review · 7. 生产环境

创建测试用户前，通过 AskUserQuestion 确认基本情况（最多 3 个问题——跳过 .mp-integrate-progress.md 中已记录的问题）：

1. 账户 — 如果已在 .mp-integrate-progress.md 中确认，则跳过。否则询问：“你有 Mercado Pago 开发者账户吗？” → Yes / No
2. 凭据 — 询问：“你有 APP_USR- 访问令牌吗？” → Yes / No
3. 凭据类型 — 询问：“你使用的是 TEST 凭据吗？——来自 {test_tab}？” → Yes, test credentials / No, production credentials / I don't know

• 没有账户 → 提供对应国家/地区的控制面板链接（智利：https://www.mercadopago.cl/developers — 不含 .com；其他国家/地区：https://www.mercadopago.com.{cc}/developers）。

• 没有凭据 → 如果开发者选择导入凭据：在调用 application_list 之前，立即执行 Step 0 中的按需流程；通过 AskUserQuestion 询问 “你想使用哪个应用？”，然后使用所选的 application_id 调用 mcp__plugin_mercadopago_mcp__get_credentials，并直接显示凭据。绝不要写入文件或提交。 手动引导开发者访问控制面板无需 MCP。

• 凭据类型 — No, production credentials 或 I don't know → 显示以下 阻止性警告，并且不要创建测试用户：

  ⛔ 警告 — 检测到生产凭据 如果使用生产环境进行测试，可能会产生真实的卡片扣款。请先切换到 Developer Dashboard 中的 {test_tab} 标签页。 👉 https://{DOMAIN}/developers/panel/app → Credentials → {test_tab} 标签页

  重复显示问题 3，直到开发者确认“是，测试凭据”。此检查不提供跳过选项——否则不要继续执行 Step 2（创建测试用户）。

创建或为测试用户充值需要 MCP，但准备情况引导和附带的测试卡片不需要。只有开发者要执行需要 MCP 的操作时，才连接 MCP。

---

当前测试模式 — 请先阅读

• 凭据前缀 — 分为两种不同类型：
  • APP_USR- → 来自 create_test_user 的测试用户凭据、生产凭据、Orders API、Checkout Pro、Point、QR
  • TEST- → 来自 {test_tab} 标签页的静态测试凭据，适用于 Checkout API / Bricks / Payments API 两种凭据都有效。get_credentials 会自动返回正确格式。绝不要建议开发者更改前缀。
• 测试用户凭据使用 APP_USR- 前缀，并且连接生产 API。测试用户拥有自己的余额（通过此技能充值），其行为与真实账户相同。
• 如需静态测试凭据且不创建测试用户：在 Developer Dashboard 中进入你的应用 → Credentials → 点击 {test_tab} 标签页。

---

步骤 0 — 仅在调用所选 MCP 工具之前连接

此技能启动时不要探测 MCP。请在调用 application_list、get_credentials、create_test_user、add_money_test_user 或 search_documentation 回退工具之前，立即按以下流程操作：

1. 如果可以直接调用预期工具，就直接尝试。不要使用 application_list 进行通用连接检查。
2. 如果该工具不可用或返回身份验证错误，请调用 mcp__plugin_mercadopago_mcp__authenticate，并使用开发者的语言显示 OAuth 链接。
3. 告知开发者使用 Cmd+Click（Mac）或 Ctrl+Click（Windows/Linux），不要将 URL 复制到外部浏览器。
4. 开发者返回后，直接重试预期工具。仅当实际操作是选择应用或导入凭据时，才调用 application_list。
5. 切勿询问回调 URL。身份验证失败两次后，提供以下选项：重试、继续使用离线指南／测试卡，或取消由 MCP 支持的操作。

---

步骤 1 — 在询问前确定 site_id

MCP 目前不会返回 site_id（其 application_list 仅返回 AppID／AppName／AppDescription，而允许我们调用 /users/me 的 OAuth 访问令牌不会向插件客户端公开）。请按以下顺序确定：

1. 使用 Agent 已传入的国家/地区作为 country= — Agent 已经确定了该值（来自持久化状态或向导）。
2. 读取项目根目录中的 .mp-integrate-progress.md — 如果之前运行时已保存国家/地区，则重复使用。
3. 最后才通过 AskUserQuestion 询问（使用选择器，切勿使用带编号的文本块）。将答案保存到 .mp-integrate-progress.md。

不要在代码库中 grep currency_id／site_id 字面量或区域设置字符串 — 它们在干净的代码库中并不可靠，还会浪费令牌。

步骤 2 — 创建测试用户

在执行以下 MCP 调用前，立即应用步骤 0。

调用 mcp__plugin_mercadopago_mcp__create_test_user，并传入：

参数	必填	值
site_id	是	MLA（阿根廷）、MLB（巴西）、MLM（墨西哥）、MLC（智利）、MCO（哥伦比亚）、MPE（秘鲁）、MLU（乌拉圭）
description	是	用于标识用户的自由文本（例如，"buyer for checkout-pro tests"）
profile	是	seller 或 buyer — 选择要模拟的角色
amount	否	以所在国家/地区货币计的初始余额

该工具会返回用户 ID、电子邮件、密码和 APP_USR- 凭据。

⚠️ 重要区别 — 两种类型的凭据：

• 测试用户电子邮件 + 密码 → 用于测试期间以买家／卖家身份登录结账页面。不要用于 .env。
• 测试用户的 APP_USR- 凭据 → 测试用户自己的 API 凭据。仅在需要以该测试用户身份发起 API 调用时使用（例如，市场卖家 OAuth 流程）。不是你应用的 MP_ACCESS_TOKEN。
• 你应用的 MP_ACCESS_TOKEN → 来自 DevPanel → 你的应用 → {test_tab} 选项卡。该令牌应写入你的 .env。由 mp-integrate 创建，而非由 create_test_user 创建。

如果开发者需要交易双方的账户（市场、订阅、P2P 中通常如此），请创建一个 seller 和一个 buyer。

---

步骤 3 — 充值（需要时）

如果会话尚未完成身份验证，请在执行以下 MCP 调用前立即应用步骤 0。

调用 mcp__plugin_mercadopago_mcp__add_money_test_user，并传入：

参数	必填
test_user_id	是 — create_test_user 返回的 ID
amount	是 — 以用户货币计的金额

充值金额受国家/地区限制。如果调用因限额错误而失败，请询问是否减少金额，并重试一次。

---

第 4 步 — 测试卡

测试卡时，不要自行编造卡号。

1. 首先，阅读 ${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/products.md — 其中整理了固定到特定版本的 AR、BR、MX、CO、CL 测试卡（卡号、CVV、有效期，以及 APRO/OTHE/FUND/… 状态码表）。Claude Code 会将其解析为当前启用的插件版本。绝不要搜索其他市场或安装缓存。这五个国家/地区无需调用 MCP。
2. 仅当该国家/地区未在其中列出时（例如 PE、UY），才应用第 0 步，并通过 MCP search_documentation 查询 "test cards {country}"（例如 "test cards peru"）。

---

第 5 步 — 将凭据交给开发者

输出模板：

## Test user created

**Country**: {country}
**Profile**: {seller | buyer}
**User id**: {id}
**Initial balance**: {amount} {currency}

### 🔑 Login credentials (to simulate the buyer/seller at checkout)

Use these to **log in at the Mercado Pago checkout page** during a test purchase:

- **Email**: {email}
- **Password**: {password}

> These are NOT your MP_ACCESS_TOKEN. Do NOT put these in your `.env`.

---

### 📋 Your app's test credentials (for your `.env`)

These come from **DevPanel → your app → {test_tab} tab** — NOT from the test user.

MP_ACCESS_TOKEN=APP_USR-... ← 你的应用测试访问令牌（来自 DevPanel） MP_PUBLIC_KEY=APP_USR-... ← 你的应用测试公钥（来自 DevPanel）

> Both types of credentials use the `APP_USR-` prefix — what matters is WHERE they come from:
> - Your `.env`: from DevPanel → your app → {test_tab} tab
> - Checkout login: the test user's email + password above

### Next steps
- Use the test user **email + password** to log in at the checkout when making a test purchase.
- Use your app's **MP_ACCESS_TOKEN** (from DevPanel) in your backend to create orders/payments.
- For card payments, use the test cards in `references/products.md`.
- Smoke test with `mp-webhooks` → trigger a real test payment to fire the webhook.
- Run `mp-review` after a successful test payment.

---

注意事项

• 测试用户凭据与生产凭据看起来完全相同。如果 .env 文件泄露，买家和卖家的余额都会暴露。
• 测试用户的电子邮件/密码可用于登录 mercadopago.com.{tld} — 开发者可以登录查看交易记录。
• 测试用户属于 site_id 指定的国家/地区；尝试在巴西站点使用阿根廷测试凭据会静默失败，返回 not_found 支付。
• 充值有每个国家/地区的每日限额。如果达到限额，请创建新的测试用户，而不是提高限额。

---

此技能不做什么

• 它不会签发真实的生产凭据。生产凭据需从 Developer Dashboard 获取。
• 它不会验证 Webhook（请使用 mp-webhooks），也不会搭建集成代码（请使用 mp-integrate）。