@debugai/mcp 1.0.0 → 2.0.0

package/README.md

@@ -14,6 +14,19 @@ This package is the same server, standalone. No VS Code required.
 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.
 
+### Set the key once for every client (optional)
+
+Instead of repeating the key in each client's `env` block, write it to
+`~/.debugai/config.json`:
+
+```json
+{ "api_key": "dbg_your_key_here" }
+```
+
+Every MCP client launching `npx -y @debugai/mcp` picks it up — you can then
+drop the `env` block from the snippets below entirely. An explicit
+`DEBUGAI_API_KEY` env var still wins over the file.
+
 ### Claude Code
 
 ```bash
@@ -93,7 +106,7 @@ You don't need this package. The
 registers the MCP server automatically (VS Code 1.101+) and adds one-click
 fix apply, proactive scan, and codebase indexing on top.
 
-## The tool
+## The tools
 
 ### `debug_error`
 
@@ -106,10 +119,35 @@ Give it an error, get an analysis.
 | `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.
+Returns the root cause, up to 3 fixes ranked by confidence, the detected
+framework, and whether the answer came from cache. Since 2.0 each fix also
+carries, where derivable: `edits` (exact old/new strings your agent's edit
+tool can apply directly), `unified_diff`, and `verify_with` (a syntax-level
+check command to run after applying). Read-only: it never touches your
+files. Applying a fix is your agent's (and your) call.
+
+Every fix is labeled with its verification state, and there are three of
+them, not two: **verified** (a mechanical check passed — currently
+parse/import classes), **failed check** (confidence capped hard), or **not
+verified** (the confidence number is the model's own estimate — nothing
+checked it). We label the third case instead of hiding it.
+
+### `report_outcome`
+
+Tell DebugAI whether an applied fix actually worked.
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| `debugLogId` | yes | The `debug_log_id` from the `debug_error` response. |
+| `result` | yes | `worked` or `failed`. |
+| `fixRank` | no | Which ranked fix was applied (1-3). |
+| `newError` | no | If it failed: the error you saw after applying. |
+
+Confirmed rank-1 fixes are remembered per project (the next hit on the same
+error starts from the confirmed fix); failed-fix follow-ups are the
+feedback that improves future answers. Agents are asked to call this once
+per applied fix — same pipeline human feedback flows through in the VS Code
+extension.
 
 Example, in Claude Code:
 
@@ -123,9 +161,10 @@ Example, in Claude Code:
 
 | 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_API_KEY` | (none) | Your API key. Falls back to `api_key` in the config file. |
+| `DEBUGAI_API_BASE` | DebugAI production | Override for self-hosted or staging setups. Falls back to `api_base` in the config file. |
 | `DEBUGAI_TIMEOUT_MS` | `150000` | Per-request deadline. Deep analyses can take 30-90s. |
+| `DEBUGAI_CONFIG_PATH` | `~/.debugai/config.json` | Alternate config file location. Rarely needed. |
 
 ## Limits and honesty
 
@@ -140,7 +179,8 @@ Example, in Claude Code:
 ## Troubleshooting
 
 - **"authentication failed"**: key missing or wrong. Check the `env` block in
-  your client config, restart the client. Keys start with `dbg_`.
+  your client config or `~/.debugai/config.json`, 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.

package/dist/backend.d.ts

@@ -6,6 +6,11 @@ export interface DebugRequest {
     project_id?: string;
     framework_hint?: string;
 }
+export interface DebugEdit {
+    file: string;
+    old_string: string;
+    new_string: string;
+}
 export interface DebugFix {
     rank: number;
     title: string;
@@ -13,6 +18,11 @@ export interface DebugFix {
     confidence: number;
     code?: string;
     line_hint?: string;
+    verified?: boolean | null;
+    verification_reason?: string;
+    edits?: DebugEdit[];
+    unified_diff?: string;
+    verify_with?: string;
 }
 export interface DebugResponse {
     root_cause: string;
@@ -26,6 +36,22 @@ export interface DebugResponse {
     pattern_matched?: string;
     remaining_today?: number;
     mock?: boolean;
+    schema_version?: string;
+    debug_log_id?: string | null;
+    error_signature?: string;
+    session_id?: string;
+    memory_hit?: boolean;
+    memory_fix_confirmed?: boolean;
+}
+export interface OutcomeRequest {
+    debug_log_id: string;
+    result: 'worked' | 'failed';
+    fix_rank?: number;
+    new_error?: string;
+    source: 'agent';
+}
+export interface OutcomeResponse {
+    success: boolean;
 }
 export interface BackendConfig {
     apiKey: string;
@@ -39,4 +65,6 @@ export interface BackendError extends Error {
     retryAfterSeconds: number;
 }
 export declare const DEFAULT_TIMEOUT_MS = 150000;
+export declare const OUTCOME_TIMEOUT_MS = 15000;
 export declare function callDebugBackend(req: DebugRequest, config: BackendConfig): Promise<DebugResponse>;
+export declare function callOutcomeBackend(req: OutcomeRequest, config: BackendConfig): Promise<OutcomeResponse>;

package/dist/backend.js

@@ -1,21 +1,23 @@
 export const DEFAULT_TIMEOUT_MS = 150_000;
+// Feedback writes are a fast DB insert, not an LLM call — fail fast so a
+// stuck outcome report never holds an agent hostage for minutes.
+export const OUTCOME_TIMEOUT_MS = 15_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;
+async function postJson(path, payload, config, timeoutMs) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     let res;
     try {
-        res = await fetch(`${config.apiBase}/debug`, {
+        res = await fetch(`${config.apiBase}${path}`, {
             method: 'POST',
             headers: {
                 'content-type': 'application/json',
                 'x-api-key': config.apiKey,
                 'user-agent': `debugai-mcp/${config.version}`,
             },
-            body: JSON.stringify(req),
+            body: JSON.stringify(payload),
             signal: controller.signal,
         });
     }
@@ -36,3 +38,9 @@ export async function callDebugBackend(req, config) {
     }
     return res.json();
 }
+export async function callDebugBackend(req, config) {
+    return postJson('/debug', req, config, config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+}
+export async function callOutcomeBackend(req, config) {
+    return postJson('/user/debug-feedback', req, config, OUTCOME_TIMEOUT_MS);
+}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export interface FileConfig {
+    apiKey?: string;
+    apiBase?: string;
+}
+export interface ResolvedSettings {
+    apiKey: string;
+    apiBase: string;
+    /** Where the key came from — used only for the startup log line. */
+    keySource: 'env' | 'file' | 'none';
+}
+export declare function configPath(env?: NodeJS.ProcessEnv): string;
+export declare function loadFileConfig(env?: NodeJS.ProcessEnv, warn?: (msg: string) => void): FileConfig;
+export declare function resolveSettings(defaultApiBase: string, env?: NodeJS.ProcessEnv, warn?: (msg: string) => void): ResolvedSettings;

package/dist/config.js

@@ -0,0 +1,48 @@
+// Optional on-disk config so a user can set their key once instead of
+// repeating it in every MCP client's env block:
+//
+//   ~/.debugai/config.json      { "api_key": "dbg_...", "api_base": "..." }
+//
+// Environment variables always win over the file. DEBUGAI_CONFIG_PATH
+// overrides the file location (tests point it at a temp dir; users normally
+// never set it).
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function configPath(env = process.env) {
+    const override = (env.DEBUGAI_CONFIG_PATH ?? '').trim();
+    return override || join(homedir(), '.debugai', 'config.json');
+}
+export function loadFileConfig(env = process.env, warn = (msg) => console.error(msg)) {
+    const path = configPath(env);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return {}; // no config file is the normal case — stay silent
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            warn(`[debugai-mcp] ignoring ${path}: expected a JSON object`);
+            return {};
+        }
+        const record = parsed;
+        const str = (v) => typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+        return { apiKey: str(record.api_key), apiBase: str(record.api_base) };
+    }
+    catch {
+        warn(`[debugai-mcp] ignoring ${path}: malformed JSON`);
+        return {};
+    }
+}
+export function resolveSettings(defaultApiBase, env = process.env, warn = (msg) => console.error(msg)) {
+    const file = loadFileConfig(env, warn);
+    const envKey = (env.DEBUGAI_API_KEY ?? '').trim();
+    const apiKey = envKey || file.apiKey || '';
+    const keySource = envKey ? 'env' : file.apiKey ? 'file' : 'none';
+    const envBase = (env.DEBUGAI_API_BASE ?? '').trim();
+    const apiBase = (envBase || file.apiBase || defaultApiBase).replace(/\/+$/, '');
+    return { apiKey, apiBase, keySource };
+}

package/dist/index.js

@@ -5,6 +5,7 @@ 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';
+import { configPath, resolveSettings } from './config.js';
 const DEFAULT_API_BASE = 'https://debugai-mvp-production.up.railway.app/api';
 function packageVersion() {
     try {
@@ -18,8 +19,11 @@ function packageVersion() {
 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.
+Exposes two tools to any MCP client:
+  debug_error     hand it an error or stack trace, get root cause + ranked
+                  fixes with machine-applicable edits (v2 contract)
+  report_outcome  tell DebugAI whether an applied fix worked — failed-fix
+                  follow-ups improve future answers for your codebase
 
 Usage:
   npx @debugai/mcp                # start the server (stdio transport)
@@ -27,10 +31,14 @@ Usage:
   npx @debugai/mcp --help
 
 Environment:
-  DEBUGAI_API_KEY      required — your API key (dbg_...) from https://debugai.io/dashboard
+  DEBUGAI_API_KEY      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})
 
+Config file (set the key once, every MCP client picks it up):
+  ~/.debugai/config.json    {"api_key": "dbg_..."}
+  Env vars win over the file. api_base is also accepted.
+
 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
@@ -51,13 +59,13 @@ function main() {
         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 { apiKey, apiBase, keySource } = resolveSettings(DEFAULT_API_BASE);
     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.');
+        console.error('[debugai-mcp] no API key found — tools will return auth errors. ' +
+            'Get a key at https://debugai.io/dashboard, then either set DEBUGAI_API_KEY in your ' +
+            `MCP client config or write it once to ${configPath()} as {"api_key": "dbg_..."}.`);
     }
     else if (!apiKey.startsWith('dbg_')) {
         console.error('[debugai-mcp] warning: DEBUGAI_API_KEY does not look like a DebugAI key (expected dbg_ prefix).');
@@ -70,7 +78,7 @@ function main() {
     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) => {
+    server.connect(transport).then(() => console.error(`[debugai-mcp] v${VERSION} connected on stdio (api: ${apiBase}, key: ${keySource})`), (err) => {
         console.error('[debugai-mcp] fatal:', err);
         process.exit(1);
     });

package/dist/server.js

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

package/dist/tools/debugError.d.ts

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

package/dist/tools/debugError.js

@@ -1,9 +1,22 @@
 import { z } from 'zod';
 import { callDebugBackend } from '../backend.js';
 import { mapBackendErrorToToolResult } from '../errors.js';
+// Tri-state verification labeling (docs/plan-v2-contract-phase1.md §1).
+// The null case is rendered ON PURPOSE: a confidence number nothing checked
+// must never look the same as one that was mechanically verified.
+export function formatVerification(fix) {
+    if (fix.verified === true) {
+        return `✓ Verified — ${fix.verification_reason ?? 'mechanical check passed'}`;
+    }
+    if (fix.verified === false) {
+        return `✗ Failed mechanical check (confidence capped) — ${fix.verification_reason ?? 'check failed'}`;
+    }
+    return '· Not verified — confidence is the model\'s own estimate; nothing checked this fix.';
+}
 export function formatFix(fix, index) {
     const lines = [
         `\n**Fix ${index} (${fix.confidence}% confidence)** — ${fix.title}`,
+        formatVerification(fix),
         fix.description,
     ];
     if (fix.code) {
@@ -12,6 +25,15 @@ export function formatFix(fix, index) {
     if (fix.line_hint) {
         lines.push(`_Location: ${fix.line_hint}_`);
     }
+    if (fix.edits?.length) {
+        lines.push('_Machine-applicable edit available: `edits` on this fix in structuredContent carries the exact old/new strings (apply with your Edit/replace tool)._');
+    }
+    if (fix.unified_diff) {
+        lines.push('```diff', fix.unified_diff.trimEnd(), '```');
+    }
+    if (fix.verify_with) {
+        lines.push(`_Syntax-level check after applying: \`${fix.verify_with}\`_`);
+    }
     return lines.join('\n');
 }
 export function registerDebugError(server, config) {
@@ -22,7 +44,8 @@ export function registerDebugError(server, config) {
             '"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.',
+            'Returns root cause explanation plus up to 3 ranked fixes with machine-applicable code edits. ' +
+            'After applying a fix, report whether it worked via the report_outcome tool.',
         inputSchema: {
             errorText: z
                 .string()
@@ -79,16 +102,23 @@ export function registerDebugError(server, config) {
             if (badges.length) {
                 sections.push(`\n---\n_${badges.join(' · ')}_`);
             }
+            if (result.debug_log_id) {
+                sections.push(`\nAfter applying a fix, call report_outcome with debugLogId "${result.debug_log_id}", ` +
+                    'the fixRank you applied, and result "worked" or "failed" (include newError text if it failed).');
+            }
             const text = sections.join('\n');
             return {
                 content: [{ type: 'text', text }],
                 structuredContent: {
+                    schema_version: result.schema_version ?? '1.0',
                     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,
+                    debug_log_id: result.debug_log_id ?? null,
+                    error_signature: result.error_signature ?? null,
                 },
             };
         }

package/dist/tools/reportOutcome.d.ts

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

package/dist/tools/reportOutcome.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { callOutcomeBackend } from '../backend.js';
+import { mapBackendErrorToToolResult } from '../errors.js';
+export function registerReportOutcome(server, config) {
+    server.registerTool('report_outcome', {
+        title: 'Report Fix Outcome',
+        description: 'Report whether a DebugAI fix actually worked after you applied it. ' +
+            'Call this ONCE after applying (or abandoning) a fix from debug_error, passing the ' +
+            'debug_log_id from that response. If the fix failed, include the new error text — ' +
+            'failed-fix follow-ups directly improve future answers for this codebase, and ' +
+            'confirmed rank-1 fixes are remembered for the whole team.',
+        inputSchema: {
+            debugLogId: z
+                .string()
+                .min(1)
+                .describe('The debug_log_id value from the debug_error response you are reporting on.'),
+            result: z
+                .enum(['worked', 'failed'])
+                .describe('"worked" = the fix resolved the error; "failed" = it did not (or made things worse).'),
+            fixRank: z
+                .number()
+                .int()
+                .min(1)
+                .max(3)
+                .optional()
+                .describe('Which ranked fix you applied (1-3). Rank 1 outcomes feed team error memory.'),
+            newError: z
+                .string()
+                .max(4000)
+                .optional()
+                .describe('If result is "failed": the error observed AFTER applying the fix.'),
+        },
+        annotations: {
+            title: 'Report Fix Outcome',
+            // Deliberately NO readOnlyHint — this records telemetry server-side.
+            idempotentHint: true,
+        },
+    }, async ({ debugLogId, result, fixRank, newError }) => {
+        try {
+            await callOutcomeBackend({
+                debug_log_id: debugLogId,
+                result,
+                fix_rank: fixRank,
+                new_error: newError,
+                source: 'agent',
+            }, config);
+            const ack = result === 'worked'
+                ? 'Outcome recorded: fix worked. Rank-1 confirmations are remembered for this project, so the next hit on this error starts from the confirmed fix.'
+                : 'Outcome recorded: fix failed. The follow-up error was logged and feeds directly into improving future answers. If you are still stuck, call debug_error again with the NEW error text.';
+            return {
+                content: [{ type: 'text', text: ack }],
+                structuredContent: { recorded: true, result },
+            };
+        }
+        catch (err) {
+            return mapBackendErrorToToolResult(err);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugai/mcp",
-  "version": "1.0.0",
+  "version": "2.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",