@debugg-ai/debugg-ai-mcp 1.0.64 → 1.0.66

package/CHANGELOG.md

@@ -0,0 +1,184 @@
+# Changelog
+
+All notable changes to the DebuggAI MCP project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed — tunnel provisioning flakiness surfaces as user-facing errors
+
+- `check_app_in_browser` / `trigger_crawl` now automatically retry transient tunnel-provision failures (5xx, 408, 429, network errors like ECONNRESET) with exponential backoff (500ms → 1500ms → 3000ms, 3 attempts). Previously a single ngrok/backend blip forced the caller to manually retry the tool call. Bead `7nx`.
+- Tunnel-provision error messages now carry structured diagnostic context — HTTP status, ngrok error code, backend `x-request-id`, retryable flag — so users have something actionable to file bug reports against instead of opaque "Tunnel setup failed". Bead `5wz`.
+- 4xx auth/quota errors (401/403/404) fail fast without retry to avoid loops against a bad API key.
+- New posthog telemetry event `tunnel.provision_retry` fires per retry attempt with outcome, status, and diagnostic fields so flaky provision rates become measurable.
+
+## [1.0.64] - 2026-04-23
+
+> **⚠️ Semver violation — this is functionally a major release shipped as a patch.**
+> The surface collapse below removes 14 tools. Callers pinned to `^1.0.63` will silently
+> receive a breaking API on their next install. A republish as `2.0.0` (or a `2.0.0`
+> bump with `1.0.64` deprecated) is recommended to restore semver discipline.
+
+This is a **breaking release**. The MCP surface collapsed from 22 tools to 11 through a uniform `search_*` pattern plus credential-management consolidation into the environment tools. The full old→new mapping is below.
+
+### ⚠️ BREAKING CHANGES — 14 tools removed, replaced by 11-tool surface
+
+| Removed tool | Replacement |
+|---|---|
+| `list_projects` | `search_projects({q?, page?, pageSize?})` (filter mode) |
+| `get_project` | `search_projects({uuid})` (uuid mode — returns the curated detail shape) |
+| `list_environments` | `search_environments({projectUuid?, q?, page?, pageSize?})` — credentials inlined per env |
+| `get_environment` | `search_environments({uuid, projectUuid})` |
+| `list_credentials` | `search_environments(...)` — credentials are inlined on each returned env (never include password) |
+| `get_credential` | `search_environments({uuid, projectUuid})` — pull from the env's `credentials[]` |
+| `create_credential` | `create_environment({name, url, credentials: [...]})` (seed on env create), or `update_environment({uuid, addCredentials: [...]})` |
+| `update_credential` | `update_environment({uuid, updateCredentials: [{uuid, ...patch}]})` |
+| `delete_credential` | `update_environment({uuid, removeCredentialIds: [uuid]})` |
+| `list_teams` | `create_project({teamName, ...})` — backend name-resolved with exact-match + ambiguity handling |
+| `list_repos` | `create_project({repoName, ...})` — same pattern |
+| `list_executions` | `search_executions({status?, projectUuid?, page?, pageSize?})` |
+| `get_execution` | `search_executions({uuid})` — full detail with `nodeExecutions` + state |
+| `cancel_execution` | Dropped — backend spin-down is now automatic; no client action needed |
+
+All `search_*` tools use a dual-mode signature: pass `{uuid}` for a single-record detail response, or pass filter params for a paginated summary list. 404 from the backend surfaces as `isError: true` with `{error: 'NotFound', message, uuid}`.
+
+Credential mutations on `update_environment` execute as `remove → update → add` in a single call, so a freed label can be re-bound in one request. Per-cred failures surface in `credentialWarnings[]` without blocking the env update.
+
+### Added
+
+- **`trigger_crawl` tool**: server-side browser-agent crawl to populate the project's knowledge graph. Returns `{executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?}` with `knowledgeGraph.imported` = true on successful KG ingestion. Supports localhost via automatic ngrok tunneling with per-process reuse.
+- **`create_project` name-based resolution**: pass `teamName` instead of `teamUuid`, or `repoName` instead of `repoUuid`. Backend-side search with case-insensitive exact match. Returns `AmbiguousMatch` with candidates if multiple hits, `NotFound` if none.
+- **`create_environment` credential seeding**: pass `credentials: [{label, username, password, role?}]` to create creds atomically with the env.
+- **`update_environment` credential sub-actions**: `addCredentials[]`, `updateCredentials[]`, `removeCredentialIds[]` in one call.
+- **`engines.node: ">=20.20.0"`** in `package.json`. Driven by `posthog-node@^5.26.0` requiring Node 20.20+.
+- **Boot-smoke CI** (`.github/workflows/boot-smoke.yml`): matrix `{ubuntu, macos} × {Node 20, 22}` verifies the MCP server boots + completes `tools/list` with published-style spawn.
+- **Eval runner tag filtering**: `--tag=<name>`, `--skip-tag=<name>`, `--flow=<csv>`; `--list` prints flows + tags. `--tag=fast` runs 12 non-browser flows in ~40s; `--tag=browser` runs heavy flows.
+- **27 eval flows total** (up from 16 in prior unreleased work). New flows since the last published version: response-structure (20), tunnel reuse (21), long-running check (22), crawl triggers public + localhost + with-project (23/24/26), published-boot-smoke (25), localhost deep-path (27).
+- **Response sanitization**: `check_app_in_browser` strips ngrok tunnel URLs from the full response including agent-authored `actionTrace[*].intent`.
+
+### Changed
+
+- **Deferred API-key validation**: missing `DEBUGGAI_API_KEY` no longer crashes the subprocess at boot (the bug that surfaced in Claude Code as "Failed to reconnect to debugg-ai"). The server starts, `tools/list` succeeds, and the error surfaces only when a tool is actually invoked — as a structured `isError: true` response pointing the caller at the missing env var.
+- **Boot-time behavior**: `index.ts` no longer calls `resolveProjectContext()` at startup. Project context resolves lazily on first tool call that needs it.
+- **`services/projectContext.ts`**: promise-dedup pattern replaces the failure-caching singleton. Concurrent callers share one in-flight promise; results cached on success only, so transient network errors don't permanently disable context resolution.
+- **Pagination mandatory on every list response**: `search_projects` / `search_environments` / `search_executions` accept optional `page` (1-indexed) and `pageSize` (default 20, max 200, oversized clamped). Response shape: `{filter, pageInfo: {page, pageSize, totalCount, totalPages, hasMore}, <items>}`.
+- **Axios error handling**: handlers map `err.statusCode` (surfaced by the transport's response interceptor) to tool-level `NotFound` errors instead of checking `err.response?.status` which the interceptor strips.
+
+### Fixed
+
+- **Progress-notification race** (bead `0bq`) in both `testPageChangesHandler` and `triggerCrawlHandler`: a progress callback firing after the handler resolved could tear down the stdio transport. Circuit breaker suppresses subsequent callbacks after the first throw; terminal-status detection emits the final `progress === total` notification inside `onUpdate` before the poll loop exits.
+- **"Failed to reconnect to debugg-ai" UX** (bead `cma`): missing API key now surfaces as a per-tool-call error instead of a silent subprocess exit at boot. MCP clients see the server register normally and get a readable error only when a tool is actually invoked.
+- **Credential role filter** (bead `hpo`): backend `?role=` filter on credentials list was returning all creds regardless. MCP now applies client-side role filtering as defense-in-depth.
+
+### Security invariants
+
+- Passwords are write-only. No response body from any tool contains a password (verified by unit tests + eval flows 06/10/12/15).
+- Tunnel URLs (`*.ngrok.debugg.ai`) are stripped from all `check_app_in_browser` responses including agent-authored text (verified by flow 05).
+- 404s from the backend surface as `isError: true` with structured `{error: 'NotFound', ...}`, never as thrown exceptions.
+
+### Tool count
+
+The server registers **11** tools (was 22 pre-collapse, 18 in the previous unreleased snapshot). Verified by eval flow `01-protocol.mjs` which locks the roster.
+
+## [1.0.15] - 2025-08-18
+
+### Added
+- **Live Session Monitoring Tools**: Added 5 new MCP tools for real-time browser session monitoring
+  - `debugg_ai_start_live_session`: Launch live remote browser sessions with real-time monitoring
+  - `debugg_ai_stop_live_session`: Stop active live sessions
+  - `debugg_ai_get_live_session_status`: Monitor session status and health
+  - `debugg_ai_get_live_session_logs`: Retrieve console logs and network requests from live sessions
+  - `debugg_ai_get_live_session_screenshot`: Capture screenshots from active sessions
+- **Enhanced Tunnel Management**: Complete rewrite of tunnel infrastructure with improved ngrok integration
+  - New `TunnelManager` service for high-level tunnel abstraction
+  - Automatic localhost URL detection and tunnel creation
+  - Better error handling and connection stability
+  - Integrated tunnel support in live session handlers
+- **Browser Sessions Service**: New dedicated service for managing browser automation sessions
+- **Comprehensive Test Infrastructure**: Added extensive test suite covering unit, integration, and end-to-end scenarios
+  - Handler tests for E2E suites and live sessions
+  - Backend services integration tests
+  - Network and MCP tools validation tests
+  - Mock infrastructure for reliable testing
+- **Enhanced Project Analysis**: New utilities for analyzing codebases and extracting context
+- **Improved Error Handling**: Centralized error management with structured error types
+- **URL Parser Utilities**: Robust URL parsing and localhost detection capabilities
+- **Configuration Management**: Centralized configuration system with environment-based settings
+- **API Specification**: Complete OpenAPI specification for backend integration
+- **GitHub Actions Workflows**: Automated publishing, version bumping, and validation workflows
+
+### Changed
+- **Major Architecture Refactoring**: Reorganized services, handlers, and utilities into cleaner modular structure
+- **Moved Tunnel Services**: Relocated tunnel management from `tunnels/` to `services/ngrok/` for better organization
+- **Enhanced E2E Runner**: Improved test execution with better progress tracking and error handling
+- **Updated Package Dependencies**: Upgraded to latest versions of core dependencies including MCP SDK
+- **Improved Documentation**: Updated README with comprehensive setup and usage instructions
+- **Enhanced Type Definitions**: Expanded type system with better validation schemas
+
+### Fixed
+- **API Endpoint Updates**: Resolved compatibility issues with backend API changes
+- **Image Support Improvements**: Enhanced handling of screenshots and visual test artifacts
+- **Tunnel Connection Stability**: Fixed issues with ngrok tunnel reliability and reconnection
+- **ES Module Compatibility**: Resolved module resolution issues for better Node.js compatibility
+
+### Security
+- **License Addition**: Added Apache 2.0 license for proper open source compliance
+- **Environment Variable Validation**: Enhanced validation of sensitive configuration data
+
+## [1.0.14] - 2025-06-09
+
+### Added
+- Final screen shot included.
+
+## [1.0.12] - 2025-06-02
+
+### Added
+- Readme docs issue
+
+## [1.0.11] - 2025-06-02
+
+### Added
+- New readme with instructions on install, usage, etc.
+
+## [1.0.10] - 2025-05-29
+
+### Fixed
+- Most MCP clients still don't support images. removed that as a response.
+
+
+## [1.0.7] - 2025-05-29
+
+### Fixed
+- Fixed tunneling issues
+- Remove notifications when a token is not provided in the original request
+
+## [1.0.2] - 2025-05-28
+
+### Fixed
+- Fixed ES module path resolution issues
+- Added proper shebang line to executable files
+- Ensured executable permissions are set during build
+
+### Added
+- Docker container support
+- Improved error handling for E2E test runs
+
+## [1.0.1] - 2025-05-28
+
+### Fixed
+- Fixed TypeScript configuration to target ES2022
+- Resolved dependency issues with Zod library
+
+### Added
+- Initial implementation of E2E test runner
+- Integration with DebuggAI server client
+
+## [1.0.0] - 2025-05-28
+
+### Added
+- Initial release of DebuggAI MCP
+- Support for running UI tests via MCP protocol
+- Integration with ngrok for tunnel creation
+- Basic test reporting functionality 

package/README.md

@@ -8,6 +8,8 @@ AI-powered browser testing via the [Model Context Protocol](https://modelcontext
 
 ## Setup
 
+**Requires Node.js 20.20.0 or later** (transitive requirement from `posthog-node@^5.26.0`).
+
 Get an API key at [debugg.ai](https://debugg.ai), then add to your MCP client config:
 
 ```json
@@ -32,16 +34,18 @@ docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-m
 
 ## Tools
 
-The server exposes **21** tools. The headline one is `check_app_in_browser`; the rest manage projects, environments, credentials, workflow execution history, and the teams/repos needed to create new projects.
+The server exposes **11** tools grouped into Browser (2), Search (3), Projects (3), and Environments (3). The headline tool is `check_app_in_browser`; the rest manage projects, environments + their credentials, and execution history through a uniform `search_*` + CRUD pattern.
+
+### Browser
 
-### `check_app_in_browser`
+#### `check_app_in_browser`
 
-Runs an AI browser agent against your app. The agent navigates, interacts, and reports back with screenshots.
+Runs an AI browser agent against your app. The agent navigates, interacts, and reports back with screenshots. Localhost URLs are auto-tunneled via ngrok.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `description` | string **required** | What to test (natural language) |
-| `url` | string **required** | Target URL — a localhost URL (`http://localhost:3000`) is auto-tunneled via ngrok |
+| `url` | string **required** | Target URL — `http://localhost:3000` is auto-tunneled |
 | `environmentId` | string | UUID of a specific environment |
 | `credentialId` | string | UUID of a specific credential |
 | `credentialRole` | string | Pick a credential by role (e.g. `admin`, `guest`) |
@@ -49,54 +53,43 @@ Runs an AI browser agent against your app. The agent navigates, interacts, and r
 | `password` | string | Password for login (ephemeral — not persisted) |
 | `repoName` | string | Override auto-detected git repo name (e.g. `my-org/my-repo`) |
 
-### Project management
+One focused check per call. The agent has a ~25-step internal budget; split broader suites across multiple calls.
 
-| Tool | Purpose |
-|------|---------|
-| `list_projects` | List projects accessible to your API key. Optional `q` for name/repo search. |
-| `get_project` | Fetch a project by `uuid`. Simplified shape (no team/runner internals). |
-| `create_project` | Create a new project. Needs `name`, `platform` (e.g. `web`), `teamUuid` (from `list_teams`), and `repoUuid` (from `list_repos`). |
-| `update_project` | PATCH a project's `name` or `description`. |
-| `delete_project` | Destructive delete. Cascades envs, creds, and history. |
+#### `trigger_crawl`
 
-### Teams and repos (prerequisites for `create_project`)
+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.
 
-| Tool | Purpose |
-|------|---------|
-| `list_teams` | Paginated list of teams accessible to the API key; optional `q` for search. |
-| `list_repos` | Paginated list of GitHub-linked repos; optional `q` for search. Use repos with `isGithubAuthorized: true` when creating a project. |
+### Search (dual-mode: uuid detail OR filtered list)
 
-### Environment management (scoped to a project)
+Each `search_*` tool has two modes. Pass `{uuid}` for a single-record detail response. Pass filter params for a paginated summary list. 404 from the backend surfaces as `isError: true` with `{error: 'NotFound', message, uuid}`.
 
-| Tool | Purpose |
-|------|---------|
-| `list_environments` | List envs for a project. Optional `q`, `projectUuid`. |
-| `create_environment` | Create a new env. Requires `name` + `url`. |
-| `get_environment` | Fetch an env by `uuid`. |
-| `update_environment` | PATCH `name` / `url` / `description`. |
-| `delete_environment` | Destructive delete. |
+| Tool | UUID mode | Filter mode |
+|------|-----------|-------------|
+| `search_projects` | `{uuid}` → curated project detail | `{q?, page?, pageSize?}` → paginated summaries |
+| `search_environments` | `{uuid, projectUuid}` → env with credentials inlined | `{projectUuid?, q?, page?, pageSize?}` → paginated envs, each with credentials array |
+| `search_executions` | `{uuid}` → full detail with `nodeExecutions` + state | `{status?, projectUuid?, page?, pageSize?}` → paginated summaries |
+
+`projectUuid` is optional on `search_environments` — if omitted, it auto-resolves from the git repo. Credentials are **always** returned without passwords.
 
-### Credential management (scoped to an environment)
+### Projects
 
 | Tool | Purpose |
 |------|---------|
-| `list_credentials` | List creds. Optional `environmentId`, `q`, `role` (server-side filter). **Never returns passwords.** |
-| `create_credential` | Create a cred. Requires `environmentId`, `label`, `username`, `password`; optional `role`. |
-| `get_credential` | Fetch by `uuid` + `environmentId`. |
-| `update_credential` | Partial PATCH. Pass `password` to rotate — it is never echoed back. |
-| `delete_credential` | Destructive delete. |
+| `create_project` | Requires `name` + `platform`. Team and repo resolve by **either** uuid **or** name: pass `teamUuid` OR `teamName`, and `repoUuid` OR `repoName`. Name resolution is case-insensitive exact match; `NotFound` if none, `AmbiguousMatch` with candidates if multiple. |
+| `update_project` | PATCH `name`, `description`. |
+| `delete_project` | Destructive — cascades environments, credentials, and execution history. |
 
-### Workflow execution history
+### Environments (credential sub-actions folded in)
 
 | Tool | Purpose |
 |------|---------|
-| `list_executions` | Paginated history. Optional `status`, `limit`. |
-| `get_execution` | Full detail for a single execution including node-level state. |
-| `cancel_execution` | Cancel an in-flight execution. |
+| `create_environment` | Requires `name` + `url`. Optional `credentials: [{label, username, password, role?}]` seeds credentials in the same call. Per-cred failures surface in `credentialWarnings[]` without blocking env creation. |
+| `update_environment` | PATCH env fields (`name`, `url`, `description`) plus credential sub-actions in one call: `addCredentials[]`, `updateCredentials: [{uuid, ...patch}]`, `removeCredentialIds: [uuid]`. Execution order: **remove → update → add** (freed labels can be re-added in one request). |
+| `delete_environment` | Destructive — cascades credentials. |
 
 ### Pagination
 
-Every `list_*` tool is paginated by default. Response shape:
+Every filter-mode response is paginated. Response shape:
 
 ```json
 {
@@ -106,13 +99,32 @@ Every `list_*` tool is paginated by default. Response shape:
 }
 ```
 
-Pass optional `page` (1-indexed, default 1) and `pageSize` (default 20, max 200; oversized values are clamped) to any list tool. No tool ever silently truncates results.
+Pass optional `page` (1-indexed, default 1) and `pageSize` (default 20, max 200; oversized values are clamped). No response is ever silently truncated.
 
 ### Security invariants
 
 - Passwords are write-only. They never appear in any response body from any tool.
 - Tunnel URLs (`*.ngrok.debugg.ai`) are stripped from all browser-agent responses, including agent-authored text.
 - 404s from the backend surface as `isError: true` with `{error: 'NotFound', ...}`, never as thrown exceptions.
+- Missing `DEBUGGAI_API_KEY` surfaces as a structured tool error on first invocation — the server still registers and lists tools normally.
+
+## Migration from v1.x (breaking change in v2.0.0)
+
+v2 collapsed a 22-tool surface to 11. Old-tool → new-tool mapping:
+
+| Removed | Replacement |
+|---------|-------------|
+| `list_projects`, `get_project` | `search_projects` (uuid mode vs filter mode) |
+| `list_environments`, `get_environment` | `search_environments` |
+| `list_credentials`, `get_credential` | `search_environments` — credentials inline on each env |
+| `create_credential` | `create_environment({credentials: [...]})` seed, or `update_environment({addCredentials: [...]})` |
+| `update_credential` | `update_environment({updateCredentials: [{uuid, ...patch}]})` |
+| `delete_credential` | `update_environment({removeCredentialIds: [uuid]})` |
+| `list_teams`, `list_repos` | `create_project({teamName, repoName})` — name resolution with ambiguity handling |
+| `list_executions`, `get_execution` | `search_executions` |
+| `cancel_execution` | **Dropped** — backend spin-down is automatic |
+
+Response-shape changes: the bare `count` field on list responses is gone — use `pageInfo.totalCount`.
 
 ## Configuration
 

package/dist/handlers/createEnvironmentHandler.js

@@ -20,7 +20,7 @@ export async function createEnvironmentHandler(input, _context) {
             if (!repoName) {
                 const payload = {
                     error: 'NoProjectResolved',
-                    message: 'No git repo detected and no projectUuid provided. Pass projectUuid (get it from list_projects) or invoke from a directory with a git origin.',
+                    message: 'No git repo detected and no projectUuid provided. Pass projectUuid (get it from search_projects) or invoke from a directory with a git origin.',
                 };
                 return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
             }

package/dist/handlers/testPageChangesHandler.js

@@ -8,6 +8,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
 import { DebuggAIServerClient } from '../services/index.js';
+import { TunnelProvisionError } from '../services/tunnels.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { detectRepoName } from '../utils/gitContext.js';
 const logger = new Logger({ module: 'testPageChangesHandler' });
@@ -96,14 +97,15 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             else {
                 let tunnel;
                 try {
-                    tunnel = await client.tunnels.provision();
+                    tunnel = await client.tunnels.provisionWithRetry();
                 }
                 catch (provisionError) {
                     const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
+                    const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
                     throw new Error(`Failed to provision tunnel for ${ctx.originalUrl}. ` +
                         `The remote browser needs a secure tunnel to reach your local dev server. ` +
                         `Make sure your dev server is running on the specified port and try again. ` +
-                        `(Detail: ${msg})`);
+                        `(Detail: ${msg})${diag}`);
                 }
                 keyId = tunnel.keyId;
                 try {

package/dist/handlers/triggerCrawlHandler.js

@@ -14,6 +14,7 @@ import { config } from '../config/index.js';
 import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
+import { TunnelProvisionError } from '../services/tunnels.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 const logger = new Logger({ module: 'triggerCrawlHandler' });
 const TEMPLATE_KEYWORD = 'raw crawl';
@@ -61,13 +62,14 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
             else {
                 let tunnel;
                 try {
-                    tunnel = await client.tunnels.provision();
+                    tunnel = await client.tunnels.provisionWithRetry();
                 }
                 catch (provisionError) {
                     const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
+                    const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
                     throw new Error(`Failed to provision tunnel for ${ctx.originalUrl}. ` +
                         `The remote browser needs a secure tunnel to reach your local dev server. ` +
-                        `(Detail: ${msg})`);
+                        `(Detail: ${msg})${diag}`);
                 }
                 keyId = tunnel.keyId;
                 ctx = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));

package/dist/services/index.js

@@ -191,7 +191,7 @@ export class DebuggAIServerClient {
      * List environments for a project. Paginated.
      * Optional q filters by name via backend ?search=.
      * The bare-array variant (no pagination) is still used internally by
-     * list_credentials when iterating across all envs.
+     * search_environments when iterating across all envs to inline credentials.
      */
     async listEnvironmentsForProject(projectUuid, q) {
         if (!this.tx)
@@ -298,8 +298,8 @@ export class DebuggAIServerClient {
     /**
      * List credentials for a specific environment. Unpaginated (fetches up to
      * backend max pageSize). q filters label/username server-side via ?search=;
-     * role filters server-side. Used internally by list_credentials when
-     * iterating across envs.
+     * role filters server-side. Used internally by search_environments when
+     * inlining credentials on each env in a page.
      */
     async listCredentialsForEnvironment(projectUuid, envUuid, q, role) {
         if (!this.tx)

package/dist/services/tunnels.js

@@ -3,11 +3,97 @@
  * Provisions short-lived ngrok keys for MCP-managed tunnel setup.
  * Called before executeWorkflow so the tunnel URL is known before execution starts.
  */
-export const createTunnelsService = (tx) => ({
-    async provision(purpose = 'workflow') {
-        const response = await tx.post('api/v1/tunnels/', { purpose });
+import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
+/**
+ * Typed error thrown by provision() when the backend/ngrok path fails.
+ * Carries diagnostic fields a retry wrapper (bead 7nx) can use to decide
+ * whether to retry, and that handler error messages can surface so users
+ * have something actionable to file bug reports against.
+ */
+export class TunnelProvisionError extends Error {
+    status;
+    code;
+    requestId;
+    networkCode;
+    retryable;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'TunnelProvisionError';
+        this.status = opts.status;
+        this.code = opts.code;
+        this.requestId = opts.requestId;
+        this.networkCode = opts.networkCode;
+        this.retryable = opts.retryable;
+    }
+    /**
+     * Stable one-line suffix for user-facing error messages.
+     * Example: '(status: 503, request-id: abc123, retryable)' or '(network: ECONNRESET, retryable)'.
+     */
+    diagnosticSuffix() {
+        const parts = [];
+        if (this.status != null)
+            parts.push(`status: ${this.status}`);
+        if (this.code)
+            parts.push(`code: ${this.code}`);
+        if (this.requestId)
+            parts.push(`request-id: ${this.requestId}`);
+        if (this.networkCode)
+            parts.push(`network: ${this.networkCode}`);
+        parts.push(this.retryable ? 'retryable' : 'not-retryable');
+        return `(${parts.join(', ')})`;
+    }
+}
+/**
+ * Classify an axios-interceptor-rewritten error (or any thrown Error) into a
+ * TunnelProvisionError with retryable semantics. Called from provision().
+ *
+ * Retryable: 5xx, 408 (request timeout), 429 (rate limit), and any network
+ * error (no response received — ECONNRESET / ECONNREFUSED / timeout).
+ * Not retryable: 4xx other than 408/429 — those indicate auth/quota/input
+ * problems that won't self-heal on the same API key.
+ */
+export function classifyProvisionError(err) {
+    const e = err;
+    const message = e?.message ? String(e.message) : 'Tunnel provisioning failed';
+    const status = typeof e?.statusCode === 'number' ? e.statusCode : undefined;
+    const data = e?.responseData;
+    const code = data && typeof data === 'object' && typeof data.code === 'string' ? data.code : undefined;
+    const headers = e?.responseHeaders;
+    const requestId = headers && typeof headers === 'object'
+        ? ((headers['x-request-id'] || headers['X-Request-Id']) ?? undefined)
+        : undefined;
+    const networkCode = typeof e?.networkCode === 'string' ? e.networkCode : undefined;
+    let retryable;
+    if (status == null) {
+        retryable = true;
+    }
+    else if (status >= 500) {
+        retryable = true;
+    }
+    else if (status === 408 || status === 429) {
+        retryable = true;
+    }
+    else {
+        retryable = false;
+    }
+    return new TunnelProvisionError({ message, status, code, requestId, networkCode, retryable });
+}
+const DEFAULT_BACKOFF_MS = [500, 1500, 3000];
+const DEFAULT_MAX_ATTEMPTS = 3;
+export const createTunnelsService = (tx) => {
+    async function provision(purpose = 'workflow') {
+        let response;
+        try {
+            response = await tx.post('api/v1/tunnels/', { purpose });
+        }
+        catch (err) {
+            throw classifyProvisionError(err);
+        }
         if (!response?.tunnelId || !response?.tunnelKey) {
-            throw new Error('Tunnel provisioning failed: missing tunnelId or tunnelKey in response');
+            throw new TunnelProvisionError({
+                message: 'Tunnel provisioning returned a success response missing tunnelId or tunnelKey',
+                retryable: false,
+            });
         }
         return {
             tunnelId: response.tunnelId,
@@ -15,5 +101,48 @@ export const createTunnelsService = (tx) => ({
             keyId: response.keyId,
             expiresAt: response.expiresAt,
         };
-    },
-});
+    }
+    async function provisionWithRetry(opts = {}) {
+        const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        const backoff = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+        const sleep = opts.sleepFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        let lastErr;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                const result = await provision(opts.purpose);
+                if (attempt > 1) {
+                    Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
+                        attempt,
+                        outcome: 'success',
+                    });
+                }
+                return result;
+            }
+            catch (err) {
+                const e = err instanceof TunnelProvisionError ? err : classifyProvisionError(err);
+                lastErr = e;
+                const isLastAttempt = attempt >= maxAttempts;
+                const willRetry = e.retryable && !isLastAttempt;
+                Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
+                    attempt,
+                    outcome: willRetry ? 'will-retry' : 'giving-up',
+                    status: e.status,
+                    code: e.code,
+                    requestId: e.requestId,
+                    networkCode: e.networkCode,
+                    retryable: e.retryable,
+                });
+                if (!willRetry)
+                    throw e;
+                const waitMs = backoff[attempt - 1] ?? backoff[backoff.length - 1] ?? 0;
+                await sleep(waitMs);
+            }
+        }
+        // Unreachable in practice — loop always returns or throws.
+        throw lastErr ?? new TunnelProvisionError({
+            message: 'provisionWithRetry exhausted attempts without a classified error',
+            retryable: false,
+        });
+    }
+    return { provision, provisionWithRetry };
+};

package/dist/tools/createProject.js

@@ -1,6 +1,6 @@
 import { CreateProjectInputSchema } from '../types/index.js';
 import { createProjectHandler } from '../handlers/createProjectHandler.js';
-const DESCRIPTION = `Create a new DebuggAI project. Required: name, platform (e.g. "web"), teamUuid (from list_teams), repoUuid (from list_repos). Returns {created: true, project: {uuid, name, slug, platform, repoName, ...}}. The repo must be GitHub-linked to the account. Use list_teams + list_repos first to discover valid UUIDs.`;
+const DESCRIPTION = `Create a new DebuggAI project. Required: name, platform (e.g. "web"), plus a team and a repo. Team and repo each accept EITHER a UUID or a name: pass teamUuid OR teamName, and repoUuid OR repoName. Name resolution does a backend search with case-insensitive exact match (returns AmbiguousMatch with candidates on multiple hits, NotFound on no hit). The repo must be GitHub-linked to the account. Returns {created: true, project: {uuid, name, slug, platform, repoName, ...}}.`;
 export function buildCreateProjectTool() {
     return {
         name: 'create_project',
@@ -11,10 +11,12 @@ export function buildCreateProjectTool() {
             properties: {
                 name: { type: 'string', description: 'Project name. Required.', minLength: 1 },
                 platform: { type: 'string', description: 'Platform (e.g. "web"). Required.', minLength: 1 },
-                teamUuid: { type: 'string', description: 'Team UUID (from list_teams). Required.' },
-                repoUuid: { type: 'string', description: 'GitHub repo UUID (from list_repos). Required — repo must be GitHub-linked.' },
+                teamUuid: { type: 'string', description: 'Team UUID. Provide teamUuid OR teamName, not both.' },
+                teamName: { type: 'string', description: 'Team name (backend-resolved, case-insensitive exact match). Provide teamUuid OR teamName, not both.' },
+                repoUuid: { type: 'string', description: 'GitHub repo UUID. Provide repoUuid OR repoName, not both. Repo must be GitHub-linked.' },
+                repoName: { type: 'string', description: 'GitHub repo name, e.g. "org/repo" (backend-resolved, case-insensitive exact match). Provide repoUuid OR repoName, not both.' },
             },
-            required: ['name', 'platform', 'teamUuid', 'repoUuid'],
+            required: ['name', 'platform'],
             additionalProperties: false,
         },
     };

package/dist/utils/axiosTransport.js

@@ -35,9 +35,14 @@ export class AxiosTransport {
                 const newErr = new Error(String(msg));
                 newErr.statusCode = err.response?.status;
                 newErr.responseData = data;
+                newErr.responseHeaders = err.response?.headers;
                 return Promise.reject(newErr);
             }
-            return Promise.reject(new Error(err.message || 'Unknown Axios error'));
+            // Network-class error (no response received) — preserve err.code (ECONNRESET, etc.)
+            const networkErr = new Error(err.message || 'Unknown Axios error');
+            if (err.code)
+                networkErr.networkCode = err.code;
+            return Promise.reject(networkErr);
         });
         // Request → snake_case
         this.axios.interceptors.request.use((cfg) => {

package/dist/utils/telemetry.js

@@ -53,5 +53,6 @@ export const TelemetryEvents = {
     TOOL_FAILED: 'tool.failed',
     WORKFLOW_EXECUTED: 'workflow.executed',
     TUNNEL_PROVISIONED: 'tunnel.provisioned',
+    TUNNEL_PROVISION_RETRY: 'tunnel.provision_retry',
     TUNNEL_STOPPED: 'tunnel.stopped',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "1.0.64",
+  "version": "1.0.66",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {
@@ -10,7 +10,10 @@
     "node": ">=20.20.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "lint": "eslint .",