@debugg-ai/debugg-ai-mcp 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.5.0]
+
+### Added — Remote transport: Streamable HTTP + OAuth Resource Server (opt-in)
+
+The server can now run as a hosted, multi-user remote MCP over **stateless
+Streamable HTTP**, in addition to the default stdio transport (which is
+unchanged). Enable with `DEBUGGAI_MCP_TRANSPORT=http` (+ `PORT`, default 3000).
+
+As an OAuth **Resource Server** (MCP 2025-06-18):
+- Each `POST /mcp` request must carry `Authorization: Bearer <token>`; the token
+  is request-scoped (AsyncLocalStorage) and used as the backend credential —
+  `api.debugg.ai` is the validator, so no token-verification keys live here.
+- Missing/invalid token → `401` with `WWW-Authenticate: Bearer resource_metadata=…`.
+- Serves RFC 9728 metadata at `/.well-known/oauth-protected-resource` advertising
+  the authorization server (`auth.debugg.ai`), so clients run the OAuth flow and
+  retry with a token.
+- `GET /health` for load-balancer / ECS health checks.
+
+Auth became request-scoped without touching the ~20 backend-client call sites:
+`config.api.key` resolves the per-request token when set (`utils/requestContext.ts`).
+Config env: `DEBUGGAI_MCP_TRANSPORT`, `PORT`, `DEBUGGAI_MCP_PUBLIC_URL`,
+`DEBUGGAI_OAUTH_ISSUER`, `DEBUGGAI_TOKEN_TYPE=bearer`. stdio installs need none of these.
+
 ## [3.4.0]
 
 ### Added — MCP Resources (browse projects / environments / executions)

package/README.md

@@ -234,6 +234,37 @@ Response-shape changes: the bare `count` field on list responses is gone — use
 DEBUGGAI_API_KEY=your_api_key
 ```
 
+## Remote / HTTP transport (optional)
+
+By default the server speaks **stdio** (local `npx`). It can instead run as a
+hosted, multi-user remote MCP over **stateless Streamable HTTP** + OAuth:
+
+```bash
+DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest
+```
+
+It is an OAuth **Resource Server**: every `POST /mcp` needs
+`Authorization: Bearer <token>`; missing/invalid tokens get a `401` with a
+`WWW-Authenticate` pointing at the RFC 9728 metadata, and clients run the OAuth
+flow against the advertised authorization server. The bearer is request-scoped —
+`api.debugg.ai` validates it.
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /mcp` | MCP Streamable HTTP (bearer-protected) |
+| `GET /.well-known/oauth-protected-resource` | RFC 9728 metadata (authorization server discovery) |
+| `GET /health` | Load-balancer / ECS health check |
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `DEBUGGAI_MCP_TRANSPORT` | `stdio` | Set to `http` for the remote transport |
+| `PORT` | `3000` | HTTP listen port |
+| `DEBUGGAI_MCP_PUBLIC_URL` | `https://mcp.debugg.ai` | This server's public resource URL (RFC 9728 `resource`) |
+| `DEBUGGAI_OAUTH_ISSUER` | `https://auth.debugg.ai` | Authorization server advertised to clients |
+| `DEBUGGAI_TOKEN_TYPE` | `token` | Set to `bearer` so OAuth tokens forward as `Authorization: Bearer` |
+
+stdio installs need none of these.
+
 ## Telemetry
 
 The MCP server ships with telemetry enabled by default — an embedded write-only PostHog project key (`phc_*`) so the team can observe cache hit rates, poll cadence, tunnel reliability, and other operational metrics across the install base. Captured events:

package/dist/config/index.js

