调试AI——MCP服务器
通过AI驱动的浏览器测试 模型上下文协议。将其指向任何URL（或localhost）并描述要测试的内容——AI代理浏览您的应用程序并返回通过/失败的屏幕截图。
设置
需要Node.js 20.20.0或更高版本 （传递要求来自 posthog-node@^5.26.0).
在获取API密钥 调试.ai，然后添加到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工具
服务器暴露 12 工具分为浏览器（3）、搜索（3），项目（3）和环境（3）。标题工具是 check_app_in_browser （完全AI代理）和 probe_page （轻量级无LLM页面探测器）；其余的则通过统一的方式管理项目、环境及其凭据和执行历史 search_* +CRUD模式。
浏览器
check_app_in_browser
对您的应用程序运行AI浏览器代理。代理通过屏幕截图进行导航、交互和报告。本地主机URL通过ngrok自动隧道传输。
| 参数 | 类型 | 说明 |
|---|---|---|
description | 字符串 必需的 | 测试内容（自然语言） |
url | 字符串 必需的 | 目标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 屏幕截图旁边的块——为捕获的内容预处理S3 URL HTTP存档（HAR） （完整网络跟踪）和 控制台日志 （每条JS控制台消息）。使用它们来检测通过类型检查和单元测试的重蚀刻循环、水合错误和其他运行时问题：
"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——通过以下方式重新调用父执行 search_executions 更新。 harStatus / consoleLogStatus 消除歧义 'downloaded' （URL可获取）， 'not_available' （页面未显示任何内容）， 'failed' （捕获中断）。在新运行时，URL通常是 null 因为capture在代理完成后异步上传——poll search_executions 与返回 executionId 直到状态达到 'downloaded'.授权/Cookie/ token/secret/api_key 在持久化工件之前，服务器端会清除标头。
trigger_crawl
启动服务器端浏览器代理爬网以填充项目的知识图。本地主机URL自动隧道。退货 {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} 和 knowledgeGraph.imported === true 成功摄入。这 browserSession 块（HAR+控制台日志URL，与上述形状相同）也存在于已完成的爬网中。
probe_page
轻量级的无LLM批处理页面探测。 传递1-20个网址；每个导航、等待加载并返回渲染状态——屏幕截图+页面元数据+结构化控制台错误+网络摘要。没有代理循环，没有LLM成本，没有场景断言。将其用于“我刚刚中断/设置了吗？”、重构后的多路径冒烟、每个PR的CI扫描以及快速检查 check_app_in_browser60-150年代的特工循环太过分了。
| 参数 | 类型 | 说明 |
|---|---|---|
targets | 阵列 必需的 | 1-20个条目： [{url, waitForSelector?, waitForLoadState?, timeoutMs?}] |
targets[].url | 字符串 必需的 | 公共URL或本地主机（自动隧道） |
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\": [ ... ] }
通行证可选 `page` （1-索引，默认1）和 `pageSize` （默认值为20，最大值为200；过大的值会被限制）。任何回应都不会被默默地截断。
### 安全不变量
- 密码只能写入。它们从未出现在任何工具的任何响应体中。
- 隧道URL(`*.ngrok.debugg.ai`)从所有浏览器代理响应中删除，包括代理编写的文本。
- 距离后端表面404秒 `isError: true` 和 `{error: 'NotFound', ...}`，从不作为抛出的异常。
- 缺失 `DEBUGGAI_API_KEY` 第一次调用时出现结构化工具错误——服务器仍然正常注册和列出工具。
## 从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` |yes|后端API密钥。别名： `DEBUGGAI_API_TOKEN`, `DEBUGGAI_JWT_TOKEN`. |
| `DEBUGGAI_API_URL` |no |后端基本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
## 遥测
MCP服务器默认启用遥测功能，这是一个嵌入式的只写PostHog项目密钥(`phc_*`)因此，团队可以观察整个安装库的缓存命中率、轮询节奏、隧道可靠性和其他操作指标。捕获的事件：
|事件|时间|
|---|---|
| `tool.executed` / `tool.failed` |每次工具调用|
| `workflow.executed` |每次浏览器代理执行（携带 `pollCount`, `durationMs`, `finalIntervalMs`) |
| `tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped` |每个隧道生命周期事件|
| `template.lookup` / `project.lookup` |缓存命中率/未命中率 `durationMs` 冷电话|
隐私姿态：
- 唯一ID是 `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
eval套件将构建的MCP服务器作为子流程生成，在真实的后端上使用每个工具，并将每个流的工件写入 `scripts/evals/artifacts//`。参见 `scripts/evals/flows/` 对于各个场景。
### MCP注册： `debugg-ai-local` 对比 `debugg-ai`
该回购提供 `.mcp.json` 注册a **项目范围** 服务器名称 `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` 接收您的更改。
## 链接
______________________________________________________________________
Apache-2.0许可证©2025 DebuggAI