@debugg-ai/debugg-ai-mcp 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.1.0]
+
+### Added — Tool annotations (behavioral hints for clients)
+
+Every tool now declares MCP [tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
+so clients can reason about a tool before calling it (e.g. confirm-gate
+destructive ops, fast-path read-only ones):
+
+- `environment`, `test_suite`, `test_case` → `destructiveHint: true` (expose a delete action)
+- `executions`, `probe_page` → `readOnlyHint: true`
+- `project`, `check_app_in_browser`, `trigger_crawl` → write but non-destructive
+- all tools → `openWorldHint: true` (they reach the DebuggAI backend / live web)
+
+Annotations are advisory; deletes are still enforced server-side via the existing
+confirmation gate. Presets live in `tools/annotations.ts`.
+
 ## [3.0.1]
 
 ### Fixed — 5 action tools were invisible in Claude Code (and any Anthropic-API client)

package/dist/tools/annotations.js

@@ -0,0 +1,33 @@
+/**
+ * Tool annotation presets (epic p7gft).
+ *
+ * Annotations are *hints* (MCP 2025-03-26+) that let clients reason about a tool
+ * before calling it — e.g. confirm-gate destructive tools, fast-path read-only
+ * ones. They are advisory; the server still enforces real safety (deletes also
+ * require confirmation via confirmDestructive.ts).
+ *
+ * Every DebuggAI tool talks to the backend and/or the open web, so
+ * `openWorldHint` is true everywhere. `readOnlyHint`/`destructiveHint` reflect a
+ * tool's MOST powerful action — the action tools mix reads and writes under one
+ * name, so the annotation is the conservative worst case:
+ *   - READ_ONLY   : only get/list/probe — never mutates backend state
+ *   - WRITES      : can create/update/run (not read-only) but cannot delete
+ *   - DESTRUCTIVE : exposes a delete action (irreversible) — clients should confirm
+ *
+ * Per the spec, `destructiveHint`/`idempotentHint` are only meaningful when
+ * `readOnlyHint` is false, so READ_ONLY omits them.
+ */
+export const READ_ONLY = {
+    readOnlyHint: true,
+    openWorldHint: true,
+};
+export const WRITES = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+};
+export const DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+};

package/dist/tools/environment.js

@@ -1,5 +1,6 @@
 import { EnvironmentInputSchema } from '../types/index.js';
 import { environmentHandler } from '../handlers/environmentHandler.js';
