@debugg-ai/debugg-ai-mcp 2.9.7 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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).
 
+## [3.0.0]
+
+### Changed — Tool surface consolidated to 8 action-based tools (BREAKING)
+
+The 20 per-verb tools were consolidated into **8** tools: three browser tools
+(`check_app_in_browser`, `probe_page`, `trigger_crawl`) plus one action-based
+tool per entity — `project`, `environment`, `test_suite`, `test_case`,
+`executions` — each taking an `action` discriminator. Clients pick up the new
+surface on MCP restart.
+
+Migration (old tool → new tool + action):
+
+- `search_projects` → `project {action:"get"|"list"}`
+- `create_project` → `project {action:"create"}`
+- `search_environments` → `environment {action:"get"|"list"}`
+- `create_environment` / `update_environment` / `delete_environment` → `environment {action:"create"|"update"|"delete"}`
+- `create_test_suite` / `search_test_suites` / `run_test_suite` / `get_test_suite_results` / `delete_test_suite` → `test_suite {action:"create"|"list"|"run"|"results"|"delete"}`
+- `create_test_case` / `update_test_case` / `delete_test_case` → `test_case {action:"create"|"update"|"delete"}`
+- `search_executions` → `executions {action:"get"|"list"}`
+
+### Removed
+
+- `update_project` and `delete_project` — rename/delete a project from the DebuggAI web app (both were effectively unused).
+- `trigger_crawl`'s `headless` parameter — the MCP now always runs headless (no opt-out).
+
+### Added
+
+- Destructive `delete` actions require confirmation: an elicitation prompt when the client supports it, otherwise a required `confirm: true` argument.
+
 ## [Unreleased]
 
 ### Added — E2E test suite management (8 new MCP tools)

package/README.md

@@ -34,7 +34,7 @@ docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-m
 
 ## Tools
 
-The server exposes **12** tools grouped into Browser (3), Search (3), Projects (3), and Environments (3). The headline tools are `check_app_in_browser` (full AI agent) and `probe_page` (lightweight no-LLM page probe); the rest manage projects, environments + their credentials, and execution history through a uniform `search_*` + CRUD pattern.
+The server exposes **8** tools: three **Browser** tools plus one **action-based** tool per managed entity. The headline tools are `check_app_in_browser` (full AI agent) and `probe_page` (lightweight no-LLM page probe). The rest — `project`, `environment`, `test_suite`, `test_case`, `executions` — each take an `action` discriminator (e.g. `{"action":"list"}`) that selects the operation. Destructive `delete` actions require confirmation (an elicitation prompt where supported, otherwise `confirm: true`).
 
 ### Browser
 
@@ -69,7 +69,7 @@ Every successful run returns a `browserSession` block alongside the screenshot
 }
 ```
 
-URLs are short-lived presigned S3 — refetch the parent execution via `search_executions` to renew. `harStatus` / `consoleLogStatus` disambiguate `'downloaded'` (URL fetchable), `'not_available'` (page emitted nothing), `'failed'` (capture broke). On a fresh run the URLs are commonly `null` because capture uploads async after the agent finishes — poll `search_executions` with the returned `executionId` until status reaches `'downloaded'`. Authorization / Cookie / `token`/`secret`/`api_key` headers are scrubbed server-side before the artifacts are persisted.
+URLs are short-lived presigned S3 — refetch the parent execution via `executions {action:"get", uuid}` to renew. `harStatus` / `consoleLogStatus` disambiguate `'downloaded'` (URL fetchable), `'not_available'` (page emitted nothing), `'failed'` (capture broke). On a fresh run the URLs are commonly `null` because capture uploads async after the agent finishes — poll `executions {action:"get", uuid: executionId}` until status reaches `'downloaded'`. Authorization / Cookie / `token`/`secret`/`api_key` headers are scrubbed server-side before the artifacts are persisted.
 
 #### `trigger_crawl`
 
@@ -95,33 +95,54 @@ The whole batch shares a single backend execution + browser session + tunnel —
 
 Performance budget: <10s for 1 URL, <25s for 20. Localhost dead-port returns `LocalServerUnreachable` in <2s without burning a workflow execution.
 
-### Search (dual-mode: uuid detail OR filtered list)
+### `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}`.
+| Action | Params | Result |
+|--------|--------|--------|
+| `get` | `{uuid}` | Curated project detail |
+| `list` | `{q?, page?, pageSize?}` | Paginated summaries |
+| `create` | `{name, platform, (teamUuid\|teamName), (repoUuid\|repoName)}` | Created project |
 
-| 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 |
+Team and repo resolve by **either** uuid **or** name (case-insensitive exact match; `NotFound` if none, `AmbiguousMatch` if multiple). There is **no** `update`/`delete` — rename or delete a project from the DebuggAI web app.
 
-`projectUuid` is optional on `search_environments` — if omitted, it auto-resolves from the git repo. Credentials are **always** returned without passwords.
+### `environment`
 
-### Projects
+| Action | Params | Result |
+|--------|--------|--------|
+| `get` | `{uuid, projectUuid?}` | Env with credentials inlined (passwords never returned) |
+| `list` | `{projectUuid?, q?, page?, pageSize?}` | Paginated envs, each with a credentials array |
+| `create` | `{name, url, description?, projectUuid?, credentials?}` | Created env (optionally seeds credentials) |
+| `update` | `{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}` | Patched env; credential ops run **remove → update → add** |
+| `delete` | `{uuid, projectUuid?, confirm?}` | Deletes env (cascades credentials) — **requires confirmation** |
 
-| Tool | Purpose |
-|------|---------|
-| `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. |
+`projectUuid` auto-resolves from the git repo when omitted. Per-cred failures surface in `credentialWarnings[]` without blocking the env op.
 
