M00N Report

@m00nsolutions/mcp-server

通过 MCP 实现 Agentic 测试管理。这个服务让 AI 助手直接开展工作，而非只阅读相关内容：在 M00N Report 中编写测试用例、规划并填充手动测试执行、将自动化测试关联到其覆盖的用例、发布版本并查看项目健康状况。M00N Report 是一个 AI 原生测试管理平台。

我需要安装哪一种？

	此 npm 包（stdio）	托管远程连接器
运行方式	通过 npx @m00nsolutions/mcp-server 作为本地进程运行	无需本地进程；客户端通过 HTTP 与 API 通信
身份验证	在 M00N_API_KEY 中设置 MCP 密钥	使用 PKCE 的 OAuth 2.1，浏览器授权页面
客户端	任何 MCP 客户端：Claude Code、Claude Desktop、Cursor 等	仅限 claude.ai 和 claude.com

如果你不是从 claude.ai 或 claude.com 连接，请使用此软件包和 MCP 密钥。本 README 的其余部分介绍的就是这种方式。关于连接器，请参阅连接器指南。

要求

Node 20 或更高版本，以及任何支持 MCP 的客户端。

安装

无需安装步骤。客户端会按下方配置，通过 npx 启动它。

若要在共享环境或 CI 环境中固定版本，请在 args 中的软件包名称后追加版本号，例如 ["-y", "@m00nsolutions/mcp-server@<version>"]。运行 npm view @m00nsolutions/mcp-server versions 可查看已发布的版本。这里特意使用占位符而非具体版本号：具体示例在下次发布后就会过时，而过时的示例会建议固定到一个已不包含最新修复的版本。

快速开始

1. 获取 MCP 密钥

在 M00N Report 中，打开 Settings -> MCP Keys 并创建一个密钥。该密钥以 m00n_mcp_ 开头，后跟 48 个十六进制字符。这不是测试报告者使用的凭据；他们的凭据以 m00n_ 开头，在此处会被拒绝。

MCP 密钥的权限与其所属账户完全相同，不会更多，也可以进一步限定范围。限定范围会从客户端可见的工具列表中移除工具，因此，工具列表比预期更短是范围设置所致，并非故障。

密钥应放在你机器上的 MCP 客户端配置中。不要将它放入存储在代码库中的工作区文件。

2. 连接客户端

Claude Code，只需一行：

claude mcp add m00n --env M00N_API_URL=https://m00nreport.com --env M00N_API_KEY=m00n_mcp_... -- npx -y @m00nsolutions/mcp-server

其他所有客户端都使用相同的 JSON 块：

{
  "mcpServers": {
    "m00n": {
      "command": "npx",
      "args": ["-y", "@m00nsolutions/mcp-server"],
      "env": {
        "M00N_API_URL": "https://m00nreport.com",
        "M00N_API_KEY": "m00n_mcp_your_key_here"
      }
    }
  }
}

该配置块的位置：

客户端	配置文件
Cursor	~/.cursor/mcp.json
Claude Desktop，macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop，Windows	%APPDATA%\Claude\claude_desktop_config.json

对于可自托管实例，请将 M00N_API_URL 指向你自己的根源站，不要添加 /api 后缀。末尾的斜杠会自动移除。

3. 确认连接

重启客户端，然后向它提问：

列出我的 M00N Report 项目

如果返回了项目列表，说明服务已连接且密钥有效。如果出现错误，或助手表示没有此类工具，则表示连接未成功；请参阅故障排除。

工具

分为 8 个领域。包含参数的完整列表位于 /documentation/mcp/tools，并与代码一同维护。服务会在启动时从你的实例获取工具列表，因此客户端看到的内容，就是客户端连接时你的实例所支持的内容。

领域	涵盖内容
项目与分析	项目、发布趋势与统计信息、单个测试的历史记录、跨自动化测试搜索
测试用例	创建、读取、更新、移动、删除、批量编辑测试用例，并将自动化测试关联到其覆盖的用例
文件夹与测试套件	文件夹和测试套件的层级结构，以及各文件夹的统计信息
测试集合	可复用的命名用例集，可添加到任何执行中
手动执行	根据测试套件、集合或单个用例创建一次执行，然后记录每个用例的结果
发布	创建和管理发布，并附加或移除其中的发布记录
健康状况与覆盖率	综合健康检查、双向覆盖缺口、用例建议、功能扫描、报告导出
外部链接	在用例上附加或移除 Jira 或 Linear 工单

