wopee-mcp

Wopee MCP 服务

为应用提供 AI 驱动的自主测试——将 Claude、Cursor 或任何兼容 MCP 的 AI Agent 连接到 Wopee.io，在几秒内生成测试用例、用户故事并运行自主测试。

npx wopee-mcp

文档 | 产品介绍页 | 控制面板

设置

前提条件

• Node.js（建议使用 v18 或更高版本）
• 支持 MCP（Model Context Protocol）的 IDE，例如 Cursor 或 VSCode

MCP 服务配置

将此服务添加到 MCP 配置中。

配置示例

{
  "mcpServers": {
    "wopee": {
      "command": "npx wopee-mcp",
      "env": {
        "WOPEE_PROJECT_UUID": "your-project-uuid-here",
        "WOPEE_API_KEY": "your-api-key-here"
      }
    }
  }
}

必需的环境变量

• WOPEE_PROJECT_UUID - Wopee 项目的 UUID。此变量用于标识你正在使用的项目。
• WOPEE_API_KEY - Wopee API 密钥。你可以在 cmd.wopee.io 的项目设置中创建密钥。

可选的环境变量

• WOPEE_API_URL - Wopee API 端点 URL。仅应在测试/开发时指定。

企业代理配置

如果你在企业代理/VPN 后方并遇到连接超时，可以使用标准环境变量配置代理设置：

{
  "mcpServers": {
    "wopee": {
      "command": "npx wopee-mcp",
      "env": {
        "WOPEE_PROJECT_UUID": "your-project-uuid-here",
        "WOPEE_API_KEY": "your-api-key-here",
        "HTTPS_PROXY": "http://your-proxy-server:8080"
      }
    }
  }
}

支持的代理环境变量

• HTTPS_PROXY 或 https_proxy - HTTPS 连接的代理服务 URL（推荐）
• HTTP_PROXY 或 http_proxy - 备用代理服务 URL

查找代理设置

如果不确定代理设置，请查看 VS Code 设置（settings.json）中的 http.proxy 值，或咨询 IT 部门。常见的企业代理格式：

• http://proxy.company.com:8080
• http://10.x.x.x:8080
• http://username:[email protected]:8080（需要身份验证时）

TLS / 证书问题

MCP 正常运行不需要此项。 如果你看到 HTTPS 或证书相关错误，说明你的环境中存在 TLS 或证书信任问题。

如果服务因 UNABLE_TO_VERIFY_LEAF_SIGNATURE 或 certificate has expired 等错误而无法运行，可能是由于：

• 自签名证书（例如，WOPEE_API_URL 指向内部或开发服务时）
• 企业代理 / SSL 检查（流量使用企业 CA 重新加密，而你的机器不信任该 CA）
• Node 信任存储中缺少 CA 证书

首选解决方案（安全）

1. 使用有效的 TLS 证书——例如 Let’s Encrypt 或内部 CA，并确保提供完整的证书链。

2. 安装企业或内部 CA，以便 Node 信任它：

   示例：

   export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/internal-ca.pem
   

   在 MCP 配置的 env 中：

   "env": {
     "WOPEE_PROJECT_UUID": "your-project-uuid-here",
     "WOPEE_API_KEY": "your-api-key-here",
     "NODE_EXTRA_CA_CERTS": "/path/to/ca.pem"
   }
   

不安全的临时解决方法（不推荐）

仅用于本地调试，你可以在 Node 中禁用 TLS 验证。此方法绝不能用于生产环境，因为它会禁用 HTTPS 安全保护，使流量面临被拦截的风险。

export NODE_TLS_REJECT_UNAUTHORIZED=0

或在 MCP 配置的 env 中：

"env": {
  "WOPEE_PROJECT_UUID": "your-project-uuid-here",
  "WOPEE_API_KEY": "your-api-key-here",
  "NODE_TLS_REJECT_UNAUTHORIZED": "0"
}

