@debugai/mcp 2.0.0 → 2.1.0

package/README.md

@@ -1,110 +1,69 @@
 # @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.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@debugai/mcp"><img src="https://img.shields.io/npm/v/@debugai/mcp?color=0A0A0F&label=npm" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-0A0A0F" alt="Node 18+">
+  <img src="https://img.shields.io/badge/license-MIT-0A0A0F" alt="MIT license">
+</p>
 
-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.
+Give your coding agent a debugger instead of a grep loop.
 
-## 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.
+Your agent hands an error to `debug_error` and gets back the root cause, the exact file and line, and up to 3 ranked fixes as ready-to-apply edits. Each fix is labeled with whether a mechanical check actually passed, so the agent knows which ones were checked and which are the model's own estimate.
 
-### Set the key once for every client (optional)
+Auto-configures Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Gemini CLI, and Cline. Works in any other MCP client with a manual entry. Node 18 or later.
 
-Instead of repeating the key in each client's `env` block, write it to
-`~/.debugai/config.json`:
+## Setup
 
-```json
-{ "api_key": "dbg_your_key_here" }
+```bash
+npx -y @debugai/mcp setup
 ```
 
-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.
+That is the whole thing. It signs you in through your browser (no key to find or copy), writes the config for every MCP client it finds on this machine, then checks that all of it actually works.
 
-### Claude Code
+Restart the clients it names and your agent has the tools.
 
-```bash
-claude mcp add debugai --env DEBUGAI_API_KEY=dbg_your_key_here -- npx -y @debugai/mcp
-```
-
-### Claude Desktop
+Prefer to read first? [debugai.io/start?src=npm](https://debugai.io/start?src=npm) walks the same thing per client.
 
-`claude_desktop_config.json` (Settings, Developer, Edit Config):
+### What that command does to your machine
 
-```json
-{
-  "mcpServers": {
-    "debugai": {
-      "command": "npx",
-      "args": ["-y", "@debugai/mcp"],
-      "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
-    }
-  }
-}
-```
+Worth knowing before you run something that edits your editor config:
 
-### Cursor
+- Signs you in with a short code you confirm in the browser. Free account, 10 debugs a day, no card.
+- Stores your key in `~/.debugai/config.json` with `0600` permissions. That is the only file that ever holds it.
+- Adds a `debugai` entry to the config of each MCP client it detects. Every file is backed up first (`<file>.debugai-backup-<timestamp>`), every other setting in the file is preserved, and a file it cannot parse is left alone and reported instead. One caveat stated plainly: if your config contains comments, the rewrite drops them, because JSON has nowhere to put them. You get a warning before it happens and the backup still has them.
+- Skips VS Code by default, because the [DebugAI extension](https://marketplace.visualstudio.com/items?itemName=debugai.debugai) already registers this server there and a second entry would show every tool twice. `install --client=vscode` does it anyway if you want the server without the extension.
+- Never writes your key into a client config. Client configs get committed to repos. Keys should not.
 
-`~/.cursor/mcp.json` (or `.cursor/mcp.json` per project):
+Preview it without writing anything:
 
-```json
-{
-  "mcpServers": {
-    "debugai": {
-      "command": "npx",
-      "args": ["-y", "@debugai/mcp"],
-      "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
-    }
-  }
-}
+```bash
+npx -y @debugai/mcp install --dry-run
 ```
 
-### Zed
-
-`settings.json`:
+Undo all of it:
 
-```json
-{
-  "context_servers": {
-    "debugai": {
-      "command": {
-        "path": "npx",
-        "args": ["-y", "@debugai/mcp"],
-        "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
-      }
-    }
-  }
-}
+```bash
+npx -y @debugai/mcp uninstall   # removes the entry from every client config
+npx -y @debugai/mcp logout      # removes the stored key
 ```
 
-### Windsurf
+### Commands
 
-`~/.codeium/windsurf/mcp_config.json`:
+| Command | What it does |
+|---------|--------------|
+| `setup` | `login` then `install`, then verifies. The one you want. |
+| `login` | Browser sign-in. `--key dbg_…` to paste a key instead (CI, air-gapped boxes). `--force` to re-link. |
+| `logout` | Removes the stored key. |
+| `status` | Which key and account are active right now. |
+| `install` | Writes client configs. `--list`, `--client=cursor`, `--all`, `--dry-run`, `--remove`. |
+| `uninstall` | Removes the entry from every client config. |
+| `doctor` | Diagnoses a broken setup: key, API reachability, per-client wiring. |
 
-```json
-{
-  "mcpServers": {
-    "debugai": {
-      "command": "npx",
-      "args": ["-y", "@debugai/mcp"],
-      "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
-    }
-  }
-}
-```
+`npx -y @debugai/mcp install --list` prints every supported client, where its config lives on your OS, and whether DebugAI is already in it.
 
-### VS Code
+### Signing in from inside a chat
 
-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.
+If your agent calls a DebugAI tool before you have signed in, the tool answers with a short code and a URL instead of an error. Confirm it in the browser, tell the agent to try again, and the call goes through. No config editing, and no client restart, because the key is re-read on every call.
 
 ## The tools
 
@@ -119,18 +78,9 @@ 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, 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.
+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 call, and yours.
 
-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.
+Every fix is labeled with its verification state, and there are three of them, not two: **verified** (a mechanical check passed, currently parse and 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`
 
@@ -143,11 +93,7 @@ Tell DebugAI whether an applied fix actually worked.
 | `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.
+Confirmed rank-1 fixes are remembered per project, so 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, through the same pipeline human feedback flows through in the VS Code extension.
 
 Example, in Claude Code:
 
@@ -157,11 +103,66 @@ Example, in Claude Code:
 > **Root cause:** `db.session` is used after the request context closed.
 > **Fix 1 (94% confidence):** move the query inside the request handler...
 
+### Making your agent reach for it
+
+The server tells connecting agents what it is for, but a rule in your project file is the deterministic version. Add this to `CLAUDE.md`, `.cursorrules`, or whatever your agent reads:
+
+```
+On any runtime error, exception, or failing test, call the debugai
+debug_error tool before attempting your own fix. After applying a fix,
+call report_outcome so the project's error memory stays accurate.
+```
+
+## VS Code
+
+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.
+
+## 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:
+
+```json
+{
+  "mcpServers": {
+    "debugai": {
+      "command": "npx",
+      "args": ["-y", "@debugai/mcp"]
+    }
+  }
+}
+```
+
+Where it goes:
+
+| Client | File |
+|--------|------|
+| Claude Code | `~/.claude.json` (or `claude mcp add 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` |
+| Gemini CLI | `~/.gemini/settings.json` |
+| Cline | VS Code globalStorage, `saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
+
+Zed uses a different key and a nested command:
+
+```json
+{
+  "context_servers": {
+    "debugai": {
+      "source": "custom",
+      "command": { "path": "npx", "args": ["-y", "@debugai/mcp"] }
+    }
+  }
+}
+```
+
+Then run `npx -y @debugai/mcp login` once to store your key. If you would rather set the key per client, `DEBUGAI_API_KEY` in that client's `env` block still works and still wins over the stored one.
+
 ## Environment variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `DEBUGAI_API_KEY` | (none) | Your API key. Falls back to `api_key` in the config file. |