一次执行就是一轮手动测试：其中记录了负责人、环境、日期，以及根据添加用例时的快照记录的每个步骤的结果。

你的密钥可查看的工具数量取决于你的实例：

curl -s -H "X-MCP-Key: $M00N_API_KEY" "$M00N_API_URL/api/mcp/tools" | jq .count

受限范围的密钥可查看的工具更少。这里有意不写具体数量：工具范围会随版本变化，而 README 中的数字最容易被忘记更新。

提示词

客户端可按名称提供的多步引导式工作流。每个提示词都接受一个可选的 project 参数，可以是名称或 UUID；省略时，如果范围内只有一个项目，服务就会选择该项目。

提示词	功能
analyze_flaky_tests	找出无需代码更改却时而通过、时而失败的测试，并对其排序
debug_test_failure	根据某次失败的历史记录和跟踪信息，逐步排查其原因
release_readiness	判断某个版本是否可以安全发布
generate_test_cases	为尚无用例的领域起草手动测试用例
weekly_health_report	汇总各项目本周的情况
investigate_regression	找出一次通过运行与一次失败运行之间的变化
run_manual_execution	完成一轮手动测试，从组装测试到记录每个用例的结果

资源

客户端无需调用工具即可获取的只读视图：所有项目、项目健康状况摘要、不稳定测试报告、当前失败的测试、文件夹结构、发布报告、测试用例内容、发布摘要。

配置

环境变量	必填	默认值	描述
M00N_API_URL	连接时必填		你的 M00N Report URL。根源地址，不带 /api 后缀。末尾的斜杠会自动去除。
M00N_API_KEY	连接时必填		MCP 密钥（m00n_mcp_...）。不带此前缀的密钥会在首次请求前被拒绝。
M00N_DEBUG	否	false	将每次请求的详细信息（包括每次工具调用的参数）添加到 stderr。无论是否启用，启动步骤和错误都会记录。
M00N_TIMEOUT_MS	否	30000	请求超时时间，单位为毫秒，填写纯数字。60s、1e4、30,000 和 1.5 均会被拒绝，并在 stderr 上显示警告，随后使用默认值。
M00N_INSECURE_SSL	否	false	接受自签名证书。仅适用于可自托管实例。

这两个布尔值在设置为 true、1 或 yes（不区分大小写）时启用。其他任何值，包括 false 和 0，都会使其保持关闭。

前两个变量要么都设置，要么都不设置。只设置其中一个会被视为错误并遭拒绝，因为无法排查一个半配置后仍然启动的服务，相比之下，服务无法启动反而更容易诊断。

此处的基础 URL 变量名为 M00N_API_URL；测试报告器将同一 URL 称为 M00N_SERVER_URL。所有 6 个软件包都读取 M00N_API_KEY，但它们使用的是项目 API 密钥，而非 MCP 密钥，因此同一个导出的 shell 变量无法同时用于两者。

无密钥运行

在未设置 M00N_API_URL 和 M00N_API_KEY 的情况下启动时，服务会以预览模式运行：它会从内置快照中列出工具、提示词和资源，并拒绝所有调用，同时告知需要设置什么。由于没有发送目标，因此不会向任何地方发送数据。

因此，检查器、客户端或目录可以在任何人注册前展示工具界面。这只是对服务的描述，并非可运行的服务，所以列表来自快照，而不是你的实例：通常，限定范围的密钥能看到的工具比快照显示的更少。

维护者使用未限定范围的密钥运行 npm run snapshot:refresh 来刷新快照。

自托管

将 M00N_API_URL 指向你自己的实例，并从该实例签发 MCP 密钥。其他一切都相同；如果你选择自托管是因为测试数据不能离开你的网络，这一点就很重要。

如果使用自签名证书，请在同一个 env 块中添加 "M00N_INSECURE_SSL": "true"。完整说明：／documentation/mcp/self-hosted。

发送的内容

