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

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.2.0]
+
+### Added — Structured tool output (`structuredContent`)
+
+Every successful tool result now carries [`structuredContent`](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
+— the parsed JSON payload — so clients can consume structured data directly
+instead of re-parsing the text blob. The text block is kept for back-compat.
+
+Promoted centrally in the CallTool path (`withStructuredContent` in
+`utils/structuredContent.ts`) rather than touching every handler. No-op for
+errors, non-object payloads, or multi-text results.
+
+`outputSchema` is intentionally not declared: the action tools return
+polymorphic shapes per action, a faithful schema would need top-level `oneOf`
+(which the Anthropic API rejects), and a permissive schema adds no value.
+`structuredContent` without a declared schema is spec-valid and is the win.
+
+## [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/index.js

@@ -21,7 +21,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { config } from "./config/index.js";
 import { initTools, getTools, getTool } from "./tools/index.js";
-import { Logger, validateInput, createErrorResponse, toMCPError, handleConfigurationError, Telemetry, TelemetryEvents, } from "./utils/index.js";
+import { Logger, validateInput, createErrorResponse, toMCPError, handleConfigurationError, Telemetry, TelemetryEvents, withStructuredContent, } from "./utils/index.js";
 import { MCPErrorCode, MCPError, } from "./types/index.js";
 // Logger and server are initialized lazily in main() to avoid triggering
 // config loading at module load time. If config validation fails (bad env vars),
@@ -116,7 +116,8 @@ function registerHandlers() {
             const toolDuration = Date.now() - toolStart;
             requestLogger.info(`Tool execution completed: ${name}`);
             Telemetry.capture(TelemetryEvents.TOOL_EXECUTED, { toolName: name, durationMs: toolDuration, success: true });
-            return result;
+            // Promote the JSON text payload to structuredContent (back-compat: text stays).
+            return withStructuredContent(result);
         }
         catch (error) {
             const mcpError = toMCPError(error, 'tool execution');

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/dist/utils/index.js

@@ -7,3 +7,4 @@ export * from './errors.js';
 export * from './projectAnalyzer.js';
 export * from './imageUtils.js';
 export * from './telemetry.js';
+export * from './structuredContent.js';

package/dist/utils/structuredContent.js

@@ -0,0 +1,42 @@
+/**
+ * Structured tool output (epic 3eb5l).
+ *
+ * MCP 2025-06-18 added `structuredContent` on tool results: a machine-readable
+ * JSON object that mirrors the human-readable text block. Clients that support
+ * it consume parsed data directly instead of re-parsing the text blob; the text
+ * block stays for back-compat.
+ *
+ * Every leaf handler already returns its payload as `JSON.stringify(payload)` in
+ * a single text item, so rather than touch ~20 handlers we promote it in ONE
+ * place — the CallTool path in index.ts wraps each result with this helper.
+ *
+ * We intentionally do NOT declare `outputSchema` on the tools: the action tools
+ * return polymorphic shapes per action, a faithful schema would need top-level
+ * `oneOf` (which the Anthropic API rejects, same as input schemas), and a
+ * permissive `type:object` schema adds no value. `structuredContent` without a
+ * declared schema is spec-valid and is the actual win.
+ */
+/**
+ * Attach `structuredContent` to a successful tool result when its single text
+ * block is a JSON object. No-op for errors, multi-text results, non-object
+ * payloads, or results that already set structuredContent.
+ */
+export function withStructuredContent(result) {
+    if (!result || result.isError || result.structuredContent)
+        return result;
+    const textItems = (result.content || []).filter((c) => c.type === 'text' && typeof c.text === 'string');
+    if (textItems.length !== 1)
+        return result;
+    let parsed;
+    try {
+        parsed = JSON.parse(textItems[0].text);
+    }
+    catch {
+        return result; // not JSON (shouldn't happen for our handlers) — leave as-is
+    }
+    // Spec requires structuredContent to be a JSON object (not array/primitive/null).
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return result;
+    }
+    return { ...result, structuredContent: parsed };
+}

package/package.json

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