-### Environments (credential sub-actions folded in)
+### `test_suite`
 
-| Tool | Purpose |
-|------|---------|
-| `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. |
+| Action | Params | Result |
+|--------|--------|--------|
+| `list` | `{projectUuid\|projectName, search?, page?, pageSize?}` | Paginated suites with status + pass rate |
+| `create` | `{name, description, projectUuid\|projectName}` | Created suite |
+| `run` | `{suiteUuid\|(suiteName+project), targetUrl?}` | Triggers all tests async |
+| `results` | `{suiteUuid\|(suiteName+project)}` | Suite + per-test outcomes |
+| `delete` | `{suiteUuid\|(suiteName+project), confirm?}` | Soft-delete — **requires confirmation** |
+
+### `test_case`
+
+| Action | Params | Result |
+|--------|--------|--------|
+| `create` | `{name, description, agentTaskDescription, suiteUuid\|(suiteName+project), relativeUrl?, maxSteps?}` | Created test case (not auto-run) |
+| `update` | `{testUuid, name?, description?, agentTaskDescription?}` | Patched test case |
+| `delete` | `{testUuid, confirm?}` | Soft-delete — **requires confirmation** |
+
+### `executions`
+
+| Action | Params | Result |
+|--------|--------|--------|
+| `get` | `{uuid}` | Full detail (`nodeExecutions` + state + errorInfo) + screenshot/gif artifacts |
+| `list` | `{status?, projectUuid?, page?, pageSize?}` | Paginated summaries |
+
+404 from the backend surfaces as `isError: true` with `{error: 'NotFound', message, uuid}`. Credentials are **always** returned without passwords.
 
 ### Pagination
 
@@ -144,6 +165,24 @@ Pass optional `page` (1-indexed, default 1) and `pageSize` (default 20, max 200;
 - 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 to v3.0.0 (action-based tools)
+
+v3 consolidated the 20 per-verb tools into 8 action-based tools. Old tool → new `tool {action}`:
+
+| Removed | Replacement |
+|---------|-------------|
+| `search_projects` | `project {action:"get"}` / `project {action:"list"}` |
+| `create_project` | `project {action:"create"}` |
+| `update_project`, `delete_project` | **Dropped** — use the DebuggAI web app |
+| `search_environments` | `environment {action:"get"}` / `{action:"list"}` |
+| `create_environment` / `update_environment` / `delete_environment` | `environment {action:"create"\|"update"\|"delete"}` |
+| `create_test_suite` / `search_test_suites` / `run_test_suite` / `get_test_suite_results` / `delete_test_suite` | `test_suite {action:"create"\|"list"\|"run"\|"results"\|"delete"}` |
+| `create_test_case` / `update_test_case` / `delete_test_case` | `test_case {action:"create"\|"update"\|"delete"}` |
+| `search_executions` | `executions {action:"get"\|"list"}` |
+| `trigger_crawl` `headless` param | **Dropped** — always headless |
+
+`delete` actions now require confirmation (elicitation prompt, or `confirm: true`). Clients pick up the new surface on MCP restart.
+
 ## Migration from v1.x (breaking change in v2.0.0)
 
 v2 collapsed a 22-tool surface to 11. Old-tool → new-tool mapping:

package/dist/handlers/environmentHandler.js

@@ -0,0 +1,27 @@
+import { ensureConfirmed } from '../utils/confirmDestructive.js';
+import { searchEnvironmentsHandler } from './searchEnvironmentsHandler.js';
+import { createEnvironmentHandler } from './createEnvironmentHandler.js';
+import { updateEnvironmentHandler } from './updateEnvironmentHandler.js';
+import { deleteEnvironmentHandler } from './deleteEnvironmentHandler.js';
+export async function environmentHandler(input, ctx) {
+    switch (input.action) {
+        case 'get':
+            return searchEnvironmentsHandler({ uuid: input.uuid, projectUuid: input.projectUuid }, ctx);
+        case 'list':
+            return searchEnvironmentsHandler({ projectUuid: input.projectUuid, q: input.q, page: input.page, pageSize: input.pageSize }, ctx);
+        case 'create': {
+            const { action, ...rest } = input;
+            return createEnvironmentHandler(rest, ctx);
+        }
+        case 'update': {
+            const { action, ...rest } = input;
+            return updateEnvironmentHandler(rest, ctx);
+        }
+        case 'delete': {
+            const refusal = await ensureConfirmed('delete', `environment ${input.uuid}`, input, ctx);
+            if (refusal)
+                return refusal;
+            return deleteEnvironmentHandler({ uuid: input.uuid, projectUuid: input.projectUuid }, ctx);
+        }
+    }
+}

package/dist/handlers/executionsHandler.js

@@ -0,0 +1,9 @@
+import { searchExecutionsHandler } from './searchExecutionsHandler.js';
+export async function executionsHandler(input, ctx) {
+    switch (input.action) {
+        case 'get':
+            return searchExecutionsHandler({ uuid: input.uuid }, ctx);
+        case 'list':
+            return searchExecutionsHandler({ projectUuid: input.projectUuid, status: input.status, page: input.page, pageSize: input.pageSize }, ctx);
+    }
+}

package/dist/handlers/index.js

@@ -8,9 +8,14 @@ export * from './createEnvironmentHandler.js';
 export * from './updateEnvironmentHandler.js';
 export * from './deleteEnvironmentHandler.js';
 // Credential mutations are folded into create_environment + update_environment.
-export * from './updateProjectHandler.js';
-export * from './deleteProjectHandler.js';
+// update_project + delete_project were cut (epic yg7o6, D8).
 export * from './createProjectHandler.js';
+// Action-tool dispatchers (the registered surface).
+export * from './projectHandler.js';
+export * from './environmentHandler.js';
+export * from './testSuiteHandler.js';
+export * from './testCaseHandler.js';
+export * from './executionsHandler.js';
 export * from './createTestSuiteHandler.js';
 export * from './searchTestSuitesHandler.js';
 export * from './deleteTestSuiteHandler.js';

package/dist/handlers/projectHandler.js

@@ -0,0 +1,14 @@
+import { searchProjectsHandler } from './searchProjectsHandler.js';
+import { createProjectHandler } from './createProjectHandler.js';
+export async function projectHandler(input, ctx) {
+    switch (input.action) {
+        case 'get':
+            return searchProjectsHandler({ uuid: input.uuid }, ctx);
+        case 'list':
+            return searchProjectsHandler({ q: input.q, page: input.page, pageSize: input.pageSize }, ctx);
+        case 'create': {
+            const { action, ...rest } = input;
+            return createProjectHandler(rest, ctx);
+        }
+    }
+}

package/dist/handlers/testCaseHandler.js

@@ -0,0 +1,22 @@
+import { ensureConfirmed } from '../utils/confirmDestructive.js';
+import { createTestCaseHandler } from './createTestCaseHandler.js';
+import { updateTestCaseHandler } from './updateTestCaseHandler.js';
+import { deleteTestCaseHandler } from './deleteTestCaseHandler.js';
+export async function testCaseHandler(input, ctx) {
+    switch (input.action) {
+        case 'create': {
+            const { action, ...rest } = input;
+            return createTestCaseHandler(rest, ctx);
+        }
+        case 'update': {
+            const { action, ...rest } = input;
+            return updateTestCaseHandler(rest, ctx);
+        }
+        case 'delete': {
+            const refusal = await ensureConfirmed('delete', `test case ${input.testUuid}`, input, ctx);
+            if (refusal)
+                return refusal;
+            return deleteTestCaseHandler({ testUuid: input.testUuid }, ctx);
+        }
+    }
+}

package/dist/handlers/testSuiteHandler.js

@@ -0,0 +1,34 @@
+import { ensureConfirmed } from '../utils/confirmDestructive.js';
+import { searchTestSuitesHandler } from './searchTestSuitesHandler.js';
+import { createTestSuiteHandler } from './createTestSuiteHandler.js';
+import { runTestSuiteHandler } from './runTestSuiteHandler.js';
+import { getTestSuiteResultsHandler } from './getTestSuiteResultsHandler.js';
+import { deleteTestSuiteHandler } from './deleteTestSuiteHandler.js';
+export async function testSuiteHandler(input, ctx) {
+    switch (input.action) {
+        case 'list': {
+            const { action, ...rest } = input;
+            return searchTestSuitesHandler(rest, ctx);
+        }
+        case 'create': {
+            const { action, ...rest } = input;
+            return createTestSuiteHandler(rest, ctx);
+        }
+        case 'run': {
+            const { action, ...rest } = input;
+            return runTestSuiteHandler(rest, ctx);
+        }
+        case 'results': {
+            const { action, ...rest } = input;
+            return getTestSuiteResultsHandler(rest, ctx);
+        }
+        case 'delete': {
+            const label = `test suite ${input.suiteUuid ?? input.suiteName ?? ''}`.trim();
+            const refusal = await ensureConfirmed('delete', label, input, ctx);
+            if (refusal)
+                return refusal;
+            const { action, confirm, ...rest } = input;
+            return deleteTestSuiteHandler(rest, ctx);
+        }
+    }
+}

package/dist/handlers/triggerCrawlHandler.js

@@ -150,8 +150,7 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
         };
         if (input.projectUuid)
             contextData.projectId = input.projectUuid;
-        if (typeof input.headless === 'boolean')
-            contextData.headless = input.headless;
+        contextData.headless = true; // D7: the MCP always runs headless — no opt-out.
         if (typeof input.timeoutSeconds === 'number')
             contextData.timeoutSeconds = input.timeoutSeconds;
         const env = {};

package/dist/tools/environment.js

@@ -0,0 +1,54 @@
+import { EnvironmentInputSchema } from '../types/index.js';
+import { environmentHandler } from '../handlers/environmentHandler.js';
+const CRED_ITEM = {
+    type: 'object',
+    properties: {
+        label: { type: 'string' }, username: { type: 'string' }, password: { type: 'string', description: 'Write-only — never returned.' }, role: { type: 'string' },
+    },
+    required: ['label', 'username', 'password'],
+    additionalProperties: false,
+};
+const DESCRIPTION = `Manage environments (and their login credentials) under a project. Pass an "action":
+  - "get"    {uuid, projectUuid?} → one environment with credentials inline (passwords never returned).
+  - "list"   {projectUuid?, q?, page?, pageSize?} → paginated environments. projectUuid auto-resolves from the git repo if omitted.
+  - "create" {name, url, description?, projectUuid?, credentials?} → create an env, optionally seeding credentials.
+  - "update" {uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?} → patch env + manage credentials.
+  - "delete" {uuid, projectUuid?, confirm?} → delete env (DESTRUCTIVE; requires confirmation).`;
+export function buildEnvironmentTool() {
+    return {
+        name: 'environment',
+        title: 'Environment',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['get', 'list', 'create', 'update', 'delete'], description: 'Operation to perform.' },
+                uuid: { type: 'string', description: '[get/update/delete] Environment UUID.' },
+                projectUuid: { type: 'string', description: 'Target project (defaults to git auto-detect).' },
+                q: { type: 'string', description: '[list] Free-text search over env name.' },
+                page: { type: 'number', description: '[list] Page (1-indexed).' },
+                pageSize: { type: 'number', description: '[list] Page size (1..200).' },
+                name: { type: 'string', description: '[create/update] Environment name.' },
+                url: { type: 'string', description: '[create/update] Base URL.' },
+                description: { type: 'string', description: '[create/update] Free-text description.' },
+                credentials: { type: 'array', items: CRED_ITEM, description: '[create] Seed login credentials.' },
+                addCredentials: { type: 'array', items: CRED_ITEM, description: '[update] Add credentials.' },
+                updateCredentials: { type: 'array', items: { type: 'object', properties: { uuid: { type: 'string' }, label: { type: 'string' }, username: { type: 'string' }, password: { type: 'string' }, role: { type: 'string' } }, required: ['uuid'], additionalProperties: false }, description: '[update] Patch credentials by UUID.' },
+                removeCredentialIds: { type: 'array', items: { type: 'string' }, description: '[update] Delete credentials by UUID.' },
+                confirm: { type: 'boolean', description: '[delete] Set true to confirm deletion (when the client cannot prompt).' },
+            },
+            required: ['action'],
+            oneOf: [
+                { properties: { action: { const: 'get' } }, required: ['action', 'uuid'] },
+                { properties: { action: { const: 'list' } }, required: ['action'] },
+                { properties: { action: { const: 'create' } }, required: ['action', 'name', 'url'] },
+                { properties: { action: { const: 'update' } }, required: ['action', 'uuid'] },
+                { properties: { action: { const: 'delete' } }, required: ['action', 'uuid'] },
+            ],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedEnvironmentTool() {
+    return { ...buildEnvironmentTool(), inputSchema: EnvironmentInputSchema, handler: environmentHandler };
+}

package/dist/tools/executions.js

@@ -0,0 +1,34 @@
+import { ExecutionsInputSchema } from '../types/index.js';
+import { executionsHandler } from '../handlers/executionsHandler.js';
+const DESCRIPTION = `Look up workflow executions (history of check_app_in_browser, trigger_crawl, and test-suite runs). Pass an "action":
+  - "get"  {uuid} → one execution with FULL detail (nodeExecutions, state, errorInfo) + any screenshot/gif artifacts.
+  - "list" {projectUuid?, status?, page?, pageSize?} → paginated execution summaries. status ∈ completed|running|failed|cancelled|pending.
+
+Tip: after a fresh check_app_in_browser run, poll action:"get" with the returned executionId until artifact URLs are available.`;
+export function buildExecutionsTool() {
+    return {
+        name: 'executions',
+        title: 'Workflow Executions',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['get', 'list'], description: 'Operation to perform.' },
+                uuid: { type: 'string', description: '[get] Execution UUID.' },
+                projectUuid: { type: 'string', description: '[list] Filter by project UUID.' },
+                status: { type: 'string', description: '[list] Filter by status.' },
+                page: { type: 'number', description: '[list] Page (1-indexed).' },
+                pageSize: { type: 'number', description: '[list] Page size (1..200).' },
+            },
+            required: ['action'],
+            oneOf: [
+                { properties: { action: { const: 'get' } }, required: ['action', 'uuid'] },
+                { properties: { action: { const: 'list' } }, required: ['action'] },
+            ],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedExecutionsTool() {
+    return { ...buildExecutionsTool(), inputSchema: ExecutionsInputSchema, handler: executionsHandler };
+}

package/dist/tools/index.js

@@ -1,66 +1,41 @@
 import { buildTestPageChangesTool, buildValidatedTestPageChangesTool } from './testPageChanges.js';
 import { buildTriggerCrawlTool, buildValidatedTriggerCrawlTool } from './triggerCrawl.js';
 import { buildProbePageTool, buildValidatedProbePageTool } from './probePage.js';
-import { buildSearchProjectsTool, buildValidatedSearchProjectsTool } from './searchProjects.js';
-import { buildSearchEnvironmentsTool, buildValidatedSearchEnvironmentsTool } from './searchEnvironments.js';
-import { buildSearchExecutionsTool, buildValidatedSearchExecutionsTool } from './searchExecutions.js';
-import { buildCreateEnvironmentTool, buildValidatedCreateEnvironmentTool } from './createEnvironment.js';
-import { buildUpdateEnvironmentTool, buildValidatedUpdateEnvironmentTool } from './updateEnvironment.js';
-import { buildDeleteEnvironmentTool, buildValidatedDeleteEnvironmentTool } from './deleteEnvironment.js';
-import { buildUpdateProjectTool, buildValidatedUpdateProjectTool } from './updateProject.js';
-import { buildDeleteProjectTool, buildValidatedDeleteProjectTool } from './deleteProject.js';
-import { buildCreateProjectTool, buildValidatedCreateProjectTool } from './createProject.js';
-import { buildCreateTestSuiteTool, buildValidatedCreateTestSuiteTool, buildSearchTestSuitesTool, buildValidatedSearchTestSuitesTool, buildDeleteTestSuiteTool, buildValidatedDeleteTestSuiteTool, buildCreateTestCaseTool, buildValidatedCreateTestCaseTool, buildUpdateTestCaseTool, buildValidatedUpdateTestCaseTool, buildDeleteTestCaseTool, buildValidatedDeleteTestCaseTool, buildRunTestSuiteTool, buildValidatedRunTestSuiteTool, buildGetTestSuiteResultsTool, buildValidatedGetTestSuiteResultsTool, } from './testSuiteTools.js';
+import { buildProjectTool, buildValidatedProjectTool } from './project.js';
+import { buildEnvironmentTool, buildValidatedEnvironmentTool } from './environment.js';
+import { buildExecutionsTool, buildValidatedExecutionsTool } from './executions.js';
+import { buildTestSuiteTool, buildValidatedTestSuiteTool } from './testSuite.js';
+import { buildTestCaseTool, buildValidatedTestCaseTool } from './testCase.js';
 let _tools = null;
 let _validatedTools = null;
 const toolRegistry = new Map();
 /**
  * Initialize tools with project context (call once after resolveProjectContext).
+ *
+ * The surface is 8 action-based tools (epic yg7o6): 3 browser tools plus one
+ * tool per managed entity (project/environment/test_suite/test_case/executions),
+ * each routing an `action` discriminator to its handler.
  */
 export function initTools(ctx) {
     const tools = [
         buildTestPageChangesTool(ctx),
-        buildTriggerCrawlTool(ctx),
         buildProbePageTool(),
-        buildSearchProjectsTool(),
-        buildSearchEnvironmentsTool(),
-        buildCreateEnvironmentTool(),
-        buildUpdateEnvironmentTool(),
-        buildDeleteEnvironmentTool(),
-        buildUpdateProjectTool(),
-        buildDeleteProjectTool(),
-        buildSearchExecutionsTool(),
-        buildCreateProjectTool(),
-        buildCreateTestSuiteTool(),
-        buildSearchTestSuitesTool(),
-        buildDeleteTestSuiteTool(),
-        buildCreateTestCaseTool(),
-        buildUpdateTestCaseTool(),
-        buildDeleteTestCaseTool(),
-        buildRunTestSuiteTool(),
-        buildGetTestSuiteResultsTool(),
+        buildTriggerCrawlTool(ctx),
+        buildProjectTool(),
+        buildEnvironmentTool(),
+        buildTestSuiteTool(),
+        buildTestCaseTool(),
+        buildExecutionsTool(),
     ];
     const validated = [
         buildValidatedTestPageChangesTool(ctx),
-        buildValidatedTriggerCrawlTool(ctx),
         buildValidatedProbePageTool(),
-        buildValidatedSearchProjectsTool(),
-        buildValidatedSearchEnvironmentsTool(),
-        buildValidatedCreateEnvironmentTool(),
-        buildValidatedUpdateEnvironmentTool(),
-        buildValidatedDeleteEnvironmentTool(),
-        buildValidatedUpdateProjectTool(),
-        buildValidatedDeleteProjectTool(),
-        buildValidatedSearchExecutionsTool(),
-        buildValidatedCreateProjectTool(),
-        buildValidatedCreateTestSuiteTool(),
-        buildValidatedSearchTestSuitesTool(),
-        buildValidatedDeleteTestSuiteTool(),
-        buildValidatedCreateTestCaseTool(),
-        buildValidatedUpdateTestCaseTool(),
-        buildValidatedDeleteTestCaseTool(),
-        buildValidatedRunTestSuiteTool(),
-        buildValidatedGetTestSuiteResultsTool(),
+        buildValidatedTriggerCrawlTool(ctx),
+        buildValidatedProjectTool(),
+        buildValidatedEnvironmentTool(),
+        buildValidatedTestSuiteTool(),
+        buildValidatedTestCaseTool(),
+        buildValidatedExecutionsTool(),
     ];
     _tools = tools;
     _validatedTools = validated;

package/dist/tools/project.js

@@ -0,0 +1,41 @@
+import { ProjectInputSchema } from '../types/index.js';
+import { projectHandler } from '../handlers/projectHandler.js';
+const DESCRIPTION = `Manage DebuggAI projects. Pass an "action":
+  - "get"    {uuid} → one project with full detail.
+  - "list"   {q?, page?, pageSize?} → paginated project summaries.
+  - "create" {name, platform, (teamUuid|teamName), (repoUuid|repoName)} → create a project. The repo must be GitHub-linked; names resolve by case-insensitive exact match.
+
+Note: there is no update/delete here — rename/delete a project from the DebuggAI web app.`;
+export function buildProjectTool() {
+    return {
+        name: 'project',
+        title: 'Project',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['get', 'list', 'create'], description: 'Operation to perform.' },
+                uuid: { type: 'string', description: '[get] Project UUID.' },
+                q: { type: 'string', description: '[list] Free-text search.' },
+                page: { type: 'number', description: '[list] Page (1-indexed).' },
+                pageSize: { type: 'number', description: '[list] Page size (1..200).' },
+                name: { type: 'string', description: '[create] Project name.' },
+                platform: { type: 'string', description: '[create] Platform, e.g. "web".' },
+                teamUuid: { type: 'string', description: '[create] Team UUID (or teamName).' },
+                teamName: { type: 'string', description: '[create] Team name (or teamUuid).' },
+                repoUuid: { type: 'string', description: '[create] GitHub repo UUID (or repoName).' },
+                repoName: { type: 'string', description: '[create] GitHub repo name "org/repo" (or repoUuid).' },
+            },
+            required: ['action'],
+            oneOf: [
+                { properties: { action: { const: 'get' } }, required: ['action', 'uuid'] },
+                { properties: { action: { const: 'list' } }, required: ['action'] },
+                { properties: { action: { const: 'create' } }, required: ['action', 'name', 'platform'] },
+            ],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedProjectTool() {
+    return { ...buildProjectTool(), inputSchema: ProjectInputSchema, handler: projectHandler };
+}

package/dist/tools/testCase.js

@@ -0,0 +1,40 @@
+import { TestCaseInputSchema } from '../types/index.js';
+import { testCaseHandler } from '../handlers/testCaseHandler.js';
+const DESCRIPTION = `Manage individual test cases within a suite. Pass an "action":
+  - "create" {name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?} → add a test case (NOT auto-run).
+  - "update" {testUuid, name?, description?, agentTaskDescription?} → patch a test case.
+  - "delete" {testUuid, confirm?} → soft-delete (DESTRUCTIVE; requires confirmation).`;
+export function buildTestCaseTool() {
+    return {
+        name: 'test_case',
+        title: 'Test Case',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['create', 'update', 'delete'], description: 'Operation to perform.' },
+                testUuid: { type: 'string', description: '[update/delete] Test case UUID.' },
+                name: { type: 'string', description: 'Test case name.' },
+                description: { type: 'string', description: 'Test case description.' },
+                agentTaskDescription: { type: 'string', description: "What the AI agent should do and verify." },
+                suiteUuid: { type: 'string', description: '[create] Suite UUID.' },
+                suiteName: { type: 'string', description: '[create] Suite name (requires a project identifier).' },
+                projectUuid: { type: 'string', description: '[create] Project UUID (or projectName).' },
+                projectName: { type: 'string', description: '[create] Project name (or projectUuid).' },
+                relativeUrl: { type: 'string', description: '[create] Starting path, must start with "/".' },
+                maxSteps: { type: 'number', description: '[create] Max agent steps (1..100).' },
+                confirm: { type: 'boolean', description: '[delete] Set true to confirm deletion (when the client cannot prompt).' },
+            },
+            required: ['action'],
+            oneOf: [
+                { properties: { action: { const: 'create' } }, required: ['action', 'name', 'description', 'agentTaskDescription'] },
+                { properties: { action: { const: 'update' } }, required: ['action', 'testUuid'] },
+                { properties: { action: { const: 'delete' } }, required: ['action', 'testUuid'] },
+            ],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedTestCaseTool() {
+    return { ...buildTestCaseTool(), inputSchema: TestCaseInputSchema, handler: testCaseHandler };
+}

package/dist/tools/testSuite.js

@@ -0,0 +1,50 @@
+import { TestSuiteInputSchema } from '../types/index.js';
+import { testSuiteHandler } from '../handlers/testSuiteHandler.js';
+const DESCRIPTION = `Manage and run test suites. Identify a suite by suiteUuid, or suiteName + a project identifier (projectUuid|projectName). Pass an "action":
+  - "list"    {projectUuid|projectName, search?, page?, pageSize?} → paginated suites with status/pass-rate.
+  - "create"  {name, description, projectUuid|projectName} → create a suite.
+  - "run"     {suiteUuid|(suiteName+project), targetUrl?} → run all tests async. Poll with action:"results".
+  - "results" {suiteUuid|(suiteName+project)} → suite + per-test outcomes.
+  - "delete"  {suiteUuid|(suiteName+project), confirm?} → soft-delete (DESTRUCTIVE; requires confirmation).`;
+const PROJECT_PROPS = {
+    projectUuid: { type: 'string', description: 'Project UUID (or projectName).' },
+    projectName: { type: 'string', description: 'Project name (or projectUuid).' },
+};
+const SUITE_PROPS = {
+    suiteUuid: { type: 'string', description: 'Test suite UUID.' },
+    suiteName: { type: 'string', description: 'Test suite name (requires a project identifier).' },
+};
+export function buildTestSuiteTool() {
+    return {
+        name: 'test_suite',
+        title: 'Test Suite',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list', 'create', 'run', 'results', 'delete'], description: 'Operation to perform.' },
+                ...SUITE_PROPS,
+                ...PROJECT_PROPS,
+                name: { type: 'string', description: '[create] Suite name.' },
+                description: { type: 'string', description: '[create] Suite description.' },
+                search: { type: 'string', description: '[list] Text filter over name/description.' },
+                page: { type: 'number', description: '[list] Page (1-indexed).' },
+                pageSize: { type: 'number', description: '[list] Page size (1..100).' },
+                targetUrl: { type: 'string', description: '[run] Override the default test target (full URL).' },
+                confirm: { type: 'boolean', description: '[delete] Set true to confirm deletion (when the client cannot prompt).' },
+            },
+            required: ['action'],
+            oneOf: [
+                { properties: { action: { const: 'list' } }, required: ['action'] },
+                { properties: { action: { const: 'create' } }, required: ['action', 'name', 'description'] },
+                { properties: { action: { const: 'run' } }, required: ['action'] },
+                { properties: { action: { const: 'results' } }, required: ['action'] },
+                { properties: { action: { const: 'delete' } }, required: ['action'] },
+            ],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedTestSuiteTool() {
+    return { ...buildTestSuiteTool(), inputSchema: TestSuiteInputSchema, handler: testSuiteHandler };
+}

package/dist/tools/triggerCrawl.js

@@ -71,10 +71,6 @@ export function buildTriggerCrawlTool(ctx) {
                     type: 'string',
                     description: 'The real password for the username above. Do NOT guess.',
                 },
-                headless: {
-                    type: 'boolean',
-                    description: 'Run the browser in headless mode. Defaults to backend configuration.',
-                },
                 timeoutSeconds: {
                     type: 'number',
                     description: 'Maximum wall-time the crawl may run, in seconds (1..1800). Backend enforces this per workflow execution.',