通过 HTTPS 发送至 M00N_API_URL：助手发起的工具调用及其参数。该服务是你自己实例的代理，不会自行存储任何内容。

每次工具调用都会写入 MCP 审计日志，并可在应用中查看；每个密钥的速率限制可遏制失控的 Agent。密钥绝不会写入该日志，也不会写入 stderr。在 M00N_DEBUG 模式下，每次工具调用的参数都会打印到 stderr，因此请像对待数据本身一样谨慎处理这些输出。

故障排除

症状	原因
客户端未显示任何 M00N Report 工具	配置尚未重新加载。请完全重启客户端，而不只是重启对话。
工具已列出，但每次调用都返回 running unconfigured	M00N_API_URL 和 M00N_API_KEY 均未传入进程，因此它以预览模式启动。请检查 env 块是否确实应用于此服务。
M00N_API_KEY should start with "m00n_mcp_"	这是项目 API 密钥，也就是测试报告人员使用的那类密钥。MCP 密钥是单独的：Settings -> MCP Keys。
Authentication failed: Invalid or expired MCP key	密钥错误、已撤销或来自其他实例。也可能是 M00N_API_URL 带有 /api 后缀，导致每个请求都返回 401，无论密钥是否有效。请先检查 URL，然后签发新密钥。
WARNING: M00N_API_URL is http://...	这不是错误，服务会继续运行。这表示每次请求都会以未加密方式发送密钥。除非实例位于可信的专用网络，否则请使用 https。环回地址不会触发警告。
... redirected to ...	该 URL 返回了重定向。由于 MCP 密钥可能会被发送到重定向目标，因此不会跟随重定向。请将 M00N_API_URL 设置为可直接响应的地址，通常是 https:// 形式。
Cannot connect to M00N Report API at ...	该 URL 上没有服务在监听。实例已关闭，或者该端口对你不可用。
Cannot resolve M00N Report API host	主机名无法解析。可能是拼写错误，也可能是从其网络外部访问了专用名称。
Request to M00N Report API timed out	请调高 M00N_TIMEOUT_MS，或检查网络路径。
SSL certificate error connecting to ...	可自托管实例使用了自签名证书。请将 M00N_INSECURE_SSL 设置为 true。
Not found during ...	该行其余部分是服务器自己的响应，通常会指出如何修复，例如列出实际存在的项目。请先阅读，再更改设置。
Rate limit exceeded. Retry after Ns.	每个密钥每分钟最多调用 1000 次工具，按滑动窗口计算。消息中会告知需要等待的时间。Agent 执行任务时很少会接近此上限；触发上限通常意味着出现了循环。
工具数量少于预期	密钥受权限范围限制，或者实例版本早于此软件包。工具列表由你的实例提供。

无论是否设置 M00N_DEBUG，服务都会将日志写入 stderr，大多数客户端会在其 MCP 面板中显示这些日志。将 M00N_DEBUG 设置为 true，即可记录每个请求及其参数。

已知限制

• 工具列表只在启动时读取一次。 重新调整密钥权限范围或升级实例后，客户端会继续使用旧列表，直到你重启客户端。
• 配置完成后，必须能够访问 GET /api/health。 服务会首先检查此接口；如果检查失败，服务就会停止。因此，即使每个工具都能正常工作，如果代理只转发 /api/mcp/*，也不会显示任何工具。
• 权限范围为零个工具的密钥无法启动服务。 服务会直接退出，而不是以空列表连接。这是配置后的运行路径；如果完全没有凭据，服务则会以预览模式启动。
• 提示词和资源是可选的。 如果无法获取它们的列表，服务仍会启动，并将原因写入 stderr；整个会话期间，客户端都看不到这些内容。
• 重定向会被拒绝，不会跟随。 密钥通过自定义标头传递，而跟随重定向的客户端只会删除它们识别的身份验证标头，因此跟随重定向会将密钥交给下一个响应的主机。服务会报告重定向指向的地址。
• 仅支持 stdio。 如需使用 HTTP 传输，请使用托管连接器。

支持

• npm 上的软件包
• 文档
• 报告问题
• 社区 Discord

许可证

MIT 许可证。请参阅 LICENSE。