@debugg-ai/debugg-ai-mcp 2.4.0 → 2.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -55,9 +55,25 @@ Runs an AI browser agent against your app. The agent navigates, interacts, and r
|
|
|
55
55
|
|
|
56
56
|
One focused check per call. The agent has a ~25-step internal budget; split broader suites across multiple calls.
|
|
57
57
|
|
|
58
|
+
Every successful run returns a `browserSession` block alongside the screenshot — presigned S3 URLs for the captured **HAR** (full network trace) and **console log** (every JS console message). Use them to detect refetch loops, hydration errors, and other runtime issues that pass type-checks and unit tests:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
"browserSession": {
|
|
62
|
+
"harUrl": "https://...session_18139.har?X-Amz-...",
|
|
63
|
+
"consoleLogUrl": "https://...session_18139_console.json?X-Amz-...",
|
|
64
|
+
"recordingUrl": "https://...session_18139_recording.webm?X-Amz-...",
|
|
65
|
+
"harStatus": "downloaded",
|
|
66
|
+
"consoleLogStatus": "downloaded",
|
|
67
|
+
"harRedactionStatus": "redacted",
|
|
68
|
+
"consoleLogRedactionStatus": "redacted"
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
URLs are short-lived presigned S3 — refetch the parent execution via `search_executions` to renew. `harStatus` / `consoleLogStatus` disambiguate `'downloaded'` (URL fetchable), `'not_available'` (page emitted nothing), `'failed'` (capture broke). On a fresh run the URLs are commonly `null` because capture uploads async after the agent finishes — poll `search_executions` with the returned `executionId` until status reaches `'downloaded'`. Authorization / Cookie / `token`/`secret`/`api_key` headers are scrubbed server-side before the artifacts are persisted.
|
|
73
|
+
|
|
58
74
|
#### `trigger_crawl`
|
|
59
75
|
|
|
60
|
-
Fires a server-side browser-agent crawl to populate the project's knowledge graph. Localhost URLs tunnel automatically. Returns `{executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?}` with `knowledgeGraph.imported === true` on successful ingestion.
|
|
76
|
+
Fires a server-side browser-agent crawl to populate the project's knowledge graph. Localhost URLs tunnel automatically. Returns `{executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?}` with `knowledgeGraph.imported === true` on successful ingestion. The `browserSession` block (HAR + console-log URLs, same shape as above) is also present on completed crawls.
|
|
61
77
|
|
|
62
78
|
### Search (dual-mode: uuid detail OR filtered list)
|
|
63
79
|
|
|
@@ -128,10 +144,42 @@ Response-shape changes: the bare `count` field on list responses is gone — use
|
|
|
128
144
|
|
|
129
145
|
## Configuration
|
|
130
146
|
|
|
147
|
+
| Env var | Required | Purpose |
|
|
148
|
+
|---|---|---|
|
|
149
|
+
| `DEBUGGAI_API_KEY` | yes | Backend API key. Aliases: `DEBUGGAI_API_TOKEN`, `DEBUGGAI_JWT_TOKEN`. |
|
|
150
|
+
| `DEBUGGAI_API_URL` | no | Backend base URL. Defaults to `https://api.debugg.ai`. |
|
|
151
|
+
| `DEBUGGAI_TOKEN_TYPE` | no | `token` (default) or `bearer`. |
|
|
152
|
+
| `LOG_LEVEL` | no | `error` / `warn` / `info` (default) / `debug`. |
|
|
153
|
+
| `POSTHOG_API_KEY` | no | Override the embedded telemetry project key (e.g. private fork). |
|
|
154
|
+
| `DEBUGGAI_TELEMETRY_DISABLED` | no | Set to `1` / `true` / `yes` / `on` to disable telemetry entirely. |
|
|
155
|
+
|
|
131
156
|
```bash
|
|
132
157
|
DEBUGGAI_API_KEY=your_api_key
|
|
133
158
|
```
|
|
134
159
|
|
|
160
|
+
## Telemetry
|
|
161
|
+
|
|
162
|
+
The MCP server ships with telemetry enabled by default — an embedded write-only PostHog project key (`phc_*`) so the team can observe cache hit rates, poll cadence, tunnel reliability, and other operational metrics across the install base. Captured events:
|
|
163
|
+
|
|
164
|
+
| Event | When |
|
|
165
|
+
|---|---|
|
|
166
|
+
| `tool.executed` / `tool.failed` | Per tool call |
|
|
167
|
+
| `workflow.executed` | Per browser-agent execution (carries `pollCount`, `durationMs`, `finalIntervalMs`) |
|
|
168
|
+
| `tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped` | Per tunnel lifecycle event |
|
|
169
|
+
| `template.lookup` / `project.lookup` | Cache hit/miss with `durationMs` on cold-call |
|
|
170
|
+
|
|
171
|
+
Privacy posture:
|
|
172
|
+
- The distinct ID is `SHA-256(api_key).slice(0, 16)` — never the raw key, no PII.
|
|
173
|
+
- `phc_*` keys are write-only by PostHog convention; safe to embed in source.
|
|
174
|
+
- Set `DEBUGGAI_TELEMETRY_DISABLED=1` to opt out entirely (resolves to a no-op provider; no events leave the process).
|
|
175
|
+
|
|
176
|
+
The active mode is logged at boot:
|
|
177
|
+
```
|
|
178
|
+
Telemetry enabled (PostHog, DebuggAI default project). Set DEBUGGAI_TELEMETRY_DISABLED=1 to opt out.
|
|
179
|
+
Telemetry enabled (PostHog, custom POSTHOG_API_KEY)
|
|
180
|
+
Telemetry disabled (DEBUGGAI_TELEMETRY_DISABLED is set)
|
|
181
|
+
```
|
|
182
|
+
|
|
135
183
|
## Local Development
|
|
136
184
|
|
|
137
185
|
```bash
|