请将此方法视为仅供调试使用的应急手段，而非常规设置步骤。

注意： 有些用户还报告说设置了 PYTHONHTTPSVERIFY=0。此 MCP 服务不使用 Python；该变量对它不起作用。它仅适用于运行基于 Python 的 MCP 主机，或在同一环境中执行 HTTPS 的其他工具——这些均不在此服务的范围内。

开始使用

此 MCP 服务中的大多数工具都需要 suiteUuid 才能运行。你有两种开始方式：

选项 1：使用现有套件

首先获取现有的分析套件：

Use the wopee_fetch_analysis_suites tool to retrieve all available suites for your project.

这将返回所有分析套件及其 UUID 的列表，你可以将这些 UUID 用于其他工具。

选项 2：创建新套件

如果你还没有任何套件，可以选择以下两种方式：

自动分析： 创建并分派完整的分析／爬取套件：

Use the wopee_dispatch_analysis tool to create and dispatch a new analysis/crawling suite.

空白套件： 创建一个空套件，供手动配置：

Use the wopee_create_blank_suite tool to create a blank analysis suite.

两种方式都会返回套件 UUID，可用于后续操作。

可用工具

套件管理

wopee_fetch_analysis_suites

获取项目的所有分析套件。查看可用套件是一个很好的起点。

• 返回： 分析套件数组，包含其 UUID、名称、状态和元数据

用法示例：

Fetch all existing analysis suites for my project

wopee_dispatch_analysis

为项目创建并分派新的分析／爬取套件，或重新运行现有套件。可用于启动新的分析会话，或重新触发之前的分析。

• 参数：
  • additionalInstructions (可选) - 在分析／爬取阶段用于指导 Agent 的额外说明（例如关注领域、忽略事项、登录步骤等）
  • additionalVariables (可选) - 传递给分析的额外环境变量。对象数组，每个对象包含：
    • key - 变量名，只能包含大写字母和下划线（例如 MY_VAR、BASE_URL）
    • value - 变量值（非空字符串）
  • rerun (可选) - 如果提供，则重新运行现有分析套件，而不是创建新套件。对象包含：
    • suiteUuid - 要重新运行的现有套件的 UUID
    • analysisIdentifier - 现有套件的分析标识符
    • mode - 重新运行模式：FULL（重新运行整个分析，包括爬取和生成）或 CRAWLING（仅重新运行爬取阶段）
• 返回： 成功消息，包含已创建／重新运行的套件信息

用法示例：

Dispatch a new analysis suite

Dispatch a new analysis suite and focus on the checkout flow

Dispatch a new analysis suite with additional variables CARD_FILAMENT=123321123 and AUTH_TOKEN=abc123

Rerun the full analysis for suite <suiteUuid> with analysis identifier <analysisIdentifier>

Rerun only the crawling phase for suite <suiteUuid> with analysis identifier <analysisIdentifier>

wopee_create_blank_suite

为项目创建一个空白分析套件。如果你想手动配置并填充套件，而不是自动进行分析，请使用此工具。

• 返回： 已创建的套件信息，包括其 UUID

用法示例：

Create a blank analysis suite for my project

生成工具

这些工具可为指定套件生成各种产物。生成时都需要提供 suiteUuid 和 type。

wopee_generate_artifact

为选定的套件生成指定文件（产物）。

• 参数：
  • suiteUuid - 套件的 UUID
  • type - "APP_CONTEXT" | "GENERAL_USER_STORIES" | "USER_STORIES_WITH_TEST_CASES" | "TEST_CASES" | "TEST_CASE_STEPS" | "REUSABLE_TEST_CASES" | "REUSABLE_TEST_CASE_STEPS"
  • mode (可选，仅限 TEST_CASES) - "UPDATE"（默认）保留现有测试用例及其步骤和运行历史记录；"CREATE" 替换范围内的测试用例，并删除其步骤、运行记录和代码
  • selectedUserStories (可选) - 用于将 TEST_CASES／TEST_CASE_STEPS 限定到指定用户故事的 ID，例如 ["US001"]；留空表示所有故事
  • selectedTestCases (可选) - 用于将 TEST_CASE_STEPS 限定到指定测试用例的标识符，例如 ["US001:TC002"]
  • instructions (可选) - 传递给 AI 引擎的变更请求
  • async (可选，仅限 TEST_CASES／USER_STORIES_WITH_TEST_CASES) - 任务进入队列后立即返回，而不是等待产物生成