+import { DESTRUCTIVE } from './annotations.js';
 const CRED_ITEM = {
     type: 'object',
     properties: {
@@ -18,6 +19,7 @@ export function buildEnvironmentTool() {
     return {
         name: 'environment',
         title: 'Environment',
+        annotations: DESTRUCTIVE,
         description: DESCRIPTION,
         inputSchema: {
             type: 'object',

package/dist/tools/executions.js

@@ -1,5 +1,6 @@
 import { ExecutionsInputSchema } from '../types/index.js';
 import { executionsHandler } from '../handlers/executionsHandler.js';
+import { READ_ONLY } from './annotations.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.
@@ -9,6 +10,7 @@ export function buildExecutionsTool() {
     return {
         name: 'executions',
         title: 'Workflow Executions',
+        annotations: READ_ONLY,
         description: DESCRIPTION,
         inputSchema: {
             type: 'object',

package/dist/tools/probePage.js

@@ -11,6 +11,7 @@
  */
 import { ProbePageInputSchema } from '../types/index.js';
 import { probePageHandler } from '../handlers/probePageHandler.js';
+import { READ_ONLY } from './annotations.js';
 const DESCRIPTION = `Probe one or more URLs and return their rendered state — screenshot, page metadata (title/finalUrl/statusCode/loadTimeMs), structured console errors, and per-URL network summary (refetch loops collapse into one row by origin+pathname).
 
 WHEN TO USE: "did I just break /settings?" / "smoke-test these 5 routes after my refactor" / "what's actually rendering at /dashboard?" — fast (<10s for 1 URL, <25s for 20), no LLM cost, no agent loop.
@@ -45,6 +46,7 @@ export function buildProbePageTool() {
     return {
         name: 'probe_page',
         title: 'Probe Page',
+        annotations: READ_ONLY,
         description: DESCRIPTION,
         inputSchema: {
             type: 'object',

package/dist/tools/project.js

@@ -1,5 +1,6 @@
 import { ProjectInputSchema } from '../types/index.js';
 import { projectHandler } from '../handlers/projectHandler.js';
+import { WRITES } from './annotations.js';
 const DESCRIPTION = `Manage DebuggAI projects. Pass an "action":
   - "get"    {uuid} → one project with full detail.
   - "list"   {q?, page?, pageSize?} → paginated project summaries.
@@ -10,6 +11,7 @@ export function buildProjectTool() {
     return {
         name: 'project',
         title: 'Project',
+        annotations: WRITES,
         description: DESCRIPTION,
         inputSchema: {
             type: 'object',

package/dist/tools/testCase.js

@@ -1,5 +1,6 @@
 import { TestCaseInputSchema } from '../types/index.js';
 import { testCaseHandler } from '../handlers/testCaseHandler.js';
+import { DESTRUCTIVE } from './annotations.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.
@@ -8,6 +9,7 @@ export function buildTestCaseTool() {
     return {
         name: 'test_case',
         title: 'Test Case',
+        annotations: DESTRUCTIVE,
         description: DESCRIPTION,
         inputSchema: {
             type: 'object',

package/dist/tools/testPageChanges.js

@@ -5,6 +5,7 @@
  */
 import { TestPageChangesInputSchema } from '../types/index.js';
 import { testPageChangesHandler } from '../handlers/testPageChangesHandler.js';
+import { WRITES } from './annotations.js';
 const BASE_DESCRIPTION = `Give an AI agent eyes on a live website or app. The agent browses it, interacts with it, and tells you whether a given task or check passed. Works on localhost or any URL. Use for visual QA, flow validation, regression checks, or anything that needs a real browser to verify.
 
 LOCALHOST SUPPORT: Pass any localhost URL (e.g. http://localhost:3000) and it Just Works. A secure tunnel is automatically created so the remote browser can reach your local dev server — no manual ngrok setup, no port forwarding, no config.
@@ -43,6 +44,7 @@ export function buildTestPageChangesTool(ctx) {
     return {
         name: "check_app_in_browser",
         title: "Run E2E Browser Test",
+        annotations: WRITES,
         description: buildToolDescription(ctx),
         inputSchema: {
             type: "object",

package/dist/tools/testSuite.js

@@ -1,5 +1,6 @@
 import { TestSuiteInputSchema } from '../types/index.js';
 import { testSuiteHandler } from '../handlers/testSuiteHandler.js';
+import { DESTRUCTIVE } from './annotations.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.
@@ -18,6 +19,7 @@ export function buildTestSuiteTool() {
     return {
         name: 'test_suite',
         title: 'Test Suite',
+        annotations: DESTRUCTIVE,
         description: DESCRIPTION,
         inputSchema: {
             type: 'object',

package/dist/tools/triggerCrawl.js

@@ -5,6 +5,7 @@
  */
 import { TriggerCrawlInputSchema } from '../types/index.js';
 import { triggerCrawlHandler } from '../handlers/triggerCrawlHandler.js';
+import { WRITES } from './annotations.js';
 const BASE_DESCRIPTION = `Trigger a browser-agent crawl of a web app to build the project's knowledge graph. The crawl systematically explores pages, UI states, and navigation flows, then populates the backend's knowledge graph so future evaluations and tests have context about the app.
 
 LOCALHOST SUPPORT: Pass any localhost URL (e.g. http://localhost:3000) and it Just Works. A secure tunnel is automatically created so the remote browser can reach your local dev server.
@@ -39,6 +40,7 @@ export function buildTriggerCrawlTool(ctx) {
     return {
         name: 'trigger_crawl',
         title: 'Trigger App Crawl',
+        annotations: WRITES,
         description: buildTriggerCrawlDescription(ctx),
         inputSchema: {
             type: 'object',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {