Debugg AI

官方

使您的代码生成代理能够通过Debugg AI测试平台，在远程浏览器中针对新的代码变更创建并运行零配置的端到端测试。

GitHub

你可以用 Debugg AI MCP 做什么？

针对任意 URL 运行 AI 浏览器代理 — 用自然语言描述测试内容，check_app_in_browser 会自动导航、交互，并返回通过/失败结果及截图。
零 LLM 成本探测多个页面 — 单次批量向 probe_page 发送最多 20 个 URL，快速获取截图、控制台错误和网络摘要。
触发知识图谱爬取 — 使用 trigger_crawl 让 AI 代理探索你的应用，并填充项目的知识图谱。
管理测试套件与测试用例 — 通过 test_suite 创建、列出、运行测试套件并查看结果，通过 test_case 定义单个用例。
检查执行产物 — 通过 executions 获取完整的执行详情、截图、HAR 跟踪记录和控制台日志，用于调试失败。
将项目、环境和执行视为资源浏览 — 通过 debugg-ai:// URI 直接引用实体，无需调用工具即可获取上下文。

文档

Debugg AI — MCP 服务器

基于 AI 的浏览器测试，通过模型上下文协议实现。将其指向任何 URL（或 localhost）并描述要测试的内容——AI 代理会浏览你的应用并返回通过/失败结果及截图。

安装

需要 Node.js 20.20.0 或更高版本（来自 posthog-node@^5.26.0 的传递性要求）。

在 debugg.ai 获取 API 密钥，然后添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "debugg-ai": {
      "command": "npx",
      "args": ["-y", "@debugg-ai/debugg-ai-mcp"],
      "env": {
        "DEBUGGAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

或使用 Docker：

docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp

工具

服务器公开了 8 个工具：三个 浏览器 工具，外加每个受管实体一个 基于操作 的工具。主要工具是 check_app_in_browser（完整的 AI 代理）和 probe_page（轻量级无 LLM 页面探测）。其余的——project、environment、test_suite、test_case、executions——每个都接受一个 action 鉴别器（例如 {"action":"list"}）来选择操作。破坏性的 delete 操作需要确认（在支持的地方显示提示，否则为 confirm: true）。

浏览器

`check_app_in_browser`

针对你的应用运行 AI 浏览器代理。代理会导航、交互，并返回截图报告。Localhost URL 会通过 ngrok 自动建立隧道。

参数	类型	描述
`description`	string 必填	要测试的内容（自然语言）
`url`	string 必填	目标 URL——`http://localhost:3000` 会自动建立隧道
`environmentId`	string	特定环境的 UUID
`credentialId`	string	特定凭据的 UUID
`credentialRole`	string	按角色选择凭据（例如 `admin`、`guest`）
`username`	string	用于登录的用户名（临时——不会持久化）
`password`	string	用于登录的密码（临时——不会持久化）
`repoName`	string	覆盖自动检测的 git 仓库名称（例如 `my-org/my-repo`）

每次调用只进行一项重点检查。代理有大约 25 步的内部预算；将更广泛的测试套件拆分到多次调用中。

每次成功运行都会返回一个 browserSession 块以及截图——捕获的 HAR（完整网络跟踪）和 控制台日志（每条 JS 控制台消息）的预签名 S3 URL。使用它们来检测重新获取循环、水合错误以及其他通过类型检查和单元测试的运行时问题：

"browserSession": {
  "harUrl": "https://...session_18139.har?X-Amz-...",
  "consoleLogUrl": "https://...session_18139_console.json?X-Amz-...",
  "recordingUrl": "https://...session_18139_recording.webm?X-Amz-...",
  "harStatus": "downloaded",
  "consoleLogStatus": "downloaded",
  "harRedactionStatus": "redacted",
  "consoleLogRedactionStatus": "redacted"
}

URL 是短期有效的预签名 S3——通过 executions {action:"get", uuid} 重新获取父执行以续期。harStatus / consoleLogStatus 用于区分 'downloaded'（URL 可获取）、'not_available'（页面未发出任何内容）、'failed'（捕获中断）。在新运行中，URL 通常是 null，因为捕获上传是在代理完成后异步进行的——轮询 executions {action:"get", uuid: executionId} 直到状态达到 'downloaded'。授权 / Cookie / token/secret/api_key 标头在工件持久化之前会在服务器端被清除。

`trigger_crawl`

触发服务器端浏览器代理爬取，以填充项目的知识图谱。Localhost URL 会自动建立隧道。成功摄取后返回 {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} 和 knowledgeGraph.imported === true。browserSession 块（HAR + 控制台日志 URL，形状与上述相同）也会在完成的爬取中出现。

`probe_page`

轻量级无 LLM 批量页面探测。 传入 1-20 个 URL；每个 URL 都会导航、等待加载，并返回渲染状态——截图 + 页面元数据 + 结构化的控制台错误 + 网络摘要。没有代理循环，没有 LLM 成本，没有场景断言。用于“我刚刚是否破坏了 /settings？”、重构后的多路由冒烟测试、CI 中每个 PR 的扫描，以及在 check_app_in_browser 的 60-150 秒代理循环显得过度的快速启动检查。

参数	类型	描述
`targets`	array 必填	1-20 个条目：`[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]`
`targets[].url`	string 必填	公共 URL 或 localhost（自动建立隧道）
`targets[].waitForLoadState`	enum	`'load'`（默认）/ `'domcontentloaded'` / `'networkidle'`
`targets[].waitForSelector`	string	导航后要等待的可选 CSS 选择器
`targets[].timeoutMs`	number	每个 URL 的超时时间，1000-30000（默认 10000）
`includeHtml`	boolean	在每个结果中返回原始 HTML（默认 false）
`captureScreenshots`	boolean	每个目标返回一张 PNG（默认 true）

整个批次共享一个后端执行 + 浏览器会话 + 隧道——一次调用中的 5 个 URL 比 5 个并行的单 URL 调用快得多。每个 URL 的 error 字段保留了批次的弹性：单个目标失败不会导致其他目标失败。

networkSummary 聚合键是 origin + pathname——重新获取循环（?n=0..4 重复命中同一端点）会折叠成一个带有计数的条目，因此 /api/poll 与 count: 47 一起出现，就是用户最初要求的可操作的“无限重新获取循环”信号。

性能预算：1 个 URL <10 秒，20 个 URL <25 秒。Localhost 死端口在 <2 秒内返回 LocalServerUnreachable，不会消耗工作流执行。

`project`

操作	参数	结果
`get`	`{uuid}`	精选的项目详情
`list`	`{q?, page?, pageSize?}`	分页摘要
`create`	`{name, platform, (teamUuid\|teamName), (repoUuid\|repoName)}`	已创建的项目

团队和仓库通过 uuid 或名称（不区分大小写的精确匹配；如果没有则为 NotFound，如果有多个则为 AmbiguousMatch）来解析。没有 update/delete——从 DebuggAI Web 应用程序重命名或删除项目。

`environment`

操作	参数	结果
`get`	`{uuid, projectUuid?}`	内联凭据的环境（密码从不返回）
`list`	`{projectUuid?, q?, page?, pageSize?}`	分页的环境，每个都带有一个凭据数组
`create`	`{name, url, description?, projectUuid?, credentials?}`	已创建的环境（可选地植入凭据）
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}`	已修补的环境；凭据操作按移除 → 更新 → 添加的顺序运行
`delete`	`{uuid, projectUuid?, confirm?}`	删除环境（级联删除凭据）——需要确认

projectUuid 在省略时会从 git 仓库自动解析。每个凭据的失败会在 credentialWarnings[] 中显示，而不会阻止环境操作。

`test_suite`

操作	参数	结果
`list`	`{projectUuid\|projectName, search?, page?, pageSize?}`	带有状态和通过率的分页测试套件
`create`	`{name, description, projectUuid\|projectName}`	已创建的测试套件
`run`	`{suiteUuid\|(suiteName+project), targetUrl?}`	异步触发所有测试
`results`	`{suiteUuid\|(suiteName+project)}`	测试套件 + 每个测试的结果
`delete`	`{suiteUuid\|(suiteName+project), confirm?}`	软删除——需要确认

`test_case`

操作	参数	结果
`create`	`{name, description, agentTaskDescription, suiteUuid\|(suiteName+project), relativeUrl?, maxSteps?}`	已创建的测试用例（不会自动运行）
`update`	`{testUuid, name?, description?, agentTaskDescription?}`	已修补的测试用例
`delete`	`{testUuid, confirm?}`	软删除——需要确认

`executions`

操作	参数	结果
`get`	`{uuid}`	完整详情（`nodeExecutions` + 状态 + errorInfo）+ 截图/gif 工件
`list`	`{status?, projectUuid?, page?, pageSize?}`	分页摘要

后端的 404 会显示为 isError: true 和 {error: 'NotFound', message, uuid}。凭据始终返回时不带密码。

分页

每个过滤模式响应都是分页的。响应形状：

{
  "filter": { "...echoed query params..." },
  "pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
  "<items>": [ ... ]
}

传递可选的 page（从 1 开始索引，默认 1）和 pageSize（默认 20，最大 200；过大的值会被限制）。任何响应都不会被静默截断。

资源

除了工具之外，服务器还将只读实体公开为 MCP 资源，以便客户端可以浏览它们并将其作为上下文 @ 提及：

URI	内容
`debugg-ai://projects`	所有项目（第一页）
`debugg-ai://environments`	自动检测到的项目的环境
`debugg-ai://executions`	最近的执行（第一页）
`debugg-ai://project/{uuid}`	一个项目，完整详情
`debugg-ai://environment/{uuid}`	一个环境（凭据内联，密码已编辑）
`debugg-ai://execution/{uuid}`	一次执行，完整节点详情 + 工件链接

读取会分派到与 project / environment / executions 工具相同的处理程序，因此数据和身份验证是相同的。资源是附加的——不支持资源的客户端可以继续使用这些工具。

安全不变量

密码是只写的。它们永远不会出现在任何工具的任何响应体中。
隧道 URL（*.ngrok.debugg.ai）会从所有浏览器代理响应中剥离，包括代理编写的文本。
后端的 404 会显示为 isError: true 和 {error: 'NotFound', ...}，而不会作为抛出的异常。
缺少 DEBUGGAI_API_KEY 会在首次调用时显示为结构化的工具错误——服务器仍然会正常注册和列出工具。

迁移到 v3.0.0（基于操作的工具）

v3 将 20 个按动词划分的工具整合为 8 个基于操作的工具。旧工具 → 新的 tool {action}：

已移除	替代
`search_projects`	`project {action:"get"}` / `project {action:"list"}`
`create_project`	`project {action:"create"}`
`update_project`, `delete_project`	已移除——使用 DebuggAI Web 应用程序
`search_environments`	`environment {action:"get"}` / `{action:"list"}`
`create_environment` / `update_environment` / `delete_environment`	`environment {action:"create"\|"update"\|"delete"}`
`create_test_suite` / `search_test_suites` / `run_test_suite` / `get_test_suite_results` / `delete_test_suite`	`test_suite {action:"create"\|"list"\|"run"\|"results"\|"delete"}`
`create_test_case` / `update_test_case` / `delete_test_case`	`test_case {action:"create"\|"update"\|"delete"}`
`search_executions`	`executions {action:"get"\|"list"}`
`trigger_crawl` `headless` 参数	已移除——始终无头运行

delete 操作现在需要确认（提示，或 confirm: true）。客户端在 MCP 重启后会获取新的界面。

从 v1.x 迁移（v2.0.0 中的重大更改）

v2 将 22 个工具的表面缩减为 11 个。旧工具 → 新工具的映射：

已移除	替代
`list_projects`, `get_project`	`search_projects`（uuid 模式 vs 过滤模式）
`list_environments`, `get_environment`	`search_environments`
`list_credentials`, `get_credential`	`search_environments`——每个环境内联凭据
`create_credential`	`create_environment({credentials: [...]})` 植入，或 `update_environment({addCredentials: [...]})`
`update_credential`	`update_environment({updateCredentials: [{uuid, ...patch}]})`
`delete_credential`	`update_environment({removeCredentialIds: [uuid]})`
`list_teams`, `list_repos`	`create_project({teamName, repoName})`——带有歧义处理的名称解析
`list_executions`, `get_execution`	`search_executions`
`cancel_execution`	已移除——后端关闭是自动的

响应形状更改：列表响应上的裸 count 字段已移除——使用 pageInfo.totalCount。

配置

环境变量	必填	用途
`DEBUGGAI_API_KEY`	是	后端 API 密钥。别名：`DEBUGGAI_API_TOKEN`、`DEBUGGAI_JWT_TOKEN`。
`DEBUGGAI_API_URL`	否	后端基础 URL。默认为 `https://api.debugg.ai`。
`DEBUGGAI_TOKEN_TYPE`	否	`token`（默认）或 `bearer`。
`LOG_LEVEL`	否	`error` / `warn` / `info`（默认）/ `debug`。
`POSTHOG_API_KEY`	否	覆盖嵌入的遥测项目密钥（例如私有分支）。
`DEBUGGAI_TELEMETRY_DISABLED`	否	设置为 `1` / `true` / `yes` / `on` 以完全禁用遥测。

DEBUGGAI_API_KEY=your_api_key

远程 / HTTP 传输（可选）

默认情况下，服务器使用 stdio（本地 npx）。它也可以作为托管的、多用户远程 MCP 运行，通过 无状态可流式 HTTP + OAuth：

DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest

这是一个 OAuth 资源服务器：每个 POST /mcp 都需要 Authorization: Bearer <token>；缺失/无效的令牌会收到一个 401，并附带一个指向 RFC 9728 元数据的 WWW-Authenticate，客户端会根据所公布的授权服务器运行 OAuth 流程。该 Bearer 令牌是请求作用域级别的 — api.debugg.ai 会对其进行验证。

端点	用途
`POST /mcp`	MCP Streamable HTTP（Bearer 保护）
`GET /.well-known/oauth-protected-resource`	RFC 9728 元数据（授权服务器发现）
`GET /health`	负载均衡器 / ECS 健康检查

环境变量	默认值	用途
`DEBUGGAI_MCP_TRANSPORT`	`stdio`	设置为 `http` 以用于远程传输
`PORT`	`3000`	HTTP 监听端口
`DEBUGGAI_MCP_PUBLIC_URL`	`https://mcp.debugg.ai`	此服务器的公共资源 URL（RFC 9728 `resource`）
`DEBUGGAI_OAUTH_ISSUER`	`https://auth.debugg.ai`	向客户端公布的授权服务器
`DEBUGGAI_TOKEN_TYPE`	`token`	设置为 `bearer`，以便 OAuth 令牌作为 `Authorization: Bearer` 转发

stdio 安装不需要上述任何配置。

遥测

该 MCP 服务器默认启用遥测 — 内嵌了一个只写的 PostHog 项目密钥（phc_*），以便团队能够观察整个安装基数的缓存命中率、轮询节奏、隧道可靠性以及其他运维指标。捕获的事件：

事件	触发时机
`tool.executed` / `tool.failed`	每次工具调用
`workflow.executed`	每次浏览器代理执行（携带 `pollCount`、`durationMs`、`finalIntervalMs`）
`tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped`	每次隧道生命周期事件
`template.lookup` / `project.lookup`	缓存命中/未命中，冷调用时携带 `durationMs`

隐私立场：

唯一标识符是 SHA-256(api_key).slice(0, 16) — 绝不是原始密钥，不含个人身份信息。
phc_* 密钥按 PostHog 惯例是只写的；可以安全地嵌入源代码。
设置 DEBUGGAI_TELEMETRY_DISABLED=1 即可完全退出（解析为一个空操作提供程序；不会有事件离开进程）。

启动时会记录当前模式：

Telemetry enabled (PostHog, DebuggAI default project). Set DEBUGGAI_TELEMETRY_DISABLED=1 to opt out.
Telemetry enabled (PostHog, custom POSTHOG_API_KEY)
Telemetry disabled (DEBUGGAI_TELEMETRY_DISABLED is set)

本地开发

npm install
npm run build
npm run test:e2e        # real end-to-end evals against the backend

评估套件会将构建好的 MCP 服务器作为子进程启动，针对真实后端执行每个工具，并将每个流程的产物写入 scripts/evals/artifacts/<timestamp>/。具体场景请参阅 scripts/evals/flows/。

MCP 注册：`debugg-ai-local` 与 `debugg-ai`

此仓库附带一个 .mcp.json，它会注册一个名为 debugg-ai-local 的项目作用域服务器，指向 node dist/index.js — 即刚构建的本地代码。它仅在 Claude Code 的工作目录为此仓库时才会激活。

你的其他项目应使用用户作用域的 debugg-ai 注册，该注册会从已发布的 npm 包中拉取：

npm run mcp:global      # registers debugg-ai in ~/.claude.json to npx -y @debugg-ai/debugg-ai-mcp

在此处编辑代码后，运行 npm run mcp:local（它仅执行重新构建），这样下次调用 debugg-ai-local 时就会包含你的更改。

链接

仪表盘 · 文档 · 问题 · Discord

Debugg AI

你可以用 Debugg AI MCP 做什么？

文档

Debugg AI — MCP 服务器

安装

工具

浏览器

check_app_in_browser

trigger_crawl

probe_page

project

environment

test_suite

test_case

executions

分页

资源