@@ -5,6 +5,7 @@ import { z } from 'zod';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { currentApiKey } from '../utils/requestContext.js';
 function findPackageVersion() {
     const __dir = dirname(fileURLToPath(import.meta.url));
     let dir = __dir;
@@ -113,7 +114,14 @@ let _config;
 export const config = {
     get server() { return getConfig().server; },
     get devMode() { return getConfig().devMode; },
-    get api() { return getConfig().api; },
+    // api.key is request-scoped under the HTTP transport: if a per-request token
+    // is set (AsyncLocalStorage), it overrides the env key for that request only.
+    // stdio / tests have no request store, so the env key is returned unchanged.
+    get api() {
+        const api = getConfig().api;
+        const requestKey = currentApiKey();
+        return requestKey ? { ...api, key: requestKey } : api;
+    },
     get defaults() { return getConfig().defaults; },
     get logging() { return getConfig().logging; },
     get telemetry() { return getConfig().telemetry; },

package/dist/httpServer.js

@@ -0,0 +1,134 @@
+/**
+ * Streamable HTTP transport + OAuth Resource Server (epic lybfq).
+ *
+ * Opt-in remote transport: `DEBUGGAI_MCP_TRANSPORT=http` (stdio stays default).
+ * Stateless (no session id) so it scales behind a plain load balancer.
+ *
+ * Auth model — the MCP server is an OAuth **Resource Server**:
+ *   - Every /mcp request must carry `Authorization: Bearer <token>`.
+ *   - The token is stashed per-request (AsyncLocalStorage) and used as the
+ *     backend credential; api.debugg.ai is the real validator (a bad token 401s
+ *     on the first backend call). No token verification keys live here.
+ *   - Missing token → 401 + `WWW-Authenticate: Bearer resource_metadata=...`,
+ *     and we serve RFC 9728 metadata at /.well-known/oauth-protected-resource
+ *     pointing clients at auth.debugg.ai to run the OAuth flow.
+ *
+ * Deployment note: set DEBUGGAI_TOKEN_TYPE=bearer so the backend client forwards
+ * the OAuth token as `Authorization: Bearer` (not `Token`).
+ */
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { runWithApiKey } from './utils/requestContext.js';
+const PUBLIC_URL = (process.env.DEBUGGAI_MCP_PUBLIC_URL || 'https://mcp.debugg.ai').replace(/\/+$/, '');
+const OAUTH_ISSUER = (process.env.DEBUGGAI_OAUTH_ISSUER || 'https://auth.debugg.ai').replace(/\/+$/, '');
+const RESOURCE_METADATA_PATH = '/.well-known/oauth-protected-resource';
+const MCP_PATH = '/mcp';
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+/** RFC 9728 protected-resource metadata: tells clients which AS issues tokens. */
+export function protectedResourceMetadata() {
+    return {
+        resource: PUBLIC_URL,
+        authorization_servers: [OAUTH_ISSUER],
+        bearer_methods_supported: ['header'],
+    };
+}
+/** Extract the token from `Authorization: Bearer <t>` (or `Token <t>`). */
+export function bearerToken(authHeader) {
+    if (!authHeader)
+        return undefined;
+    const m = /^(?:Bearer|Token)\s+(.+)$/i.exec(authHeader.trim());
+    return m ? m[1].trim() : undefined;
+}
+function sendJson(res, code, body, extraHeaders = {}) {
+    const data = JSON.stringify(body);
+    res.writeHead(code, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(data),
+        ...extraHeaders,
+    });
+    res.end(data);
+}
+function unauthorized(res) {
+    const metadataUrl = `${PUBLIC_URL}${RESOURCE_METADATA_PATH}`;
+    sendJson(res, 401, { error: 'unauthorized', error_description: 'Missing or invalid bearer token; authenticate via the linked authorization server.' }, { 'WWW-Authenticate': `Bearer resource_metadata="${metadataUrl}"` });
+}
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        let aborted = false;
+        req.on('data', (chunk) => {
+            data += chunk;
+            if (data.length > MAX_BODY_BYTES && !aborted) {
+                aborted = true;
+                reject(new Error('request body too large'));
+            }
+        });
+        req.on('end', () => {
+            if (aborted)
+                return;
+            if (!data)
+                return resolve(undefined);
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        req.on('error', reject);
+    });
+}
+/** Start the stateless Streamable HTTP server. Resolves to the listening server. */
+export async function startHttpServer(opts) {
+    const { port, buildServer, logger } = opts;
+    const httpServer = createServer(async (req, res) => {
+        const path = new URL(req.url || '/', 'http://localhost').pathname;
+        // ECS / LB health check — no auth.
+        if (path === '/health' && req.method === 'GET') {
+            return sendJson(res, 200, { status: 'ok' });
+        }
+        // RFC 9728 protected-resource metadata — public discovery, no auth.
+        if (path === RESOURCE_METADATA_PATH && req.method === 'GET') {
+            return sendJson(res, 200, protectedResourceMetadata());
+        }
+        if (path === MCP_PATH) {
+            const token = bearerToken(req.headers['authorization']);
+            if (!token) {
+                logger.info('HTTP MCP request without bearer token → 401');
+                return unauthorized(res);
+            }
+            let body;
+            if (req.method === 'POST') {
+                try {
+                    body = await readJsonBody(req);
+                }
+                catch {
+                    return sendJson(res, 400, { error: 'invalid_request', error_description: 'Request body must be valid JSON' });
+                }
+            }
+            // Stateless: a fresh server + transport per request, scoped to this
+            // request's bearer token via AsyncLocalStorage (so config.api.key resolves
+            // to it for every backend call made while handling this request).
+            const srv = buildServer();
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            res.on('close', () => {
+                transport.close().catch(() => { });
+                srv.close().catch(() => { });
+            });
+            try {
+                await srv.connect(transport);
+                await runWithApiKey(token, () => transport.handleRequest(req, res, body));
+            }
+            catch (error) {
+                logger.error('HTTP MCP request failed', { error: error instanceof Error ? error.message : String(error) });
+                if (!res.headersSent)
+                    sendJson(res, 500, { error: 'internal_error' });
+            }
+            return;
+        }
+        sendJson(res, 404, { error: 'not_found' });
+    });
+    await new Promise((resolve) => httpServer.listen(port, resolve));
+    logger.info('HTTP transport listening', { port, resource: PUBLIC_URL, authorizationServer: OAUTH_ISSUER });
+    return httpServer;
+}

