@debugg-ai/debugg-ai-mcp 1.0.63 → 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/config/index.js

@@ -28,7 +28,10 @@ const configSchema = z.object({
         version: z.string(),
     }),
     api: z.object({
-        key: z.string().min(1, 'API key is required (set DEBUGGAI_API_KEY)'),
+        // key is validated at tool-call time (not at boot) so MCP clients can surface
+        // a proper error message instead of seeing the subprocess die → "Failed to
+        // reconnect". See bead cma + flow 25.
+        key: z.string(),
         tokenType: z.enum(['token', 'bearer']).default('token'),
         baseUrl: z.string().url().default('https://api.debugg.ai'),
     }),

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 };
             }
@@ -44,6 +44,39 @@ export async function createEnvironmentHandler(input, _context) {
             projectUuid,
             environment: env,
         };
+        // Optional credentials seed: best-effort per-cred. Success goes to
+        // credentials[]; failure goes to credentialWarnings[] (never blocks env creation).
+        if (input.credentials && input.credentials.length > 0) {
+            const created = [];
+            const warnings = [];
+            for (const seed of input.credentials) {
+                try {
+                    const cred = await client.createCredential(projectUuid, env.uuid, {
+                        label: seed.label,
+                        username: seed.username,
+                        password: seed.password,
+                        role: seed.role,
+                    });
+                    // Defensive: drop any stray password from the response shape
+                    created.push({
+                        uuid: cred.uuid,
+                        label: cred.label,
+                        username: cred.username,
+                        role: cred.role ?? null,
+                        environmentUuid: cred.environmentUuid,
+                    });
+                }
+                catch (err) {
+                    warnings.push({
+                        label: seed.label,
+                        error: err?.message ?? String(err),
+                    });
+                }
+            }
+            payload.credentials = created;
+            if (warnings.length > 0)
+                payload.credentialWarnings = warnings;
+        }
         logger.toolComplete('create_environment', Date.now() - start);
         return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
     }

package/dist/handlers/createProjectHandler.js

@@ -3,26 +3,78 @@ import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { config } from '../config/index.js';
 const logger = new Logger({ module: 'createProjectHandler' });
