@debugg-ai/debugg-ai-mcp 3.3.0 → 3.4.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.4.0]
+
+### Added — MCP Resources (browse projects / environments / executions)
+
+The server now declares the `resources` capability and exposes the read-only
+entities as addressable resources, so clients can browse and @-mention them as
+context instead of only calling tools:
+
+- **Collections** (`resources/list`): `debugg-ai://projects`, `debugg-ai://environments`, `debugg-ai://executions`
+- **Templates** (`resources/templates/list`): `debugg-ai://project/{uuid}`, `debugg-ai://environment/{uuid}`, `debugg-ai://execution/{uuid}`
+- **`resources/read`** dispatches each URI to the same entity handler the tools
+  use — identical data + auth, no drift — and returns the JSON payload.
+
+Additive: clients without resource support keep using the tools unchanged.
+Implementation in `handlers/resourcesHandler.ts`.
+
 ## [3.3.0]
 
 ### Added — Run artifacts returned as resource links

package/README.md

@@ -158,6 +158,24 @@ Every filter-mode response is paginated. Response shape:
 
 Pass optional `page` (1-indexed, default 1) and `pageSize` (default 20, max 200; oversized values are clamped). No response is ever silently truncated.
 
+## Resources
+
+Alongside tools, the server exposes the read-only entities as MCP **resources**
+so clients can browse and @-mention them as context:
+
+| URI | What |
+|---|---|
+| `debugg-ai://projects` | All projects (first page) |
+| `debugg-ai://environments` | Environments for the auto-detected project |
+| `debugg-ai://executions` | Recent executions (first page) |
+| `debugg-ai://project/{uuid}` | One project, full detail |
+| `debugg-ai://environment/{uuid}` | One environment (credentials inline, passwords redacted) |
+| `debugg-ai://execution/{uuid}` | One execution, full node detail + artifact links |
+
+Reads dispatch to the same handlers as the `project` / `environment` /
+`executions` tools, so the data and auth are identical. Resources are additive —
+clients without resource support keep using the tools.
+
 ### Security invariants
 
 - Passwords are write-only. They never appear in any response body from any tool.

package/dist/handlers/resourcesHandler.js

