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

package/CHANGELOG.md

@@ -0,0 +1,177 @@
+# 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]
+
+## [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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "1.0.64",
+  "version": "1.0.65",
   "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 .",