package/dist/index.js

@@ -49,12 +49,12 @@ function createMCPServer() {
 /**
  * Create progress callback for tool execution
  */
-function createProgressCallback(progressToken) {
+function createProgressCallback(srv, progressToken) {
     if (!progressToken)
         return undefined;
     return async ({ progress, total, message }) => {
         try {
-            await server.notification({
+            await srv.notification({
                 method: "notifications/progress",
                 params: {
                     progressToken,
@@ -76,10 +76,21 @@ function createProgressCallback(progressToken) {
     };
 }
 /**
- * Register MCP request handlers. Called in main() after server is created.
+ * Build a fully-configured MCP Server (capabilities + all request handlers).
+ * The HTTP transport calls this once per request for stateless isolation; main()
+ * uses it for the long-lived stdio server.
  */
-function registerHandlers() {
-    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+export function buildConfiguredServer() {
+    const srv = createMCPServer();
+    registerHandlers(srv);
+    return srv;
+}
+/**
+ * Register MCP request handlers on a server instance. Called for the stdio
+ * singleton in main(), and once per request by the HTTP transport (stateless).
+ */
+function registerHandlers(srv) {
+    srv.setRequestHandler(CallToolRequestSchema, async (req) => {
         const typedReq = req;
         const requestId = `req_${Date.now()}`;
         const requestLogger = logger.child({ requestId });
@@ -113,7 +124,7 @@ function registerHandlers() {
                 requestId,
                 timestamp: new Date(),
             };
-            const progressCallback = createProgressCallback(typeof progressToken === 'string' || typeof progressToken === 'number' ? String(progressToken) : undefined);
+            const progressCallback = createProgressCallback(srv, typeof progressToken === 'string' || typeof progressToken === 'number' ? String(progressToken) : undefined);
             requestLogger.info(`Executing tool: ${name}`);
             const toolStart = Date.now();
             const result = await tool.handler(validatedInput, context, progressCallback);
@@ -134,7 +145,7 @@ function registerHandlers() {
             return createErrorResponse(mcpError, typedReq.params.name);
         }
     });
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
+    srv.setRequestHandler(ListToolsRequestSchema, async () => {
         const tools = getTools();
         logger.info('Tools list requested', { toolCount: tools.length });
         return { tools };
@@ -142,14 +153,14 @@ function registerHandlers() {
     // 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 () => {
+    srv.setRequestHandler(ListResourcesRequestSchema, async () => {
         logger.info('Resources list requested', { resourceCount: RESOURCE_COLLECTIONS.length });
         return { resources: RESOURCE_COLLECTIONS };
     });
-    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+    srv.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
         return { resourceTemplates: RESOURCE_TEMPLATES };
     });
-    server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+    srv.setRequestHandler(ReadResourceRequestSchema, async (req) => {
         const uri = req.params?.uri;
         logger.info('Resource read requested', { uri });
         try {
@@ -170,19 +181,18 @@ async function main() {
         // Initialize logger and server here (not at module load time) so config
         // validation errors are caught by this try-catch instead of crashing.
         logger = new Logger({ module: 'main' });
-        server = createMCPServer();
-        // Register request handlers (they reference the `server` variable)
-        registerHandlers();
+        const transportMode = (process.env.DEBUGGAI_MCP_TRANSPORT || 'stdio').toLowerCase();
         logger.info('Starting DebuggAI MCP Server', {
             nodeVersion: process.version,
             platform: process.platform,
             architecture: process.arch,
-            pid: process.pid
+            pid: process.pid,
+            transport: transportMode,
         });
-        // NOTE: DEBUGGAI_API_KEY validation is deferred to the first tool call so
-        // MCP clients see a proper initialize response + a structured tool error,
-        // rather than the subprocess dying with "Failed to reconnect" (bead cma).
-        if (!config.api.key) {
+        // stdio is single-user: the API key comes from the environment and is
+        // validated at first tool call (bead cma). HTTP is multi-user: each request
+        // carries its own bearer token, so a missing env key at boot is expected.
+        if (transportMode !== 'http' && !config.api.key) {
             logger.warn('DEBUGGAI_API_KEY is not set. Server will boot but every tool call will return a ConfigurationError until the env var is configured.');
         }
         // Initialize telemetry: PostHog by default (public project key embedded
@@ -206,12 +216,28 @@ async function main() {
         // No API calls at boot. Project context is resolved lazily on first tool
         // invocation (list_environments / list_credentials / check_app_in_browser).
         initTools(null);
-        const transport = new StdioServerTransport();
-        await server.connect(transport);
-        logger.info('DebuggAI MCP Server is running and ready to accept requests', {
-            transport: 'stdio',
-            toolsAvailable: getTools().map(t => t.name),
-        });
+        if (transportMode === 'http') {
+            // Remote/hosted transport (epic lybfq): stateless Streamable HTTP + OAuth
+            // Resource Server. stdio stays the default and is unaffected.
+            const { startHttpServer } = await import('./httpServer.js');
+            const port = Number(process.env.PORT) || 3000;
+            await startHttpServer({ port, buildServer: buildConfiguredServer, logger });
+            logger.info('DebuggAI MCP Server is running and ready to accept requests', {
+                transport: 'http',
+                port,
+                toolsAvailable: getTools().map(t => t.name),
+            });
+        }
+        else {
+            server = createMCPServer();
+            registerHandlers(server);
+            const transport = new StdioServerTransport();
+            await server.connect(transport);
+            logger.info('DebuggAI MCP Server is running and ready to accept requests', {
+                transport: 'stdio',
+                toolsAvailable: getTools().map(t => t.name),
+            });
+        }
     }
     catch (error) {
         logger.error('Failed to start DebuggAI MCP Server', {

package/dist/utils/requestContext.js

@@ -0,0 +1,24 @@
+/**
+ * Request-scoped context (epic lybfq).
+ *
+ * stdio is single-user: one API key from the environment for the whole process.
+ * The HTTP transport is multi-user: each request carries its own bearer token.
+ * Rather than thread a token through every handler + backend-client call site,
+ * we stash it in AsyncLocalStorage for the duration of the request and let
+ * `config.api.key` resolve it (see config/index.ts). Outside an HTTP request
+ * (i.e. stdio, or tests) the store is empty and the env key is used — so the
+ * stdio path is completely unchanged.
+ *
+ * This module intentionally has NO imports so any layer (incl. config) can use
+ * it without creating an import cycle.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+/** Run `fn` with a request-scoped API key (used by the HTTP transport per request). */
+export function runWithApiKey(apiKey, fn) {
+    return storage.run({ apiKey }, fn);
+}
+/** The request-scoped API key if inside runWithApiKey(), else undefined (stdio). */
+export function currentApiKey() {
+    return storage.getStore()?.apiKey;
+}

package/package.json

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