• 返回： 成功生成时返回生成的输出。

用法示例：

Generate app context for my most recent analysis suite

获取工具

这些工具可获取指定套件生成的产物。都需要提供 suiteUuid 和 type。

wopee_fetch_artifact

从选定的套件获取所查询的文件（产物）。

• 参数：
  • suiteUuid - 套件的 UUID
  • type - "APP_CONTEXT" | "GENERAL_USER_STORIES" | "USER_STORIES" | "PLAYWRIGHT_CODE" | "PROJECT_CONTEXT"
  • identifier - 要获取 Playwright 代码的测试用例标识符，例如 US003:TC004
• 返回： 成功获取时返回文件内容。

用法示例：

Fetch user stories for the latest suite

更新工具

这些工具用于更新或设置特定套件的某些文件（制品）。必须提供 suiteUuid、type 和 content。

wopee_update_artifact

更新或替换特定套件中现有的文件（制品）

• 参数：
  • suiteUuid - 套件的 UUID
  • type - "APP_CONTEXT" | "GENERAL_USER_STORIES" | "USER_STORIES" | "PLAYWRIGHT_CODE" | "PROJECT_CONTEXT"
  • content - app context、general user stories 和 project context 的 Markdown 内容；user stories 的结构化 JSON
  • identifier - 要获取 Playwright 代码的测试用例标识符，例如 US003:TC004
• 返回值： 根据工具调用是否成功返回布尔值

用法示例：

Update app context file for the most recent suite with this content: <YourMarkdown>

Agent 测试

wopee_dispatch_agent

调度自主测试 Agent，为所选套件执行测试用例。测试会异步运行（通常需要 1-3 分钟）。此工具确认调度并返回跟踪信息，而非最终结果。

• 参数：
  • suiteUuid - 包含测试用例的套件 UUID
  • analysisIdentifier - 套件的分析标识符
  • testCases - 要执行的测试用例对象数组，每个对象包含：
    • testCaseId - 测试用例的 ID
    • userStoryId - 关联用户故事的 ID
• 返回值： 调度确认信息及跟踪信息（套件 UUID、分析标识符、每个测试用例的执行状态）。不会返回通过/失败结果——稍后请使用 wopee_fetch_recent_executions 或 wopee_fetch_executed_test_cases 检查结果。

用法示例：

Dispatch agent for my latest suite's user story US001 and test case TC003

测试结果

wopee_fetch_recent_executions

获取当前项目最近执行的测试用例（最多 20 个，按时间从新到旧排列）。无需记住特定套件 UUID，即可快速检查最近调度的测试状态。

• 参数： 无（使用环境中的 WOPEE_PROJECT_UUID）
• 返回值： 最近执行记录列表，包含执行状态（IN_PROGRESS、IN_QUEUE、FINISHED、FAILED）、Agent 报告以及通过/失败结果

用法示例：

What's the status of my recent test runs?

How did my tests go?

wopee_fetch_executed_test_cases

获取指定分析套件中已执行的测试用例及其结果。可用于检查已调度的 Agent 运行状态和报告。

• 参数：
  • suiteUuid - 要获取结果的分析套件 UUID
  • analysisIdentifier (可选) - 用于缩小结果范围的分析标识符（例如 A068）
• 返回值： 按用户故事分组的结果数组，每组包含已执行的测试用例及其执行状态、Agent 报告、Agent 报告状态、代码报告和代码报告状态