+| `DEBUGAI_API_KEY` | (none) | Your API key. Overrides `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. |
@@ -170,22 +171,23 @@ Example, in Claude Code:
 
 - 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).
+- 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, and Claude (Anthropic) does the analysis. Privacy policy: [debugai.io/privacy](https://debugai.io/privacy?src=npm).
 
 ## Troubleshooting
 
-- **"authentication failed"**: key missing or wrong. Check the `env` block in
-  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.
-- **Timeouts**: deep analyses can take up to 90s. If your client has its own
-  tool timeout, raise it above that.
+Run `npx -y @debugai/mcp doctor` first. It checks your Node version, whether a key is stored and where it came from, whether that key still authenticates against the API, the permissions on the config file, and which detected clients are missing the DebugAI entry. Most answers are in that output.
+
+- **"authentication failed"**: the key was rotated or revoked. Run `npx -y @debugai/mcp login --force`.
+- **Tools do not appear in the client**: the client was not restarted, or it reads a different config file. `install --list` shows which file was written.
+- **Nothing happens on `npx @debugai/mcp`**: correct. It is a stdio server waiting for an MCP client to speak first. Use `--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.
+
+## Changelog
+
+**2.1.0**: one-command setup. Browser sign-in over a device link (no key pasting), automatic client config writing with backups, `doctor` for diagnosing a broken setup, and in-conversation sign-in when an agent calls a tool before you have an account.
+
+**2.0.0**: `report_outcome` tool, ready-to-apply `edits` per fix, and the three-state verification label.
 
 ## Development
 

package/dist/auth.d.ts

@@ -0,0 +1,40 @@
+export interface AuthProviderOptions {
+    apiBase: string;
+    env?: NodeJS.ProcessEnv;
+    clientLabel?: string;
+    /** Injected in tests. */
+    now?: () => number;
+    fetchImpl?: typeof fetch;
+}
+export type EnsureAuth = {
+    ok: true;
+    apiKey: string;
+} | {
+    ok: false;
+    reason: 'link_pending';
+    text: string;
+    userCode: string;
+    verificationUri: string;
+} | {
+    ok: false;
+    reason: 'link_unavailable';
+    text: string;
+};
+export declare class AuthProvider {
+    private readonly opts;
+    private pending;
+    private pendingStartedAt;
+    private lastPollAt;
+    private readonly env;
+    private readonly now;
+    constructor(opts: AuthProviderOptions);
+    /** Env wins over file, re-read every call — see the header note. */
+    currentKey(): string;
+    /**
+     * Returns a usable key, or the exact words the agent should say to the user.
+     * Never throws: a failure to reach the link endpoint degrades to printed
+     * instructions, it does not take the tool call down with it.
+     */
+    ensure(): Promise<EnsureAuth>;
+    private pendingResult;
+}

package/dist/auth.js

@@ -0,0 +1,115 @@
+// Live auth for the running server.
+//
+// Two problems this solves, both of which used to end the funnel:
+//
+//  1. The key used to be read ONCE at process start. A user who fixed their
+//     setup while the client was running still got auth errors until they
+//     restarted the whole MCP client. Now the key is re-read from env + the
+//     config file on every tool call, so `debugai-mcp login` in another
+//     terminal takes effect on the next call — no restart, no reconnect.
+//
+//  2. A user with no key at all used to get a dead-end error. Now the server
+//     starts a device link itself and hands the agent a short code plus a URL
+//     to read out. The human approves in a browser; the agent retries; the
+//     second call finds the key and does the real work. Signup happens inside
+//     the conversation instead of in a config file the user never opens.
+import { loadFileConfig, writeFileConfig } from './config.js';
+import { DeviceLinkError, pollDeviceLink, startDeviceLink, } from './deviceLink.js';
+/** Minimum gap between in-session polls: one poll per tool call, at most. */
+const MIN_POLL_GAP_MS = 3_000;
+export class AuthProvider {
+    opts;
+    pending = null;
+    pendingStartedAt = 0;
+    lastPollAt = 0;
+    env;
+    now;
+    constructor(opts) {
+        this.opts = opts;
+        this.env = opts.env ?? process.env;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Env wins over file, re-read every call — see the header note. */
+    currentKey() {
+        const envKey = (this.env.DEBUGAI_API_KEY ?? '').trim();
+        if (envKey)
+            return envKey;
+        return loadFileConfig(this.env, () => { }).apiKey ?? '';
+    }
+    /**
+     * Returns a usable key, or the exact words the agent should say to the user.
+     * Never throws: a failure to reach the link endpoint degrades to printed
+     * instructions, it does not take the tool call down with it.
+     */
+    async ensure() {
+        const existing = this.currentKey();
+        if (existing)
+            return { ok: true, apiKey: existing };
+        // A link already in flight — poll it once before minting another code, so
+        // an agent retrying in a loop doesn't spray fresh codes at the user.
+        if (this.pending && this.now() - this.pendingStartedAt < this.pending.expiresIn * 1000) {
+            if (this.now() - this.lastPollAt >= MIN_POLL_GAP_MS) {
+                this.lastPollAt = this.now();
+                try {
+                    const result = await pollDeviceLink(this.pending.deviceCode, {
+                        apiBase: this.opts.apiBase,
+                        fetchImpl: this.opts.fetchImpl,
+                    });
+                    if (result.status === 'linked') {
+                        writeFileConfig({ apiKey: result.apiKey }, this.env);
+                        this.pending = null;
+                        return { ok: true, apiKey: result.apiKey };
+                    }
+                    if (result.status === 'expired' || result.status === 'denied') {
+                        this.pending = null; // fall through and mint a fresh code below
+                    }
+                }
+                catch {
+                    // Network hiccup mid-link: keep the pending code, repeat instructions.
+                }
+            }
+            if (this.pending)
+                return this.pendingResult(this.pending);
+        }
+        try {
+            const start = await startDeviceLink({
+                apiBase: this.opts.apiBase,
+                clientLabel: this.opts.clientLabel,
+                fetchImpl: this.opts.fetchImpl,
+            });
+            this.pending = start;
+            this.pendingStartedAt = this.now();
+            this.lastPollAt = this.now();
+            return this.pendingResult(start);
+        }
+        catch (err) {
+            const detail = err instanceof DeviceLinkError ? ` (${err.message})` : '';
+            return {
+                ok: false,
+                reason: 'link_unavailable',
+                text: 'DebugAI is not connected to an account yet, and the automatic link could not be ' +
+                    `started${detail}. Tell the user to run this in a terminal, which signs them in and ` +
+                    'stores the key for every MCP client at once:\n\n' +
+                    '    npx -y @debugai/mcp login\n\n' +
+                    'It opens a browser, takes about 20 seconds, and needs no config editing. ' +
+                    'Then retry this tool call. No client restart needed.',
+            };
+        }
+    }
+    pendingResult(start) {
+        return {
+            ok: false,
+            reason: 'link_pending',
+            userCode: start.userCode,
+            verificationUri: start.verificationUri,
+            text: 'DebugAI is not connected to an account yet. This takes about 20 seconds and needs no ' +
+                'config file editing.\n\n' +
+                'Tell the user, verbatim:\n' +
+                `  1. Open ${start.verificationUriComplete}\n` +
+                `  2. Sign in (free, 10 debugs/day, no card) and confirm the code ${start.userCode}\n\n` +
+                'Then call this tool again with the same arguments. The key is picked up automatically ' +
+                'on the next call. The MCP client does NOT need restarting. ' +
+                `The code expires in ${Math.round(start.expiresIn / 60)} minutes.`,
+        };
+    }
+}

package/dist/backend.d.ts

@@ -1,3 +1,4 @@
+import type { AuthProvider } from './auth.js';
 export interface DebugRequest {
     error_message: string;
     code_snippet?: string;
@@ -54,11 +55,19 @@ export interface OutcomeResponse {
     success: boolean;
 }
 export interface BackendConfig {
+    /** Key resolved at process start. Present for direct/test use; live calls prefer `auth`. */
     apiKey: string;
     apiBase: string;
     version: string;
     /** Whole-request deadline in ms. Claude analysis runs 30-90s; nginx cuts at 120s. */
     timeoutMs?: number;
+    /**
+     * Live auth. When set, tools resolve the key through it on every call (so a
+     * key added while the client is running works without a restart) and can
+     * start a browser sign-in mid-conversation. Absent in unit tests, which pass
+     * a fixed apiKey.
+     */
+    auth?: AuthProvider;
 }
 export interface BackendError extends Error {
     status: number;

package/dist/cli/clients.d.ts

@@ -0,0 +1,36 @@
+export type ConfigShape = 'mcpServers' | 'context_servers' | 'vscode_servers';
+export interface McpClient {
+    id: string;
+    label: string;
+    shape: ConfigShape;
+    /** Absolute path to the config file, or null when this OS isn't supported. */
+    configPath: string | null;
+    /** Directories that prove the app is installed even before any MCP config exists. */
+    probes: string[];
+    /** What the user must do after we write the file. */
+    afterInstall: string;
+    /**
+     * True for clients `install` skips unless named explicitly — currently only
+     * VS Code, where the DebugAI extension already registers the server and a
+     * second manual entry would show the same tools twice.
+     */
+    optIn?: boolean;
+    note?: string;
+}
+export declare function knownClients(env?: NodeJS.ProcessEnv): McpClient[];
+export declare function findClient(id: string, env?: NodeJS.ProcessEnv): McpClient | undefined;
+/** A client counts as present when its config file OR its app directory exists. */
+export declare function isDetected(client: McpClient): boolean;
+export declare function detectedClients(env?: NodeJS.ProcessEnv): McpClient[];
+/**
+ * The server entry itself. `npx -y` is deliberate: it self-updates on each
+ * launch and needs no global install, which is the only variant that works
+ * identically on a laptop, a devcontainer, and CI.
+ *
+ * No `env` block, ever — the key lives in ~/.debugai/config.json (see
+ * config.ts). Client configs get committed to repos; keys should not.
+ */
+export declare function serverEntry(client: McpClient): Record<string, unknown>;
+/** Top-level key in that client's config file where servers are listed. */
+export declare function serversKey(shape: ConfigShape): string;
+export declare const SERVER_NAME = "debugai";

package/dist/cli/clients.js

@@ -0,0 +1,143 @@
+// Where every MCP client keeps its config, and what shape it wants.
+//
+// This registry is the thing that replaces "copy this JSON blob into the
+// right file" in the README. Adding a client = one entry here; the install
+// command, doctor, and `--print` output all read from it.
+//
+// Two config shapes exist in the wild:
+//   mcpServers      { command, args, env? }                    (most clients)
+//   context_servers { source, command: { path, args, env? } }  (Zed)
+//   servers         { type: "stdio", command, args }           (VS Code native)
+import { existsSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+function appDataDir(env) {
+    const home = homedir();
+    if (platform() === 'win32')
+        return env.APPDATA ?? join(home, 'AppData', 'Roaming');
+    if (platform() === 'darwin')
+        return join(home, 'Library', 'Application Support');
+    return env.XDG_CONFIG_HOME ?? join(home, '.config');
+}
+/** VS Code's per-user directory — Cline stores its MCP config under it too. */
+function vscodeUserDir(env) {
+    return join(appDataDir(env), 'Code', 'User');
+}
+export function knownClients(env = process.env) {
+    const home = homedir();
+    const appData = appDataDir(env);
+    return [
+        {
+            id: 'claude-code',
+            label: 'Claude Code',
+            shape: 'mcpServers',
+            configPath: join(home, '.claude.json'),
+            probes: [join(home, '.claude'), join(home, '.claude.json')],
+            afterInstall: 'Start a new Claude Code session (or run /mcp to reconnect).',
+        },
+        {
+            id: 'claude-desktop',
+            label: 'Claude Desktop',
+            shape: 'mcpServers',
+            configPath: join(appData, 'Claude', 'claude_desktop_config.json'),
+            probes: [join(appData, 'Claude')],
+            afterInstall: 'Quit Claude Desktop completely and reopen it (closing the window is not enough).',
+        },
+        {
+            id: 'cursor',
+            label: 'Cursor',
+            shape: 'mcpServers',
+            configPath: join(home, '.cursor', 'mcp.json'),
+            probes: [join(home, '.cursor')],
+            afterInstall: 'Cursor picks this up on its own — check Settings, MCP for a green dot.',
+        },
+        {
+            id: 'windsurf',
+            label: 'Windsurf',
+            shape: 'mcpServers',
+            configPath: join(home, '.codeium', 'windsurf', 'mcp_config.json'),
+            probes: [join(home, '.codeium', 'windsurf'), join(home, '.codeium')],
+            afterInstall: 'Open Windsurf, Settings, MCP and hit refresh.',
+        },
+        {
+            id: 'zed',
+            label: 'Zed',
+            shape: 'context_servers',
+            configPath: platform() === 'win32'
+                ? join(appData, 'Zed', 'settings.json')
+                : join(env.XDG_CONFIG_HOME ?? join(home, '.config'), 'zed', 'settings.json'),
+            probes: [
+                join(env.XDG_CONFIG_HOME ?? join(home, '.config'), 'zed'),
+                join(appData, 'Zed'),
+            ],
+            afterInstall: 'Zed reloads settings on save — the server appears in the agent panel.',
+        },
+        {
+            id: 'gemini-cli',
+            label: 'Gemini CLI',
+            shape: 'mcpServers',
+            configPath: join(home, '.gemini', 'settings.json'),
+            probes: [join(home, '.gemini')],
+            afterInstall: 'Restart the Gemini CLI session.',
+        },
+        {
+            id: 'cline',
+            label: 'Cline (VS Code)',
+            shape: 'mcpServers',
+            configPath: join(vscodeUserDir(env), 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json'),
+            probes: [join(vscodeUserDir(env), 'globalStorage', 'saoudrizwan.claude-dev')],
+            afterInstall: 'Open the Cline panel, MCP Servers — it reconnects without a VS Code restart.',
+        },
+        {
+            id: 'vscode',
+            label: 'VS Code (native MCP)',
+            shape: 'vscode_servers',
+            configPath: join(vscodeUserDir(env), 'mcp.json'),
+            probes: [vscodeUserDir(env)],
+            optIn: true,
+            note: 'The DebugAI VS Code extension already registers this server (VS Code 1.101+), '
+                + 'plus one-click fix apply and proactive scan. Only install here if you do not want the extension.',
+            afterInstall: 'Run "MCP: List Servers" from the command palette to confirm.',
+        },
+    ];
+}
+export function findClient(id, env = process.env) {
+    return knownClients(env).find((c) => c.id === id.toLowerCase());
+}
+/** A client counts as present when its config file OR its app directory exists. */
+export function isDetected(client) {
+    if (client.configPath && existsSync(client.configPath))
+        return true;
+    return client.probes.some((p) => existsSync(p));
+}
+export function detectedClients(env = process.env) {
+    return knownClients(env).filter(isDetected);
+}
+/**
+ * The server entry itself. `npx -y` is deliberate: it self-updates on each
+ * launch and needs no global install, which is the only variant that works
+ * identically on a laptop, a devcontainer, and CI.
+ *
+ * No `env` block, ever — the key lives in ~/.debugai/config.json (see
+ * config.ts). Client configs get committed to repos; keys should not.
+ */
+export function serverEntry(client) {
+    const command = 'npx';
+    const args = ['-y', '@debugai/mcp'];
+    if (client.shape === 'context_servers') {
+        return { source: 'custom', command: { path: command, args } };
+    }
+    if (client.shape === 'vscode_servers') {
+        return { type: 'stdio', command, args };
+    }
+    return { command, args };
+}
+/** Top-level key in that client's config file where servers are listed. */
+export function serversKey(shape) {
+    if (shape === 'context_servers')
+        return 'context_servers';
+    if (shape === 'vscode_servers')
+        return 'servers';
+    return 'mcpServers';
+}
+export const SERVER_NAME = 'debugai';

package/dist/cli/commands.d.ts

@@ -0,0 +1,7 @@
+export declare function cmdLogin(argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function cmdLogout(_argv: string[], env?: NodeJS.ProcessEnv): number;
+export declare function cmdStatus(_argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function cmdInstall(argv: string[], env?: NodeJS.ProcessEnv): number;
+export declare function cmdUninstall(argv: string[], env?: NodeJS.ProcessEnv): number;
+export declare function cmdDoctor(_argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function cmdSetup(argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;