@@ -0,0 +1,127 @@
+/**
+ * MCP Resources (epic pglam).
+ *
+ * Exposes the read-only entities (projects / environments / executions) as
+ * addressable resources so clients can browse and @-mention them as context
+ * instead of (or alongside) calling the `project`/`environment`/`executions`
+ * tools. Reads reuse the exact tool handlers — same data, same auth, no drift.
+ *
+ *   Collections (resources/list):     debugg-ai://projects | environments | executions
+ *   Items (resources/templates/list): debugg-ai://project/{uuid}
+ *                                     debugg-ai://environment/{uuid}
+ *                                     debugg-ai://execution/{uuid}
+ *
+ * Resources are additive: clients that don't support the capability simply
+ * keep using the tools.
+ */
+import { config } from '../config/index.js';
+import { MCPError, MCPErrorCode, } from '../types/index.js';
+import { projectHandler } from './projectHandler.js';
+import { environmentHandler } from './environmentHandler.js';
+import { executionsHandler } from './executionsHandler.js';
+const SCHEME = 'debugg-ai';
+const JSON_MIME = 'application/json';
+/** Concrete collection resources returned by resources/list. */
+export const RESOURCE_COLLECTIONS = [
+    {
+        uri: `${SCHEME}://projects`,
+        name: 'projects',
+        title: 'DebuggAI Projects',
+        description: 'All projects visible to this API key (first page).',
+        mimeType: JSON_MIME,
+    },
+    {
+        uri: `${SCHEME}://environments`,
+        name: 'environments',
+        title: 'DebuggAI Environments',
+        description: 'Environments for the auto-detected project (credentials redacted).',
+        mimeType: JSON_MIME,
+    },
+    {
+        uri: `${SCHEME}://executions`,
+        name: 'executions',
+        title: 'DebuggAI Executions',
+        description: 'Recent workflow executions (first page).',
+        mimeType: JSON_MIME,
+    },
+];
+/** URI templates returned by resources/templates/list. */
+export const RESOURCE_TEMPLATES = [
+    {
+        uriTemplate: `${SCHEME}://project/{uuid}`,
+        name: 'project',
+        title: 'DebuggAI Project',
+        description: 'A single project by UUID, with full detail.',
+        mimeType: JSON_MIME,
+    },
+    {
+        uriTemplate: `${SCHEME}://environment/{uuid}`,
+        name: 'environment',
+        title: 'DebuggAI Environment',
+        description: 'A single environment by UUID, with credentials inline (passwords redacted).',
+        mimeType: JSON_MIME,
+    },
+    {
+        uriTemplate: `${SCHEME}://execution/{uuid}`,
+        name: 'execution',
+        title: 'DebuggAI Execution',
+        description: 'A single execution by UUID, with full node detail + artifact links.',
+        mimeType: JSON_MIME,
+    },
+];
+function readContext() {
+    return { timestamp: new Date() };
+}
+/** Pull the JSON payload that every entity handler emits as its single text block. */
+function payloadText(res) {
+    const text = res.content?.find((c) => c.type === 'text')?.text;
+    return typeof text === 'string' ? text : '{}';
+}
+// debugg-ai://<kind>            (collection)
+// debugg-ai://<kind>/<uuid>     (item)
+const URI_RE = new RegExp(`^${SCHEME}://([a-z]+)(?:/([^/?#]+))?$`);
+/**
+ * Resolve a debugg-ai:// resource URI by dispatching to the matching tool
+ * handler and wrapping its JSON payload as a resource content block.
+ */
+export async function readResource(uri) {
+    if (!config.api.key) {
+        throw new MCPError(MCPErrorCode.CONFIGURATION_ERROR, 'DEBUGGAI_API_KEY is not set. Configure it in your MCP server registration. Get a key at https://debugg.ai.', { missingEnvVars: ['DEBUGGAI_API_KEY'] });
+    }
+    const match = URI_RE.exec(uri);
+    if (!match) {
+        throw new MCPError(MCPErrorCode.INVALID_PARAMS, `Unrecognized resource URI: ${uri}`);
+    }
+    const [, kind, id] = match;
+    const ctx = readContext();
+    const requireId = () => {
+        if (!id) {
+            throw new MCPError(MCPErrorCode.INVALID_PARAMS, `Resource ${uri} requires a UUID: ${SCHEME}://${kind}/{uuid}`);
+        }
+        return id;
+    };
+    let res;
+    switch (kind) {
+        case 'projects':
+            res = await projectHandler({ action: 'list' }, ctx);
+            break;
+        case 'project':
+            res = await projectHandler({ action: 'get', uuid: requireId() }, ctx);
+            break;
+        case 'environments':
+            res = await environmentHandler({ action: 'list' }, ctx);
+            break;
+        case 'environment':
+            res = await environmentHandler({ action: 'get', uuid: requireId() }, ctx);
+            break;
+        case 'executions':
+            res = await executionsHandler({ action: 'list' }, ctx);
+            break;
+        case 'execution':
+            res = await executionsHandler({ action: 'get', uuid: requireId() }, ctx);
+            break;
+        default:
+            throw new MCPError(MCPErrorCode.INVALID_PARAMS, `Unknown resource kind "${kind}" in ${uri}`);
+    }
+    return { contents: [{ uri, mimeType: JSON_MIME, text: payloadText(res) }] };
+}

package/dist/index.js

@@ -18,9 +18,10 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { config } from "./config/index.js";
 import { initTools, getTools, getTool } from "./tools/index.js";
+import { readResource, RESOURCE_COLLECTIONS, RESOURCE_TEMPLATES } from "./handlers/resourcesHandler.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
@@ -39,6 +40,9 @@ function createMCPServer() {
             tools: {
                 listChanged: false,
             },
+            resources: {
+                listChanged: false,
+            },
         },
     });
 }
@@ -135,6 +139,28 @@ function registerHandlers() {
         logger.info('Tools list requested', { toolCount: tools.length });
         return { tools };
     });
+    // Resources (epic pglam): browse projects/environments/executions as
+    // addressable read URIs. Reads dispatch to the same entity handlers as the
+    // tools, so data + auth stay consistent.
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        logger.info('Resources list requested', { resourceCount: RESOURCE_COLLECTIONS.length });
+        return { resources: RESOURCE_COLLECTIONS };
+    });
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        return { resourceTemplates: RESOURCE_TEMPLATES };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        const uri = req.params?.uri;
+        logger.info('Resource read requested', { uri });
+        try {
+            return await readResource(uri);
+        }
+        catch (error) {
+            const mcpError = toMCPError(error, 'resource read');
+            logger.error('Resource read failed', { uri, errorCode: mcpError.code, message: mcpError.message });
+            throw mcpError;
+        }
+    });
 }
 /**
  * Main server initialization and startup

package/package.json

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