用法示例：

Fetch test results for suite <suiteUuid>

Show me the executed test cases for my latest analysis suite

报告

wopee_create_github_issue

将 GitHub 问题提交到与当前项目关联的仓库。提供失败运行的 executedTestCaseUuid 后，Wopee.io 会在你的文本下方添加该运行的已知信息：失败步骤、预期结果与实际结果、失败步骤的截图，以及 Commander 中该运行的链接。

• 参数：
  • title - 问题标题
  • body (可选) - Markdown 内容，会原样保留在运行证据上方
  • labels (可选) - 要应用的标签，例如 ["bug"]。GitHub 可能会跳过仓库中不存在的标签；结果会说明哪些标签已应用
  • executedTestCaseUuid (可选) - 要附加证据的运行，值可通过 wopee_fetch_recent_executions 或 wopee_dispatch_agent 查看
• 返回： 问题编号和 URL，以及未能添加的内容说明（例如无法上传的截图）
• 要求： 问题由 Wopee.io GitHub App 创建，且问题正文会提及你。该 App 的安装需要拥有仓库的 Issues: Read & write 权限；截图会提交到单独的 wopee-issue-assets 分支，因此还需要 Contents: Read & write 权限。该分支与代码没有共同历史记录，可以安全删除；删除后只会导致现有问题中的图片失效。

用法示例：

File the failed checkout test as a GitHub issue

典型工作流

1. 从测试套件开始：

   • 使用 wopee_fetch_analysis_suites 查看现有测试套件，或
   • 使用 wopee_dispatch_analysis 创建新的测试套件

2. 生成产物：

   • 生成应用上下文：使用 wopee_generate_artifact，并指定 APP_CONTEXT 和 suiteUuid
   • 生成通用用户故事：使用 wopee_generate_artifact，并指定 GENERAL_USER_STORIES 和 suiteUuid
   • 生成包含测试用例的用户故事：使用 wopee_generate_artifact，并指定 USER_STORIES_WITH_TEST_CASES 和 suiteUuid
   • 生成可复用的测试用例：使用 wopee_generate_artifact，并指定 REUSABLE_TEST_CASES 和 suiteUuid
   • 生成可复用的测试用例步骤：使用 wopee_generate_artifact，并指定 REUSABLE_TEST_CASE_STEPS 和 suiteUuid
   • 生成测试用例步骤：使用 wopee_generate_artifact，并指定 TEST_CASE_STEPS 和 suiteUuid

3. 获取生成的内容：

   • 使用获取工具检索生成的 Markdown/JSON 文件

4. 运行测试：

   • 使用 wopee_dispatch_agent 通过自主测试 Agent 执行测试用例

5. 检查结果：

   • 使用 wopee_fetch_recent_executions 快速检查近期测试运行的状态
   • 使用 wopee_fetch_executed_test_cases 检查特定测试套件的详细状态和报告
   • 或使用 fetch-test-results 提示词，获取所有测试结果的格式化摘要

6. 报告失败：

   • 使用 wopee_create_github_issue，并提供失败运行的 executedTestCaseUuid，将问题提交到你的仓库

可用提示词

fetch-project-summary

获取分析测试套件及其用户故事/测试用例，然后通过两个 Markdown 表格显示格式化摘要：测试套件概览和详细的测试用例明细。

fetch-test-results

获取分析测试套件及其已执行测试用例的结果，然后通过格式化的 Markdown 表格显示每个测试用例的执行状态、Agent 报告状态和代码报告状态。也会列出失败报告的详情。

备注

• 大多数工具都需要 suiteUuid。请始终先获取或创建一个测试套件。
• wopee_dispatch_analysis 工具会完成整个处理周期——爬取应用并逐个生成所有文件（产物）。
• 建议使用 cmd.wopee.io，以便直观地查看生成的数据和 Agent 运行结果。