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

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.3.0]
+
+### Added — Run artifacts returned as resource links
+
+`check_app_in_browser` and `executions {action:"get"}` now surface execution
+artifacts — **run recording, HAR, console log** — as MCP
+[`resource_link`](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
+content blocks pointing at their presigned URLs, instead of base64-inlining them.
+Leaner responses, and the URLs stay renewable / fetchable on demand. The legacy
+run-recording GIF (previously downloaded and inlined as multi-MB base64) is now a
+link; the `browserSession` presigned URLs are auto-detected and linked
+(deduped).
+
+Screenshots are **deliberately kept inline** as image blocks so vision-capable
+clients can still see them — the core visual-verification workflow. Helpers:
+`resourceLinkBlock` + `artifactResourceLinks` in `utils/imageUtils.ts`.
+
+## [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)

package/dist/handlers/searchExecutionsHandler.js

@@ -13,7 +13,7 @@ import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { config } from '../config/index.js';
 import { toPaginationParams } from '../utils/pagination.js';
-import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
+import { fetchImageAsBase64, imageContentBlock, resourceLinkBlock, artifactResourceLinks } from '../utils/imageUtils.js';
 const logger = new Logger({ module: 'searchExecutionsHandler' });
 function notFound(uuid) {
     return {
@@ -80,10 +80,25 @@ export async function searchExecutionsHandler(input, _context) {
                     if (img)
                         content.push(imageContentBlock(img.data, img.mimeType));
                 }
-                if (gifUrl) {
-                    const gif = await fetchImageAsBase64(gifUrl).catch(() => null);
-                    if (gif)
-                        content.push(imageContentBlock(gif.data, 'image/gif'));
+                // Artifact links (bead 8qndk): run recording (legacy GIF field) + the
+                // browserSession presigned URLs (HAR / console log / recording). Linked,
+                // not base64-inlined. Screenshot stays inline above for vision.
+                const artifactLinks = [
+                    ...(gifUrl
+                        ? [resourceLinkBlock(gifUrl, `run-recording-${input.uuid}.gif`, {
+                                mimeType: 'image/gif',
+                                title: 'Run recording',
+                                description: 'Animated recording of the execution (presigned URL — open or fetch on demand).',
+                            })]
+                        : []),
+                    ...artifactResourceLinks(execution.browserSession),
+                ];
+                const seenArtifactUris = new Set();
+                for (const link of artifactLinks) {
+                    if (link.uri && !seenArtifactUris.has(link.uri)) {
+                        seenArtifactUris.add(link.uri);
+                        content.push(link);
+                    }
                 }
                 return { content };
             }

package/dist/handlers/testPageChangesHandler.js

@@ -6,7 +6,7 @@
 import { config } from '../config/index.js';
 import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
-import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
+import { fetchImageAsBase64, imageContentBlock, resourceLinkBlock, artifactResourceLinks } from '../utils/imageUtils.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
@@ -539,11 +539,26 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             if (img)
                 content.push(imageContentBlock(img.data, img.mimeType));
         }
-        if (gifUrl) {
-            logger.info(`Embedding GIF/video: ${gifUrl}`);
-            const gif = await fetchImageAsBase64(gifUrl).catch(() => null);
-            if (gif)
-                content.push(imageContentBlock(gif.data, 'image/gif'));
+        // Artifact links (bead 8qndk): run recording (legacy GIF field) + the
+        // browserSession presigned URLs (HAR / console log / recording). Returned as
+        // resource_links, not base64-inlined. Screenshots stay inline above so
+        // vision-capable clients still SEE them.
+        const artifactLinks = [
+            ...(gifUrl
+                ? [resourceLinkBlock(gifUrl, 'run-recording.gif', {
+                        mimeType: 'image/gif',
+                        title: 'Run recording',
+                        description: 'Animated recording of the run (presigned URL — open or fetch on demand).',
+                    })]
+                : []),
+            ...artifactResourceLinks(sanitizedPayload.browserSession),
+        ];
+        const seenArtifactUris = new Set();
+        for (const link of artifactLinks) {
+            if (link.uri && !seenArtifactUris.has(link.uri)) {
+                seenArtifactUris.add(link.uri);
+                content.push(link);
+            }
         }
         return { content };
     }

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

@@ -39,3 +39,60 @@ function inferMimeFromUrl(url) {
 export function imageContentBlock(data, mimeType) {
     return { type: 'image', data, mimeType };
 }
+/**
+ * Build an MCP resource_link content block (MCP 2025-06-18) pointing at an
+ * (often presigned) artifact URL — leaner than inlining the bytes, and the URL
+ * stays renewable/on-demand. Use for large non-vision artifacts (run-recording
+ * GIFs, HAR, console logs) rather than base64-embedding them.
+ */
+export function resourceLinkBlock(uri, name, opts = {}) {
+    const block = { type: 'resource_link', uri, name };
+    if (opts.mimeType)
+        block.mimeType = opts.mimeType;
+    if (opts.title)
+        block.title = opts.title;
+    if (opts.description)
+        block.description = opts.description;
+    return block;
+}
+const MIME_BY_EXT = {
+    gif: 'image/gif', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg',
+    webp: 'image/webp', mp4: 'video/mp4', webm: 'video/webm',
+    har: 'application/json', json: 'application/json', txt: 'text/plain', log: 'text/plain',
+};
+function titleize(key) {
+    return key
+        .replace(/[_-]+/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .replace(/\bUrl\b|\bUri\b/gi, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^\w/, (c) => c.toUpperCase());
+}
+/**
+ * Build resource_link blocks for every (presigned) artifact URL found one level
+ * deep in `source` (e.g. an execution's browserSession: HAR, console log, run
+ * recording). Defensive about exact field names — it links any https value and
+ * skips tunnel/ngrok hosts. Returns [] for nullish/empty input.
+ */
+export function artifactResourceLinks(source) {
+    if (!source || typeof source !== 'object')
+        return [];
+    const out = [];
+    for (const [key, value] of Object.entries(source)) {
+        if (typeof value !== 'string')
+            continue;
+        if (!/^https?:\/\//i.test(value))
+            continue;
+        if (/ngrok|tunnel/i.test(value))
+            continue;
+        const ext = (value.split('?')[0].match(/\.([a-z0-9]+)$/i)?.[1] ?? '').toLowerCase();
+        const name = ext ? `${key}.${ext}` : key;
+        out.push(resourceLinkBlock(value, name, {
+            mimeType: MIME_BY_EXT[ext],
+            title: titleize(key),
+            description: 'Execution artifact (presigned URL — open or fetch on demand).',
+        }));
+    }
+    return out;
+}

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.1.0",
+  "version": "3.3.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {