@debugai/mcp 1.1.0 → 2.0.0

package/README.md

@@ -106,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`
 
@@ -119,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:
 

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/index.js

@@ -19,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)

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.1.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",