+function errorResp(error, message, extra = {}) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ error, message, ...extra }, null, 2),
+            }],
+        isError: true,
+    };
+}
+/**
+ * Resolve a name to a single uuid via backend search + exact (case-insensitive)
+ * match. Returns either a uuid, a NotFound error, or an Ambiguous error with
+ * candidate options surfaced.
+ */
+function resolveName(name, candidates, kind) {
+    const needle = name.toLowerCase();
+    const matches = candidates.filter(c => c.name.toLowerCase() === needle);
+    if (matches.length === 0) {
+        return {
+            error: `${kind}NotFound`,
+            message: `No ${kind.toLowerCase()} matching "${name}" found. ` +
+                (candidates.length > 0
+                    ? `Available: ${candidates.slice(0, 10).map(c => `"${c.name}"`).join(', ')}`
+                    : '(none accessible to this API key)'),
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            error: 'AmbiguousMatch',
+            message: `Multiple ${kind.toLowerCase()}s match "${name}". Pass ${kind.toLowerCase()}Uuid explicitly.`,
+            candidates: matches.map(m => ({ uuid: m.uuid, name: m.name })),
+        };
+    }
+    return { uuid: matches[0].uuid };
+}
 export async function createProjectHandler(input, _context) {
     const start = Date.now();
     logger.toolStart('create_project', {
-        name: input.name,
-        platform: input.platform,
-        teamUuid: input.teamUuid,
-        repoUuid: input.repoUuid,
+        name: input.name, platform: input.platform,
+        teamUuid: input.teamUuid, teamName: input.teamName,
+        repoUuid: input.repoUuid, repoName: input.repoName,
     });
     try {
         const client = new DebuggAIServerClient(config.api.key);
         await client.init();
+        // Resolve team
+        let teamUuid = input.teamUuid;
+        if (!teamUuid && input.teamName) {
+            const teamsResp = await client.listTeams({ page: 1, pageSize: 100 }, input.teamName);
+            const resolved = resolveName(input.teamName, teamsResp.teams, 'Team');
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            teamUuid = resolved.uuid;
+        }
+        // Resolve repo
+        let repoUuid = input.repoUuid;
+        if (!repoUuid && input.repoName) {
+            const reposResp = await client.listRepos({ page: 1, pageSize: 100 }, input.repoName);
+            const resolved = resolveName(input.repoName, reposResp.repos, 'Repo');
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            repoUuid = resolved.uuid;
+        }
+        if (!teamUuid || !repoUuid) {
+            // Schema-level invariant should have caught this, but defensive.
+            return errorResp('ValidationError', `Unable to resolve ${!teamUuid ? 'team' : 'repo'} — provide teamUuid/teamName and repoUuid/repoName.`);
+        }
         const project = await client.createProject({
-            name: input.name,
-            platform: input.platform,
-            teamUuid: input.teamUuid,
-            repoUuid: input.repoUuid,
+            name: input.name, platform: input.platform, teamUuid, repoUuid,
         });
-        const payload = { created: true, project };
         logger.toolComplete('create_project', Date.now() - start);
-        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify({ created: true, project }, null, 2) }] };
     }
     catch (error) {
         logger.toolError('create_project', error, Date.now() - start);

package/dist/handlers/index.js

@@ -1,22 +1,12 @@
 export * from './testPageChangesHandler.js';
 export * from './triggerCrawlHandler.js';
-export * from './listEnvironmentsHandler.js';
-export * from './listCredentialsHandler.js';
-export * from './listProjectsHandler.js';
+export * from './searchProjectsHandler.js';
+export * from './searchEnvironmentsHandler.js';
+export * from './searchExecutionsHandler.js';
 export * from './createEnvironmentHandler.js';
-export * from './createCredentialHandler.js';
-export * from './getEnvironmentHandler.js';
 export * from './updateEnvironmentHandler.js';
 export * from './deleteEnvironmentHandler.js';
-export * from './getCredentialHandler.js';
-export * from './updateCredentialHandler.js';
-export * from './deleteCredentialHandler.js';
-export * from './getProjectHandler.js';
+// Credential mutations are folded into create_environment + update_environment.
 export * from './updateProjectHandler.js';
 export * from './deleteProjectHandler.js';
-export * from './listExecutionsHandler.js';
-export * from './getExecutionHandler.js';
-export * from './cancelExecutionHandler.js';
-export * from './listTeamsHandler.js';
-export * from './listReposHandler.js';
 export * from './createProjectHandler.js';

package/dist/handlers/searchEnvironmentsHandler.js

@@ -0,0 +1,122 @@
+/**
+ * search_environments handler (bead 5kw)
+ *
+ * Absorbs list_environments + get_environment + all credential search.
+ * Each environment in the response has its credentials expanded inline.
+ *
+ * Modes:
+ *   uuid mode: {uuid, projectUuid?} → {filter:{uuid}, project, pageInfo:{totalCount:1,...},
+ *                                      environments:[{...env, credentials:[...]}]}
+ *   filter mode: {projectUuid?, q?, page?, pageSize?} → paginated list, creds inline per env
+ *
+ * Invariants:
+ *   - NEVER returns a password field anywhere in the response (defensive strip at handler edge)
+ *   - Git-fallback for projectUuid: detectRepoName() → findProjectByRepoName(); NoProjectResolved if both fail
+ *   - NotFound on unknown uuid returns isError:true
+ */
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { config } from '../config/index.js';
+import { detectRepoName } from '../utils/gitContext.js';
+import { toPaginationParams, makePageInfo } from '../utils/pagination.js';
+const logger = new Logger({ module: 'searchEnvironmentsHandler' });
+function stripPassword(cred) {
+    // Defensive: take only known-safe keys. Never spread the source.
+    return {
+        uuid: cred.uuid,
+        label: cred.label,
+        username: cred.username,
+        role: cred.role ?? null,
+        ...(cred.environmentUuid ? { environmentUuid: cred.environmentUuid } : {}),
+    };
+}
+function notFound(uuid) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ error: 'NotFound', message: `Environment ${uuid} not found.`, uuid }, null, 2),
+            }],
+        isError: true,
+    };
+}
+function noProjectResolved(pagination, reason) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    error: 'NoProjectResolved',
+                    message: reason,
+                    pageInfo: makePageInfo(pagination.page, pagination.pageSize, 0, null),
+                    environments: [],
+                }, null, 2),
+            }],
+    };
+}
+export async function searchEnvironmentsHandler(input, _context) {
+    const start = Date.now();
+    const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
+    logger.toolStart('search_environments', { ...input, ...pagination });
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        // ── Resolve projectUuid ──
+        let projectUuid = input.projectUuid;
+        let project = null;
+        if (!projectUuid) {
+            const repoName = detectRepoName();
+            if (!repoName) {
+                return noProjectResolved(pagination, 'No git repo detected and no projectUuid provided. Pass projectUuid (get via search_projects) or invoke from a directory with a git origin.');
+            }
+            const resolved = await client.findProjectByRepoName(repoName);
+            if (!resolved) {
+                return noProjectResolved(pagination, `No DebuggAI project found for repo "${repoName}". Pass projectUuid explicitly.`);
+            }
+            projectUuid = resolved.uuid;
+            project = { uuid: resolved.uuid, name: resolved.name, repoName: resolved.repo?.name ?? repoName };
+        }
+        else {
+            project = { uuid: projectUuid, name: null, repoName: null };
+        }
+        // ── uuid mode ──
+        if (input.uuid) {
+            try {
+                const env = await client.getEnvironment(projectUuid, input.uuid);
+                const creds = await client.listCredentialsForEnvironment(projectUuid, input.uuid).catch(() => []);
+                const payload = {
+                    project,
+                    filter: { uuid: input.uuid },
+                    pageInfo: { page: 1, pageSize: 1, totalCount: 1, totalPages: 1, hasMore: false },
+                    environments: [{ ...env, credentials: creds.map(stripPassword) }],
+                };
+                logger.toolComplete('search_environments', Date.now() - start);
+                return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+            }
+            catch (err) {
+                if (err?.statusCode === 404 || err?.response?.status === 404)
+                    return notFound(input.uuid);
+                throw err;
+            }
+        }
+        // ── Filter mode ──
+        const { pageInfo, environments } = await client.listEnvironmentsPaginated(projectUuid, pagination, input.q);
+        // Expand creds per env (sequential — bounded by page size, typically ≤20)
+        const withCreds = [];
+        for (const env of environments) {
+            const creds = await client.listCredentialsForEnvironment(projectUuid, env.uuid).catch(() => []);
+            withCreds.push({ ...env, credentials: creds.map(stripPassword) });
+        }
+        const payload = {
+            project,
+            filter: { q: input.q ?? null },
+            pageInfo,
+            environments: withCreds,
+        };
+        logger.toolComplete('search_environments', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('search_environments', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'search_environments');
+    }
+}