@debugai/mcp 2.3.0 → 2.4.1

package/README.md

@@ -133,6 +133,8 @@ call report_outcome so the project's error memory stays accurate.
 
 You do not 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. It is on [Open VSX](https://open-vsx.org/extension/debugai/debugai) too, for Cursor, Windsurf, and VSCodium.
 
+The two servers are the same protocol surface and are kept in step by a test that reads both copies as text, because a comment saying "keep these in sync" has failed here before. From extension 2.8.1 the bundled server also does local source resolution, which this package has had since 2.2.0. Until then, an agent on the bundled server that pasted a traceback into a workspace nobody had indexed still got "Insufficient context for specific fix" at 20% confidence, which is the exact answer this feature exists to remove.
+
 ## Manual setup
 
 `setup` covers this, and `install --client=<id>` covers the case where a client is installed somewhere unusual. If you would still rather edit the file yourself, the entry is the same everywhere:
@@ -150,9 +152,16 @@ You do not need this package. The [DebugAI extension](https://marketplace.visual
 
 Where it goes:
 
+> **On Claude Code, `--scope user` is the part that matters.** `claude mcp add`
+> defaults to `--scope local`, which writes the server under
+> `projects."/your/dir".mcpServers` — it then works in that one directory and
+> nowhere else, which reads exactly like DebugAI needing to be set up per repo.
+> `debugai-mcp install` always writes the user scope. If you already ran the
+> local-scope version, `debugai-mcp doctor` now tells you which one you have.
+
 | Client | File |
 |--------|------|
-| Claude Code | `~/.claude.json` (or `claude mcp add debugai -- npx -y @debugai/mcp`) |
+| Claude Code | `~/.claude.json`, top-level `mcpServers` (or `claude mcp add --scope user debugai -- npx -y @debugai/mcp`) |
 | Claude Desktop | macOS `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows `%APPDATA%\Claude\claude_desktop_config.json` |
 | Cursor | `~/.cursor/mcp.json` |
 | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
@@ -190,6 +199,7 @@ Then run `npx -y @debugai/mcp login` once to store your key. If you would rather
 - 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, any snippet you pass, and — since 2.2 — the project source files the stack trace names are sent there, and Claude (Anthropic) does the analysis. The response lists every file that was read. Scope and limits are spelled out under [`debug_error`](#it-reads-the-source-the-trace-names-22). Privacy policy: [debugai.io/privacy](https://debugai.io/privacy?src=npm).
 - Errors are remembered per project so a repeat hit starts from a fix that was already confirmed. The project identity is a hash of your repo root path; the path itself is never sent.
+- The VS Code extension reads the project's `requirements.txt`, `pyproject.toml` and `package.json` and the interpreter the editor has selected, which is what lets it tell "not installed" apart from "installed under a different interpreter". This server sends none of that, so on a missing-module error you get the general answer and the check to run, not a verdict. You have a shell and it does not, so the honest division is that you run the check. Reporting those facts back through this server is planned.
 
 ## Troubleshooting
 
@@ -204,9 +214,36 @@ Run `npx -y @debugai/mcp doctor` first. It checks your Node version, whether a k
 
 **Note on updates**: the analysis runs on DebugAI's servers, so improvements to
 error parsing, retrieval and root-cause quality reach you without upgrading this
-package. Recent server-side work: pytest, unittest, jest, vitest and mocha output
-now yields real file paths, so a failing test gets cross-file context instead of
-none. Client releases are only for things that change on your machine.
+package. Client releases are only for things that change on your machine.
+
+Recent server-side work, all of it live for agents already:
+
+- `ModuleNotFoundError` no longer opens with an install command. A read of every
+  one we had answered found five of eight rejected by the agent that received
+  them, for three different causes needing three different fixes: the package
+  was installed under another interpreter, the name was a local file, or the
+  import line was malformed. Rank 1 is now the check that tells those apart.
+- A Python `SyntaxError` is no longer diagnosed as a JavaScript one, and the
+  framework is read from the error text rather than from what the repository
+  contains.
+- Operating-system errors (`Access is denied.`, `No space left on device`) are
+  recognised as errors. Thirty were probed and twenty-eight had been refused.
+- Credentials in the text you send are replaced before anything is stored or
+  reaches a model.
+- pytest, unittest, jest, vitest and mocha output yields real file paths, so a
+  failing test gets cross-file context instead of none.
+
+**2.4.0**: `report_outcome` gains `unused`. An agent that solved the problem its
+own way had to report `failed`, which marks a fix as tried and beaten when
+nothing of ours was ever run. Both tool surfaces, the npm server and the one
+bundled in the VS Code extension, now take the same fields.
+
+**2.3.0**: agents get the same four memory states the editor panel does.
+`debug_error` had two branches, and a fix that had been tried and kept failing
+read identically to one nobody had tried. To an agent those are the same
+sentence, so the natural next move is to propose the fix that already did not
+work. The four states now match the panel: confirmed and verified, confirmed,
+unproven, and anti-pattern.
 
 **2.2.0**: two things that were advertised but not delivered.
 

package/dist/backend.d.ts

@@ -56,9 +56,19 @@ export interface DebugResponse {
 }
 export interface OutcomeRequest {
     debug_log_id: string;
-    result: 'worked' | 'failed';
+    /**
+     * 'unused' joined on 2026-08-26. An agent that read the fixes, used none of
+     * them and solved it another way previously had to report 'failed', which
+     * marks a fix as tried and beaten when nothing of ours was ever run.
+     */
+    result: 'worked' | 'failed' | 'unused';
     fix_rank?: number;
+    /** An error message observed after a failed fix. Not an explanation. */
     new_error?: string;
+    /** What actually resolved it, when our answer was not what worked. */
+    actual_fix?: string;
+    /** What would have made the tool more useful here. About the tool, not the bug. */
+    tool_feedback?: string;
     source: 'agent';
 }
 export interface OutcomeResponse {

package/dist/cli/commands.js

@@ -17,7 +17,7 @@ import { clearStoredKey, configPath, loadFileConfig, maskKey, resolveSettings, w
 import { DeviceLinkError, startDeviceLink, waitForDeviceLink } from '../deviceLink.js';
 import { DEFAULT_API_BASE } from '../constants.js';
 import { detectedClients, findClient, isDetected, knownClients, } from './clients.js';
-import { applyToClient, isInstalled } from './install.js';
+import { applyToClient, findInstall } from './install.js';
 import { FAIL, INFO, OK, WARN, bold, codeBox, dim, heading, openBrowser, say, yellow } from './ui.js';
 // ── shared helpers ───────────────────────────────────────────────────────────
 function flag(argv, name) {
@@ -215,7 +215,12 @@ function listClients(env) {
     heading('Known MCP clients');
     for (const c of knownClients(env)) {
         const mark = isDetected(c) ? OK() : INFO();
-        const state = isDetected(c) ? (isInstalled(c) ? 'detected · debugai configured' : 'detected') : 'not found';
+        const site = isDetected(c) ? findInstall(c) : null;
+        const state = !isDetected(c)
+            ? 'not found'
+            : site?.scope === 'user' ? 'detected · debugai configured'
+                : site?.scope === 'project' ? 'detected · debugai configured (one directory only)'
+                    : 'detected';
         say(`  ${mark} ${bold(c.id.padEnd(15))} ${c.label.padEnd(22)} ${dim(state)}`);
         say(`      ${dim(c.configPath ?? 'no config path on this OS')}`);
         if (c.note)
@@ -329,10 +334,23 @@ export async function cmdDoctor(_argv, env = process.env) {
         say(`  ${INFO()} None detected. "debugai-mcp install --list" shows every supported client.`);
     }
     for (const c of detected) {
-        if (isInstalled(c))
+        const site = findInstall(c);
+        if (site?.scope === 'user') {
             pass(`${c.label} — debugai configured`, c.configPath ?? undefined);
-        else
+        }
+        else if (site?.scope === 'project') {
+            // Working, but only in one directory, and somebody who does not know that
+            // concludes DebugAI has to be set up per repo. That belief is what makes
+            // an MCP server not worth installing, so this is a warning with the exact
+            // command to widen it rather than a quiet pass.
+            say(`  ${WARN()} ${yellow(`${c.label} — debugai configured for ONE directory only`)}`);
+            say(`      ${dim(site.projectPath ?? '')}`);
+            say(`      ${dim('`claude mcp add` defaults to --scope local. To use DebugAI in every repo:')}`);
+            say(`      ${dim(`debugai-mcp install --client=${c.id}`)}`);
+        }
+        else {
             say(`  ${WARN()} ${yellow(`${c.label} — installed but DebugAI is not in its config`)}\n      ${dim(`fix: debugai-mcp install --client=${c.id}`)}`);
+        }
     }
     say();
     if (hardFailures) {

package/dist/cli/install.d.ts

@@ -17,5 +17,42 @@ export interface InstallOptions {
     remove?: boolean;
 }
 export declare function applyToClient(client: McpClient, opts?: InstallOptions): InstallResult;
-/** True when the client's config already points at this server. */
+/**
+ * Where a client's config points at this server, if anywhere.
+ *
+ * ## Why this is not a boolean any more
+ *
+ * Claude Code stores MCP servers in two places in one file, and the difference
+ * decides whether DebugAI works in every repo or exactly one:
+ *
+ *   ~/.claude.json
+ *   ├── mcpServers            ← user scope. Every directory, every session.
+ *   └── projects
+ *       └── /home/me/thing
+ *           └── mcpServers    ← local scope. That one directory only.
+ *
+ * `claude mcp add` writes the SECOND one, because `--scope local` is its
+ * default. This function used to read only the first, so the officially
+ * documented install path produced a config that `doctor` then reported as
+ * missing — a diagnostic contradicting a working install, which is worse than
+ * no diagnostic, because it sends somebody to re-run an installer that then
+ * creates a duplicate entry in the other scope.
+ *
+ * Reported by an agent running a real build on 2026-08-24, who lost a whole
+ * session to it. Their words: "two documented paths disagree, and the
+ * diagnostic sides with the wrong one."
+ *
+ * The scope is returned rather than flattened away because the two are not
+ * equally good. A local-scope install is the thing that makes somebody think
+ * they have to reconfigure DebugAI per directory, and telling them where it
+ * actually is turns that into a one-line fix.
+ */
+export interface InstallSite {
+    /** 'user' works everywhere. 'project' works in `projectPath` only. */
+    scope: 'user' | 'project';
+    /** Which directory it is scoped to, for 'project'. */
+    projectPath?: string;
+}
+export declare function findInstall(client: McpClient): InstallSite | null;
+/** True when the client's config points at this server in ANY scope. */
 export declare function isInstalled(client: McpClient): boolean;

package/dist/cli/install.js

@@ -135,16 +135,32 @@ export function applyToClient(client, opts = {}) {
         warning,
     };
 }
-/** True when the client's config already points at this server. */
-export function isInstalled(client) {
+export function findInstall(client) {
     if (!client.configPath || !existsSync(client.configPath))
-        return false;
+        return null;
+    const has = (v) => Boolean(v && typeof v === 'object' && SERVER_NAME in v);
     try {
         const parsed = parseJsonc(readFileSync(client.configPath, 'utf8'));
-        const servers = parsed.value?.[serversKey(client.shape)];
-        return Boolean(servers && typeof servers === 'object' && SERVER_NAME in servers);
+        const root = parsed.value;
+        if (has(root?.[serversKey(client.shape)]))
+            return { scope: 'user' };
+        // Claude Code's per-directory scope. Other clients have no `projects` key,
+        // so this loop simply never runs for them rather than needing a special case.
+        const projects = root?.projects;
+        if (projects && typeof projects === 'object') {
+            for (const [dir, cfg] of Object.entries(projects)) {
+                if (cfg && typeof cfg === 'object' && has(cfg.mcpServers)) {
+                    return { scope: 'project', projectPath: dir };
+                }
+            }
+        }
+        return null;
     }
     catch {
-        return false;
+        return null;
     }
 }
+/** True when the client's config points at this server in ANY scope. */
+export function isInstalled(client) {
+    return findInstall(client) !== null;
+}

package/dist/server.js

@@ -26,6 +26,12 @@ yourself only when you already know the relevant code is somewhere the trace
 does not name.
 
 After you apply or abandon a fix, call report_outcome with the debug_log_id.
+Report it even when you ignored the answer and fixed it your own way: pass
+result "unused" and put what actually worked in actualFix. A case DebugAI got
+wrong is worth more to it than one it got right, and "unused" is not the same
+as "failed" — reporting a fix as failed when you never ran it buries it for the
+next person. If the tool could have served you better here, say so in
+toolFeedback; that reaches the people who build it.
 That is what turns a one-off answer into memory for the next person who hits
 the same error. Skipping it costs the user the feature they are paying for.
 

package/dist/tools/reportOutcome.d.ts

@@ -1,3 +1,39 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { BackendConfig } from '../backend.js';
+/**
+ * The channel back.
+ *
+ * ## Why this tool grew on 2026-08-26
+ *
+ * An external user's agent reported an outcome and wrote this into `newError`,
+ * a field described to it as "the error observed AFTER applying the fix":
+ *
+ *   "The first corrected node -e command was still rewritten by PowerShell
+ *    quoting; a separate PowerShell HTTP verification was used successfully
+ *    instead."
+ *
+ * That is not an error. It is a post-mortem: our answer was aimed at the wrong
+ * layer, and here is what actually worked. It is the most useful thing anybody
+ * has ever sent this system, and the agent had to force it through the wrong
+ * slot because nothing here asked for it.
+ *
+ * So the schema now asks. Three changes, each closing a case an honest agent
+ * could not previously report:
+ *
+ *   'unused'       — you read the fixes, used none of them, and solved it your
+ *                    own way. Previously only 'worked' and 'failed' existed, so
+ *                    this had to be misreported as a failure or not reported.
+ *                    Reporting it as a failure is actively harmful: it marks a
+ *                    fix as tried and beaten when nothing of ours was run.
+ *   actualFix      — what actually resolved it. Ground truth on a case we got
+ *                    wrong, which is worth more than a case we got right.
+ *   toolFeedback   — what would have made this tool more useful here. About the
+ *                    tool, not the bug, and kept separate for exactly that
+ *                    reason: a complaint about DebugAI must never end up
+ *                    promoted into somebody's project memory as a fix.
+ *
+ * A field on a tool agents already call beats a new tool they would have to be
+ * told about. This one has a measured ~50% attach rate; a new `send_feedback`
+ * starts at zero and competes for the same attention.
+ */
 export declare function registerReportOutcome(server: McpServer, config: BackendConfig): void;

package/dist/tools/reportOutcome.js

@@ -2,41 +2,98 @@ import { z } from 'zod';
 import { callOutcomeBackend } from '../backend.js';
 import { mapBackendErrorToToolResult } from '../errors.js';
 import { resolveAuth } from './authGate.js';
+/**
+ * The channel back.
+ *
+ * ## Why this tool grew on 2026-08-26
+ *
+ * An external user's agent reported an outcome and wrote this into `newError`,
+ * a field described to it as "the error observed AFTER applying the fix":
+ *
+ *   "The first corrected node -e command was still rewritten by PowerShell
+ *    quoting; a separate PowerShell HTTP verification was used successfully
+ *    instead."
+ *
+ * That is not an error. It is a post-mortem: our answer was aimed at the wrong
+ * layer, and here is what actually worked. It is the most useful thing anybody
+ * has ever sent this system, and the agent had to force it through the wrong
+ * slot because nothing here asked for it.
+ *
+ * So the schema now asks. Three changes, each closing a case an honest agent
+ * could not previously report:
+ *
+ *   'unused'       — you read the fixes, used none of them, and solved it your
+ *                    own way. Previously only 'worked' and 'failed' existed, so
+ *                    this had to be misreported as a failure or not reported.
+ *                    Reporting it as a failure is actively harmful: it marks a
+ *                    fix as tried and beaten when nothing of ours was run.
+ *   actualFix      — what actually resolved it. Ground truth on a case we got
+ *                    wrong, which is worth more than a case we got right.
+ *   toolFeedback   — what would have made this tool more useful here. About the
+ *                    tool, not the bug, and kept separate for exactly that
+ *                    reason: a complaint about DebugAI must never end up
+ *                    promoted into somebody's project memory as a fix.
+ *
+ * A field on a tool agents already call beats a new tool they would have to be
+ * told about. This one has a measured ~50% attach rate; a new `send_feedback`
+ * starts at zero and competes for the same attention.
+ */
 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.',
+        description: 'Report what happened after DebugAI answered — including when you did not use its fix. ' +
+            'Call this ONCE per debug_error response, passing the debug_log_id from it. ' +
+            'If you solved the problem another way, say so with result "unused" and put the real ' +
+            'fix in actualFix: a case DebugAI got wrong is worth more to it than one it got right. ' +
+            'If the tool could have helped you more here, say that in toolFeedback. ' +
+            'Confirmed rank-1 fixes are remembered for this project and returned to whoever hits ' +
+            'the same error next.',
         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).'),
+                .enum(['worked', 'failed', 'unused'])
+                .describe('"worked" = you applied a DebugAI fix and the error stopped. ' +
+                '"failed" = you applied one and it did not help (or made things worse). ' +
+                '"unused" = you did not apply any of them and resolved it another way. ' +
+                'Use "unused" rather than "failed" when nothing of ours was actually run. ' +
+                'They are different facts and reporting the wrong one buries a fix nobody tried.'),
             fixRank: z
                 .number()
                 .int()
                 .min(1)
                 .max(3)
                 .optional()
-                .describe('Which ranked fix you applied (1-3). Rank 1 outcomes feed team error memory.'),
+                .describe('Which ranked fix you applied (1-3). Rank 1 outcomes feed team error memory. Omit for "unused".'),
             newError: z
                 .string()
                 .max(4000)
                 .optional()
-                .describe('If result is "failed": the error observed AFTER applying the fix.'),
+                .describe('If result is "failed": the error observed AFTER applying the fix. An error message, not an explanation.'),
+            actualFix: z
+                .string()
+                .max(4000)
+                .optional()
+                .describe('What actually resolved the error, when it was not the fix DebugAI suggested. ' +
+                'Free text. Say what the real cause turned out to be and what you changed, ' +
+                'especially if the cause was in a different layer than the answer addressed ' +
+                '(the shell, the runtime version, the environment, a missing package).'),
+            toolFeedback: z
+                .string()
+                .max(2000)
+                .optional()
+                .describe('What would have made DebugAI more useful on THIS call. About the tool, not the bug: ' +
+                'context it lacked, a question it should have asked, an input shape it rejected, ' +
+                'a wrong assumption in its reasoning. This reaches the people who build it.'),
         },
         annotations: {
             title: 'Report Fix Outcome',
             // Deliberately NO readOnlyHint — this records telemetry server-side.
             idempotentHint: true,
         },
-    }, async ({ debugLogId, result, fixRank, newError }) => {
+    }, async ({ debugLogId, result, fixRank, newError, actualFix, toolFeedback }) => {
         const gate = await resolveAuth(config);
         if (!gate.ok)
             return gate.result;
@@ -46,11 +103,22 @@ export function registerReportOutcome(server, config) {
                 result,
                 fix_rank: fixRank,
                 new_error: newError,
+                actual_fix: actualFix,
+                tool_feedback: toolFeedback,
                 source: 'agent',
             }, gate.config);
+            // The acknowledgement is the only thing that tells an agent its report
+            // landed somewhere real. An 'unused' report especially: an agent that
+            // says "I ignored you and did it myself" and gets a generic thank-you
+            // learns that the field is decorative, and stops filling it.
             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.';
+                : result === 'unused'
+                    ? 'Outcome recorded: our fix was not used.' +
+                        (actualFix
+                            ? ' The fix that actually worked was logged — that is the most useful thing this tool receives, because it is a case we got wrong.'
+                            : ' If you know what actually resolved it, send it in actualFix: a wrong answer we can see is worth more than a right one we cannot.')
+                    : '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 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugai/mcp",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "mcpName": "io.github.1shizaan/debugai-mcp",
   "description": "DebugAI MCP server. One command sets it up in Claude Desktop, Claude Code, Cursor, Zed, Windsurf, Cline or any MCP client: browser sign-in, no key pasting, no config editing.",
   "license": "MIT",