@debugai/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DebugAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# @debugai/mcp
+
+DebugAI as an MCP server. Your agent hands an error to `debug_error` and gets
+back the root cause plus up to 3 ranked fixes with code patches. Works in
+Claude Desktop, Claude Code, Cursor, Zed, Windsurf, and any other MCP client.
+
+Until now this server only shipped inside the
+[DebugAI VS Code extension](https://marketplace.visualstudio.com/items?itemName=debugai.debugai).
+This package is the same server, standalone. No VS Code required.
+
+## Setup
+
+1. Create a free account at [debugai.io](https://debugai.io) (10 debugs/day, no card).
+2. Copy your API key (`dbg_...`) from [debugai.io/dashboard](https://debugai.io/dashboard).
+3. Add the server to your MCP client (snippets below). Node 18+ required.
+
+### Claude Code
+
+```bash
+claude mcp add debugai --env DEBUGAI_API_KEY=dbg_your_key_here -- npx -y @debugai/mcp
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json` (Settings, Developer, Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "debugai": {
+      "command": "npx",
+      "args": ["-y", "@debugai/mcp"],
+      "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (or `.cursor/mcp.json` per project):
+
+```json
+{
+  "mcpServers": {
+    "debugai": {
+      "command": "npx",
+      "args": ["-y", "@debugai/mcp"],
+      "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
+    }
+  }
+}
+```
+
+### Zed
+
+`settings.json`:
+
+```json
+{
+  "context_servers": {
+    "debugai": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "@debugai/mcp"],
+        "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "debugai": {
+      "command": "npx",
+      "args": ["-y", "@debugai/mcp"],
+      "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
+    }
+  }
+}
+```
+
+### VS Code
+
+You don't need this package. The
+[DebugAI extension](https://marketplace.visualstudio.com/items?itemName=debugai.debugai)
+registers the MCP server automatically (VS Code 1.101+) and adds one-click
+fix apply, proactive scan, and codebase indexing on top.
+
+## The tool
+
+### `debug_error`
+
+Give it an error, get an analysis.
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| `errorText` | yes | Full error message, exception, or stack trace. |
+| `language` | no | `javascript`, `typescript`, `python`, `go`, `rust`, or `auto` (default). |
+| `codeSnippet` | no | Code around the failing line, if the agent has it. |
+| `filePath` | no | Path to the file that threw. |
+
+Returns the root cause, up to 3 fixes ranked by confidence (with code
+patches), the detected framework, and whether the answer came from cache.
+Read-only: it never touches your files. Applying a fix is your agent's
+(and your) call.
+
+Example, in Claude Code:
+
+> Paste a traceback and ask "why is this failing?". Claude calls
+> `debug_error` and gets back something like:
+>
+> **Root cause:** `db.session` is used after the request context closed.
+> **Fix 1 (94% confidence):** move the query inside the request handler...
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEBUGAI_API_KEY` | (none) | Your API key. Required for real analyses. |
+| `DEBUGAI_API_BASE` | DebugAI production | Override for self-hosted or staging setups. |
+| `DEBUGAI_TIMEOUT_MS` | `150000` | Per-request deadline. Deep analyses can take 30-90s. |
+
+## Limits and honesty
+
+- Free tier: 10 debugs/day. Pro ($12/mo): 1,000/mo soft cap, never hard-blocked at it.
+- When you hit the daily cap the tool says so and stops. It will not silently retry.
+- Simple errors route to a fast model; ugly cross-file ones route to a
+  stronger one on paid tiers. The `Model:` badge in each response tells you
+  which one answered.
+- Analyses run on DebugAI's servers. The error text and any snippet you pass
+  are sent there. Privacy policy: [debugai.io/privacy](https://debugai.io/privacy).
+
+## Troubleshooting
+
+- **"authentication failed"**: key missing or wrong. Check the `env` block in
+  your client config, restart the client. Keys start with `dbg_`.
+- **Nothing happens on `npx @debugai/mcp`**: correct. It's a stdio server that
+  waits for an MCP client to speak first. Run `npx @debugai/mcp --help` to
+  verify the install.
+- **Timeouts**: deep analyses can take up to 90s. If your client has its own
+  tool timeout, raise it above that.
+
+## Development
+
+```bash
+npm install
+npm test        # builds, then runs unit + spawned-process e2e tests
+```
+
+MIT © DebugAI

package/dist/backend.d.ts

@@ -0,0 +1,42 @@
+export interface DebugRequest {
+    error_message: string;
+    code_snippet?: string;
+    language?: string;
+    file_path?: string;
+    project_id?: string;
+    framework_hint?: string;
+}
+export interface DebugFix {
+    rank: number;
+    title: string;
+    description: string;
+    confidence: number;
+    code?: string;
+    line_hint?: string;
+}
+export interface DebugResponse {
+    root_cause: string;
+    fixes: DebugFix[];
+    framework_detected?: string;
+    model_used?: string;
+    cached?: boolean;
+    has_project_context?: boolean;
+    related_files_count?: number;
+    confidence_level?: string;
+    pattern_matched?: string;
+    remaining_today?: number;
+    mock?: boolean;
+}
+export interface BackendConfig {
+    apiKey: string;
+    apiBase: string;
+    version: string;
+    /** Whole-request deadline in ms. Claude analysis runs 30-90s; nginx cuts at 120s. */
+    timeoutMs?: number;
+}
+export interface BackendError extends Error {
+    status: number;
+    retryAfterSeconds: number;
+}
+export declare const DEFAULT_TIMEOUT_MS = 150000;
+export declare function callDebugBackend(req: DebugRequest, config: BackendConfig): Promise<DebugResponse>;

package/dist/backend.js

@@ -0,0 +1,38 @@
+export const DEFAULT_TIMEOUT_MS = 150_000;
+function makeBackendError(message, status, retryAfterSeconds = 0) {
+    return Object.assign(new Error(message), { status, retryAfterSeconds });
+}
+export async function callDebugBackend(req, config) {
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetch(`${config.apiBase}/debug`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': config.apiKey,
+                'user-agent': `debugai-mcp/${config.version}`,
+            },
+            body: JSON.stringify(req),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (controller.signal.aborted) {
+            throw makeBackendError(`DebugAI request timed out after ${Math.round(timeoutMs / 1000)}s`, 504);
+        }
+        // DNS failure, refused connection, no network — status 0 marks "never reached the API"
+        throw makeBackendError(`Could not reach the DebugAI API at ${config.apiBase}: ${err?.message ?? String(err)}`, 0);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        const retryAfter = Number(res.headers.get('retry-after') ?? 0);
+        throw makeBackendError(text || res.statusText, res.status, retryAfter);
+    }
+    return res.json();
+}

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare function mapBackendErrorToToolResult(err: unknown): CallToolResult;

package/dist/errors.js

@@ -0,0 +1,119 @@
+const PRICING_URL = 'https://debugai.io/pricing';
+const DASHBOARD_URL = 'https://debugai.io/dashboard';
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export function mapBackendErrorToToolResult(err) {
+    const status = err?.status ?? 0;
+    const message = err?.message ?? String(err);
+    const retry = err?.retryAfterSeconds ?? 60;
+    if (status === 401 || status === 403) {
+        return {
+            isError: true,
+            content: [{
+                    type: 'text',
+                    text: 'DebugAI authentication failed: API key missing, invalid, or expired. ' +
+                        `Tell the user to get their API key at ${DASHBOARD_URL} and set it as the ` +
+                        'DEBUGAI_API_KEY environment variable in their MCP client config (the "env" block ' +
+                        'for the debugai server entry), then restart the MCP client and retry.',
+                }],
+            structuredContent: {
+                error_type: 'auth_failed',
+                dashboard_url: DASHBOARD_URL,
+                retryable: false,
+            },
+        };
+    }
+    // 402 Payment Required — quota exhausted (NOT a transient rate limit).
+    // Agents must NOT retry. They must surface the upgrade URL to the user.
+    if (status === 402) {
+        const body = tryParseJson(message) ?? {};
+        const tier = body.tier ?? 'free';
+        const limit = body.limit ?? 10;
+        const resets = body.resets_at ?? 'midnight UTC';
+        const upgrade = body.upgrade_url ?? PRICING_URL;
+        return {
+            isError: true,
+            content: [{
+                    type: 'text',
+                    text: `DebugAI ${tier} tier daily quota reached (${limit} debugs/day). ` +
+                        `Resets at ${resets}. ` +
+                        `IMPORTANT: This is NOT a transient rate limit — do NOT retry this call. ` +
+                        `Tell the user to upgrade to Pro for more debugging: ${upgrade}. ` +
+                        `Pro is $12/month, lifts the daily cap, and gives unlimited sessions (soft cap 1,000/mo).`,
+                }],
+            structuredContent: {
+                error_type: 'quota_exceeded',
+                tier,
+                daily_limit: limit,
+                resets_at: resets,
+                upgrade_url: upgrade,
+                retryable: false,
+            },
+        };
+    }
+    if (status === 429) {
+        return {
+            isError: true,
+            content: [{
+                    type: 'text',
+                    text: `DebugAI rate limit hit (transient). Retry after ${retry} seconds. ` +
+                        `Do NOT retry this call immediately — inform the user and wait for the cooldown. ` +
+                        `Upgrade for higher limits: ${DASHBOARD_URL}`,
+                }],
+            structuredContent: {
+                error_type: 'rate_limited',
+                retry_after_seconds: retry,
+                retryable: true,
+            },
+        };
+    }
+    if (status === 503 || status === 504) {
+        return {
+            isError: true,
+            content: [{
+                    type: 'text',
+                    text: `DebugAI engine temporarily unavailable (HTTP ${status}). ` +
+                        `Tell the user this is a transient issue and to retry in 30-60 seconds. ` +
+                        `Check status at https://status.debugai.io if it persists.`,
+                }],
+            structuredContent: {
+                error_type: 'engine_unavailable',
+                status,
+                retryable: true,
+            },
+        };
+    }
+    // status 0 — the request never reached the API (DNS, refused, offline)
+    if (status === 0) {
+        return {
+            isError: true,
+            content: [{
+                    type: 'text',
+                    text: `${message}. The user may be offline, behind a proxy, or DEBUGAI_API_BASE may be ` +
+                        `misconfigured. Retry once the network is available.`,
+                }],
+            structuredContent: {
+                error_type: 'network_error',
+                retryable: true,
+            },
+        };
+    }
+    return {
+        isError: true,
+        content: [{
+                type: 'text',
+                text: `DebugAI request failed: ${message}. The user can retry shortly.`,
+            }],
+        structuredContent: {
+            error_type: 'unknown',
+            status,
+            retryable: true,
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+import { DEFAULT_TIMEOUT_MS } from './backend.js';
+const DEFAULT_API_BASE = 'https://debugai-mvp-production.up.railway.app/api';
+function packageVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+        return JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+const VERSION = packageVersion();
+const HELP = `debugai-mcp v${VERSION} — DebugAI MCP server (stdio)
+
+Exposes the debug_error tool to any MCP client: hand it an error or stack
+trace, get root cause + ranked fixes from DebugAI.
+
+Usage:
+  npx @debugai/mcp                # start the server (stdio transport)
+  npx @debugai/mcp --version
+  npx @debugai/mcp --help
+
+Environment:
+  DEBUGAI_API_KEY      required — your API key (dbg_...) from https://debugai.io/dashboard
+  DEBUGAI_API_BASE     optional — API base URL (default: DebugAI production)
+  DEBUGAI_TIMEOUT_MS   optional — per-request deadline in ms (default: ${DEFAULT_TIMEOUT_MS})
+
+This is a stdio MCP server: it is meant to be launched BY an MCP client
+(Claude Desktop, Claude Code, Cursor, Zed, ...), not run interactively.
+Config snippets: https://www.npmjs.com/package/@debugai/mcp
+`;
+// stdout carries the MCP protocol — every human-facing line goes to stderr.
+function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--version') || args.includes('-v')) {
+        process.stdout.write(`${VERSION}\n`);
+        return;
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (args.length > 0) {
+        console.error(`[debugai-mcp] unknown argument(s): ${args.join(' ')} (see --help)`);
+        process.exitCode = 1;
+        return;
+    }
+    const apiKey = (process.env.DEBUGAI_API_KEY ?? '').trim();
+    const apiBase = (process.env.DEBUGAI_API_BASE ?? DEFAULT_API_BASE).trim().replace(/\/+$/, '');
+    const rawTimeout = Number(process.env.DEBUGAI_TIMEOUT_MS);
+    const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : DEFAULT_TIMEOUT_MS;
+    if (!apiKey) {
+        console.error('[debugai-mcp] DEBUGAI_API_KEY not set — tools will return auth errors. ' +
+            'Get a key at https://debugai.io/dashboard and add it to the "env" block of your MCP client config.');
+    }
+    else if (!apiKey.startsWith('dbg_')) {
+        console.error('[debugai-mcp] warning: DEBUGAI_API_KEY does not look like a DebugAI key (expected dbg_ prefix).');
+    }
+    const server = createServer({ apiKey, apiBase, version: VERSION, timeoutMs });
+    const shutdown = (signal) => {
+        console.error(`[debugai-mcp] received ${signal}, shutting down`);
+        void server.close().finally(() => process.exit(0));
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    const transport = new StdioServerTransport();
+    server.connect(transport).then(() => console.error(`[debugai-mcp] v${VERSION} connected on stdio (api: ${apiBase})`), (err) => {
+        console.error('[debugai-mcp] fatal:', err);
+        process.exit(1);
+    });
+}
+main();

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BackendConfig } from './backend.js';
+export declare function createServer(config: BackendConfig): McpServer;

package/dist/server.js

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerDebugError } from './tools/debugError.js';
+export function createServer(config) {
+    const server = new McpServer({ name: 'debugai', version: config.version }, { capabilities: { tools: { listChanged: true } } });
+    registerDebugError(server, config);
+    return server;
+}

package/dist/tools/debugError.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { BackendConfig, DebugFix } from '../backend.js';
+export declare function formatFix(fix: DebugFix, index: number): string;
+export declare function registerDebugError(server: McpServer, config: BackendConfig): void;

package/dist/tools/debugError.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { callDebugBackend } from '../backend.js';
+import { mapBackendErrorToToolResult } from '../errors.js';
+export function formatFix(fix, index) {
+    const lines = [
+        `\n**Fix ${index} (${fix.confidence}% confidence)** — ${fix.title}`,
+        fix.description,
+    ];
+    if (fix.code) {
+        lines.push('```', fix.code, '```');
+    }
+    if (fix.line_hint) {
+        lines.push(`_Location: ${fix.line_hint}_`);
+    }
+    return lines.join('\n');
+}
+export function registerDebugError(server, config) {
+    server.registerTool('debug_error', {
+        title: 'Debug Error',
+        description: 'Analyze a runtime error, exception, or stack trace and return root cause + ranked fixes. ' +
+            'Use whenever the user pastes an error, asks "why is this failing", "what does this error mean", ' +
+            '"debug this stack trace", "fix this exception", "analyze this traceback", or shows a ' +
+            'Traceback / TypeError / ReferenceError / AttributeError. ' +
+            'Works for Python, JavaScript, TypeScript, Go, Rust. ' +
+            'Returns root cause explanation plus up to 3 ranked fixes with code patches.',
+        inputSchema: {
+            errorText: z
+                .string()
+                .min(1)
+                .describe('The full error message, exception, or stack trace text.'),
+            language: z
+                .enum(['javascript', 'typescript', 'python', 'go', 'rust', 'auto'])
+                .default('auto')
+                .describe('Source language. Use "auto" to let DebugAI detect from the error.'),
+            codeSnippet: z
+                .string()
+                .optional()
+                .describe('Surrounding code lines near where the error was thrown, if available.'),
+            filePath: z
+                .string()
+                .optional()
+                .describe('Absolute or relative path to the file that threw the error, if known.'),
+        },
+        annotations: {
+            readOnlyHint: true,
+            title: 'Debug Error',
+        },
+    }, async ({ errorText, language, codeSnippet, filePath }) => {
+        try {
+            const result = await callDebugBackend({
+                error_message: errorText,
+                language: language !== 'auto' ? language : undefined,
+                code_snippet: codeSnippet,
+                file_path: filePath,
+                // framework_hint deliberately omitted: a language ('python') is not a
+                // framework ('fastapi'), and sending it bypasses the engine's
+                // framework detection — FastAPI/React errors lose their expert hints.
+            }, config);
+            const sections = ['## Root Cause', result.root_cause ?? '(no root cause returned)'];
+            if (result.fixes?.length) {
+                sections.push('\n## Fixes');
+                result.fixes.forEach((fix, i) => {
+                    sections.push(formatFix(fix, i + 1));
+                });
+            }
+            const badges = [];
+            if (result.model_used) {
+                badges.push(`Model: ${result.model_used}`);
+            }
+            if (result.has_project_context) {
+                badges.push('Codebase-aware: yes');
+            }
+            if (result.cached) {
+                badges.push('Cached: yes');
+            }
+            if (result.framework_detected) {
+                badges.push(`Framework: ${result.framework_detected}`);
+            }
+            if (badges.length) {
+                sections.push(`\n---\n_${badges.join(' · ')}_`);
+            }
+            const text = sections.join('\n');
+            return {
+                content: [{ type: 'text', text }],
+                structuredContent: {
+                    root_cause: result.root_cause,
+                    fixes: result.fixes,
+                    framework_detected: result.framework_detected,
+                    model_used: result.model_used,
+                    cached: result.cached ?? false,
+                    has_project_context: result.has_project_context ?? false,
+                },
+            };
+        }
+        catch (err) {
+            return mapBackendErrorToToolResult(err);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@debugai/mcp",
+  "version": "1.0.0",
+  "description": "DebugAI MCP server — hand any error to DebugAI from Claude Desktop, Claude Code, Cursor, Zed, or any MCP client and get root cause + ranked fixes.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "debugai-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "debugging",
+    "ai",
+    "claude",
+    "error-analysis",
+    "stack-trace",
+    "debugai"
+  ],
+  "homepage": "https://debugai.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1shizaan/debugai-mvp.git",
+    "directory": "packages/mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}