@debugai/mcp 1.1.0 → 2.1.0

package/dist/cli/jsonc.d.ts

@@ -0,0 +1,12 @@
+export interface ParsedJsonc {
+    value: unknown;
+    hadComments: boolean;
+}
+export declare function stripJsonComments(text: string): {
+    out: string;
+    hadComments: boolean;
+};
+/** Removes trailing commas before } or ] — legal in JSONC, fatal to JSON.parse. */
+export declare function stripTrailingCommas(text: string): string;
+/** Parses JSON or JSONC. Throws the underlying SyntaxError on real malformed input. */
+export declare function parseJsonc(text: string): ParsedJsonc;

package/dist/cli/jsonc.js

@@ -0,0 +1,115 @@
+// Minimal JSONC tolerance for editor config files.
+//
+// Zed's settings.json and VS Code's mcp.json ship WITH comments and often
+// carry trailing commas. `JSON.parse` throws on both, and a naive regex
+// stripper corrupts any string containing "//" — e.g. every URL in the file.
+// So this walks the text character by character with a string-state machine.
+//
+// Round-tripping comments is out of scope: we detect them (`hadComments`) so
+// the caller can warn the user and back the file up before rewriting.
+export function stripJsonComments(text) {
+    let out = '';
+    let hadComments = false;
+    let i = 0;
+    let inString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    while (i < text.length) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (inLineComment) {
+            if (ch === '\n') {
+                inLineComment = false;
+                out += ch;
+            }
+            i++;
+            continue;
+        }
+        if (inBlockComment) {
+            if (ch === '*' && next === '/') {
+                inBlockComment = false;
+                i += 2;
+                continue;
+            }
+            if (ch === '\n')
+                out += ch; // keep line numbers honest for error messages
+            i++;
+            continue;
+        }
+        if (inString) {
+            out += ch;
+            if (ch === '\\') {
+                out += next ?? '';
+                i += 2;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            i++;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            i++;
+            continue;
+        }
+        if (ch === '/' && next === '/') {
+            inLineComment = true;
+            hadComments = true;
+            i += 2;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            inBlockComment = true;
+            hadComments = true;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return { out, hadComments };
+}
+/** Removes trailing commas before } or ] — legal in JSONC, fatal to JSON.parse. */
+export function stripTrailingCommas(text) {
+    let out = '';
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            out += ch;
+            if (ch === '\\') {
+                out += text[i + 1] ?? '';
+                i++;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === ',') {
+            // Look ahead past whitespace for a closer.
+            let j = i + 1;
+            while (j < text.length && /\s/.test(text[j]))
+                j++;
+            if (text[j] === '}' || text[j] === ']')
+                continue; // drop this comma
+        }
+        out += ch;
+    }
+    return out;
+}
+/** Parses JSON or JSONC. Throws the underlying SyntaxError on real malformed input. */
+export function parseJsonc(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return { value: {}, hadComments: false };
+    const { out, hadComments } = stripJsonComments(text);
+    return { value: JSON.parse(stripTrailingCommas(out)), hadComments };
+}

package/dist/cli/ui.d.ts

@@ -0,0 +1,19 @@
+export declare const bold: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const OK: () => string;
+export declare const FAIL: () => string;
+export declare const WARN: () => string;
+export declare const INFO: () => string;
+export declare function say(line?: string): void;
+export declare function heading(text: string): void;
+/**
+ * Opens a URL in the user's browser, best effort. Returns false when there is
+ * clearly no browser to open (headless Linux, CI) so the caller prints the URL
+ * instead of pretending something happened.
+ */
+export declare function openBrowser(url: string): boolean;
+/** Big enough to read across a room, small enough to fit a narrow terminal. */
+export declare function codeBox(code: string): string;

package/dist/cli/ui.js

@@ -0,0 +1,56 @@
+// Terminal output helpers.
+//
+// Everything the CLI prints goes to STDOUT here — but note the MCP server
+// itself prints only to stderr (stdout carries the protocol). The two never
+// run at the same time: a subcommand exits before any transport is created.
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+const useColor = process.stdout.isTTY === true &&
+    !process.env.NO_COLOR &&
+    process.env.TERM !== 'dumb';
+const wrap = (code) => (s) => (useColor ? `[${code}m${s}` : s);
+export const bold = wrap('1');
+export const dim = wrap('2');
+export const red = wrap('31');
+export const green = wrap('32');
+export const yellow = wrap('33');
+export const OK = () => green('✓');
+export const FAIL = () => red('✗');
+export const WARN = () => yellow('!');
+export const INFO = () => dim('·');
+export function say(line = '') {
+    process.stdout.write(`${line}\n`);
+}
+export function heading(text) {
+    say();
+    say(bold(text));
+}
+/**
+ * Opens a URL in the user's browser, best effort. Returns false when there is
+ * clearly no browser to open (headless Linux, CI) so the caller prints the URL
+ * instead of pretending something happened.
+ */
+export function openBrowser(url) {
+    const os = platform();
+    const headlessLinux = os === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY && !process.env.WSL_DISTRO_NAME;
+    if (process.env.CI || headlessLinux)
+        return false;
+    const [cmd, args] = os === 'darwin' ? ['open', [url]] :
+        os === 'win32' ? ['cmd', ['/c', 'start', '', url]] :
+            ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Big enough to read across a room, small enough to fit a narrow terminal. */
+export function codeBox(code) {
+    const inner = `  ${code}  `;
+    const rule = '─'.repeat(inner.length);
+    return [`┌${rule}┐`, `│${inner}│`, `└${rule}┘`].join('\n');
+}

package/dist/config.d.ts

@@ -11,3 +11,13 @@ export interface ResolvedSettings {
 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;
+/** Fields a write may touch. `undefined` leaves the existing value alone. */
+export interface ConfigPatch {
+    apiKey?: string;
+    apiBase?: string;
+}
+export declare function writeFileConfig(patch: ConfigPatch, env?: NodeJS.ProcessEnv): string;
+/** Removes the stored key, keeping any api_base override. True if a key was there. */
+export declare function clearStoredKey(env?: NodeJS.ProcessEnv): boolean;
+/** Keys are long secrets — never print more than their shape. */
+export declare function maskKey(key: string): string;

package/dist/config.js

@@ -6,9 +6,14 @@
 // 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';
+//
+// This file is the ONLY place the API key is ever written. `debugai-mcp
+// install` deliberately does not put the key into any MCP client config:
+// one secret, one file, 0600 — rotating or revoking is a single edit, and a
+// shared or committed client config never carries a live key.
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 export function configPath(env = process.env) {
     const override = (env.DEBUGAI_CONFIG_PATH ?? '').trim();
     return override || join(homedir(), '.debugai', 'config.json');
@@ -46,3 +51,50 @@ export function resolveSettings(defaultApiBase, env = process.env, warn = (msg)
     const apiBase = (envBase || file.apiBase || defaultApiBase).replace(/\/+$/, '');
     return { apiKey, apiBase, keySource };
 }
+export function writeFileConfig(patch, env = process.env) {
+    const path = configPath(env);
+    const existing = loadFileConfig(env, () => { }); // corrupt file → start clean
+    const next = {};
+    const apiKey = patch.apiKey !== undefined ? patch.apiKey : existing.apiKey;
+    const apiBase = patch.apiBase !== undefined ? patch.apiBase : existing.apiBase;
+    if (apiKey)
+        next.api_key = apiKey;
+    if (apiBase)
+        next.api_base = apiBase;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try {
+        chmodSync(tmp, 0o600); // umask can defeat the mode passed to writeFileSync
+    }
+    catch {
+        /* non-POSIX filesystem — best effort */
+    }
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+    return path;
+}
+/** Removes the stored key, keeping any api_base override. True if a key was there. */
+export function clearStoredKey(env = process.env) {
+    const existing = loadFileConfig(env, () => { });
+    if (!existing.apiKey)
+        return false;
+    writeFileConfig({ apiKey: '' }, env);
+    return true;
+}
+/** Keys are long secrets — never print more than their shape. */
+export function maskKey(key) {
+    if (!key)
+        return '(none)';
+    if (key.length <= 12)
+        return `${key.slice(0, 4)}…`;
+    return `${key.slice(0, 8)}…${key.slice(-4)}`;
+}

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_API_BASE = "https://debugai-mvp-production.up.railway.app/api";
+export declare const WEB_BASE = "https://debugai.io";

package/dist/constants.js

@@ -0,0 +1,5 @@
+// Shared endpoints. The API base is overridable per-user (DEBUGAI_API_BASE or
+// api_base in the config file) for self-hosted and staging setups; these are
+// only the defaults.
+export const DEFAULT_API_BASE = 'https://debugai-mvp-production.up.railway.app/api';
+export const WEB_BASE = 'https://debugai.io';

package/dist/deviceLink.d.ts

@@ -0,0 +1,51 @@
+export interface DeviceLinkStart {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    /** URL with the code pre-filled — what we actually open / print first. */
+    verificationUriComplete: string;
+    expiresIn: number;
+    /** Minimum seconds between polls, per the server. */
+    interval: number;
+}
+export type DeviceLinkPoll = {
+    status: 'pending';
+} | {
+    status: 'slow_down';
+    interval: number;
+} | {
+    status: 'expired';
+} | {
+    status: 'denied';
+} | {
+    status: 'linked';
+    apiKey: string;
+    email?: string;
+    tier?: string;
+};
+export interface DeviceLinkOptions {
+    apiBase: string;
+    /** Shown on the approval page so the human knows what they're authorizing. */
+    clientLabel?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare class DeviceLinkError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export declare function startDeviceLink(opts: DeviceLinkOptions): Promise<DeviceLinkStart>;
+/** One poll. Never throws on a normal pending/expired answer — those are statuses. */
+export declare function pollDeviceLink(deviceCode: string, opts: DeviceLinkOptions): Promise<DeviceLinkPoll>;
+export interface WaitOptions extends DeviceLinkOptions {
+    /** Called once per state change so a CLI can show progress. */
+    onTick?: (secondsLeft: number) => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/**
+ * Blocks until the human approves, denies, or the code expires. Honors the
+ * server's interval and backs off when told to (`slow_down`) — a client that
+ * ignores that is how a device flow turns into a self-inflicted DoS.
+ */
+export declare function waitForDeviceLink(start: DeviceLinkStart, opts: WaitOptions): Promise<DeviceLinkPoll>;

package/dist/deviceLink.js

@@ -0,0 +1,125 @@
+// Device-link client — the API-key-paste killer.
+//
+// Modeled on the OAuth 2.0 Device Authorization Grant (RFC 8628), which
+// exists for exactly this shape of problem: a program that can't own a
+// browser redirect needs a credential a human holds. Same three moves:
+//
+//   1. start  → server mints a long secret (device_code) + a short
+//               human-typeable code (user_code) and a verification URL
+//   2. human  → opens the URL in a real browser, signs in, confirms the code
+//   3. poll   → the program exchanges device_code for the credential
+//
+// Deviations from RFC 8628, on purpose: this returns a DebugAI API key
+// rather than an OAuth access token (no token endpoint, no refresh cycle,
+// and the key is the same one the extension and dashboard already use), and
+// there is no client_id — the npm package is the only client.
+//
+// Poll statuses mirror the RFC's error codes so the state machine is
+// familiar: authorization_pending, slow_down, expired_token, access_denied.
+const START_TIMEOUT_MS = 15_000;
+const POLL_TIMEOUT_MS = 15_000;
+export class DeviceLinkError extends Error {
+    status;
+    constructor(message, status = 0) {
+        super(message);
+        this.status = status;
+        this.name = 'DeviceLinkError';
+    }
+}
+async function postJson(url, body, timeoutMs, fetchImpl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const text = await res.text().catch(() => '');
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch {
+            json = { raw: text };
+        }
+        return { status: res.status, json };
+    }
+    catch (err) {
+        if (controller.signal.aborted) {
+            throw new DeviceLinkError(`DebugAI did not answer within ${Math.round(timeoutMs / 1000)}s`, 504);
+        }
+        throw new DeviceLinkError(`Could not reach DebugAI at ${url}: ${err?.message ?? String(err)}`, 0);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function startDeviceLink(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const { status, json } = await postJson(`${opts.apiBase}/device-link/start`, { client_label: opts.clientLabel ?? 'DebugAI MCP server' }, opts.timeoutMs ?? START_TIMEOUT_MS, fetchImpl);
+    if (status !== 200 || !json?.device_code || !json?.user_code) {
+        throw new DeviceLinkError(json?.error
+            ? `DebugAI refused to start the link: ${json.error}`
+            : `DebugAI returned HTTP ${status} when starting the link`, status);
+    }
+    return {
+        deviceCode: String(json.device_code),
+        userCode: String(json.user_code),
+        verificationUri: String(json.verification_uri),
+        verificationUriComplete: String(json.verification_uri_complete ?? json.verification_uri),
+        expiresIn: Number(json.expires_in) || 600,
+        interval: Number(json.interval) || 5,
+    };
+}
+/** One poll. Never throws on a normal pending/expired answer — those are statuses. */
+export async function pollDeviceLink(deviceCode, opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const { status, json } = await postJson(`${opts.apiBase}/device-link/poll`, { device_code: deviceCode }, opts.timeoutMs ?? POLL_TIMEOUT_MS, fetchImpl);
+    if (status === 200 && json?.api_key) {
+        return { status: 'linked', apiKey: String(json.api_key), email: json.email, tier: json.tier };
+    }
+    // A proxy or rate limiter answering 429 means "you are early", never "this
+    // code is dead" — treating it as expired would kill a perfectly good login.
+    if (status === 429) {
+        return { status: 'slow_down', interval: Number(json?.interval) || 15 };
+    }
+    switch (json?.error) {
+        case 'authorization_pending': return { status: 'pending' };
+        case 'slow_down': return { status: 'slow_down', interval: Number(json.interval) || 10 };
+        case 'expired_token': return { status: 'expired' };
+        case 'access_denied': return { status: 'denied' };
+        default:
+            // An unknown 4xx means this device_code will never succeed — treat it as
+            // expired rather than spinning forever against a dead code.
+            if (status >= 400 && status < 500)
+                return { status: 'expired' };
+            throw new DeviceLinkError(`Unexpected response while polling (HTTP ${status})`, status);
+    }
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Blocks until the human approves, denies, or the code expires. Honors the
+ * server's interval and backs off when told to (`slow_down`) — a client that
+ * ignores that is how a device flow turns into a self-inflicted DoS.
+ */
+export async function waitForDeviceLink(start, opts) {
+    const sleep = opts.sleep ?? defaultSleep;
+    const now = opts.now ?? Date.now;
+    const deadline = now() + start.expiresIn * 1000;
+    let interval = Math.max(1, start.interval);
+    for (;;) {
+        if (now() >= deadline)
+            return { status: 'expired' };
+        await sleep(interval * 1000);
+        const result = await pollDeviceLink(start.deviceCode, opts);
+        if (result.status === 'slow_down') {
+            interval = Math.max(interval + 5, result.interval);
+            continue;
+        }
+        if (result.status !== 'pending')
+            return result;
+        opts.onTick?.(Math.max(0, Math.round((deadline - now()) / 1000)));
+    }
+}

package/dist/index.js

@@ -5,8 +5,10 @@ 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 { AuthProvider } from './auth.js';
+import { DEFAULT_API_BASE } from './constants.js';
 import { configPath, resolveSettings } from './config.js';
-const DEFAULT_API_BASE = 'https://debugai-mvp-production.up.railway.app/api';
+import { cmdDoctor, cmdInstall, cmdLogin, cmdLogout, cmdSetup, cmdStatus, cmdUninstall, } from './cli/commands.js';
 function packageVersion() {
     try {
         const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
@@ -17,57 +19,102 @@ function packageVersion() {
     }
 }
 const VERSION = packageVersion();
-const HELP = `debugai-mcp v${VERSION} — DebugAI MCP server (stdio)
+const HELP = `debugai-mcp v${VERSION} — DebugAI MCP server + setup CLI
 
-Exposes the debug_error tool to any MCP client: hand it an error or stack
-trace, get root cause + ranked fixes from DebugAI.
+Quick start (one command, no config files to edit):
+  npx -y @debugai/mcp setup
 
-Usage:
-  npx @debugai/mcp                # start the server (stdio transport)
-  npx @debugai/mcp --version
-  npx @debugai/mcp --help
+Commands:
+  setup          sign in, then wire up every MCP client found on this machine
+  login          sign in via browser and store the key (--key dbg_… to paste one)
+  logout         remove the stored key
+  status         show the active key and account
+  install        add DebugAI to MCP client configs
+                   --list          show every supported client and where it lives
+                   --client=cursor target one client (comma-separate for several)
+                   --all           every supported client, detected or not
+                   --dry-run       print what would change, write nothing
+                   --remove        take the entry back out
+  uninstall      remove DebugAI from every client config
+  doctor         diagnose setup: key, API reachability, client wiring
+  (no command)   run the MCP server on stdio — this is what clients launch
+
+Tools exposed to your agent:
+  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
 
 Environment:
-  DEBUGAI_API_KEY      your API key (dbg_...) from https://debugai.io/dashboard
+  DEBUGAI_API_KEY      your API key (dbg_…). Overrides the stored key.
   DEBUGAI_API_BASE     optional — API base URL (default: DebugAI production)
   DEBUGAI_TIMEOUT_MS   optional — per-request deadline in ms (default: ${DEFAULT_TIMEOUT_MS})
+  DEBUGAI_CONFIG_PATH  optional — alternate config file location
 
-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.
+Config file (written by login, read by every MCP client on this machine):
+  ${configPath()}    {"api_key": "dbg_…"}
 
-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
+Docs: https://debugai.io/start?src=mcp
 `;
-// stdout carries the MCP protocol — every human-facing line goes to stderr.
-function main() {
+const SUBCOMMANDS = new Set([
+    'setup', 'login', 'logout', 'status', 'install', 'uninstall', 'doctor',
+]);
+async function runSubcommand(name, argv) {
+    switch (name) {
+        case 'setup': return cmdSetup(argv);
+        case 'login': return cmdLogin(argv);
+        case 'logout': return cmdLogout(argv);
+        case 'status': return cmdStatus(argv);
+        case 'install': return cmdInstall(argv);
+        case 'uninstall': return cmdUninstall(argv);
+        case 'doctor': return cmdDoctor(argv);
+        default: return 1;
+    }
+}
+// stdout carries the MCP protocol — in server mode every human-facing line goes
+// to stderr. Subcommands print to stdout and exit before any transport exists,
+// so the two can never interleave.
+async function main() {
     const args = process.argv.slice(2);
     if (args.includes('--version') || args.includes('-v')) {
         process.stdout.write(`${VERSION}\n`);
         return;
     }
-    if (args.includes('--help') || args.includes('-h')) {
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
         process.stdout.write(HELP);
         return;
     }
+    const [first, ...rest] = args;
+    if (first && SUBCOMMANDS.has(first)) {
+        process.exitCode = await runSubcommand(first, rest);
+        return;
+    }
+    if (first && !first.startsWith('-')) {
+        console.error(`[debugai-mcp] unknown command: ${first} (see --help)`);
+        process.exitCode = 1;
+        return;
+    }
     if (args.length > 0) {
         console.error(`[debugai-mcp] unknown argument(s): ${args.join(' ')} (see --help)`);
         process.exitCode = 1;
         return;
     }
+    // ── server mode ────────────────────────────────────────────────────────────
     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;
+    // The auth provider re-reads the key on every tool call and can start a
+    // browser sign-in from inside a conversation, so a missing key is a
+    // 20-second detour instead of a dead end. See auth.ts.
+    const auth = new AuthProvider({ apiBase, clientLabel: 'DebugAI MCP server' });
     if (!apiKey) {
-        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_..."}.`);
+        console.error('[debugai-mcp] no API key yet — the first tool call will hand your agent a sign-in link. ' +
+            'To do it now instead, run: npx -y @debugai/mcp login');
     }
     else if (!apiKey.startsWith('dbg_')) {
         console.error('[debugai-mcp] warning: DEBUGAI_API_KEY does not look like a DebugAI key (expected dbg_ prefix).');
     }
-    const server = createServer({ apiKey, apiBase, version: VERSION, timeoutMs });
+    const server = createServer({ apiKey, apiBase, version: VERSION, timeoutMs, auth });
     const shutdown = (signal) => {
         console.error(`[debugai-mcp] received ${signal}, shutting down`);
         void server.close().finally(() => process.exit(0));
@@ -80,4 +127,4 @@ function main() {
         process.exit(1);
     });
 }
-main();
+void main();

package/dist/server.js

@@ -1,7 +1,37 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerDebugError } from './tools/debugError.js';
+import { registerReportOutcome } from './tools/reportOutcome.js';
+// `instructions` is handed to the agent's context at connect time — the one
+// channel the protocol gives a server to say what it is FOR. Without it,
+// agents skip debug_error, because "analyze this error" looks like something
+// they already do themselves. The framing here is deliberate: lead with what
+// the model cannot derive on its own (this project's error history, a fix a
+// human confirmed, a mechanical check), not with "AI-powered analysis".
+const INSTRUCTIONS = `DebugAI is this project's debugging memory and fix verifier.
+
+When a runtime error, exception, stack trace, or failing test output appears,
+call debug_error before reasoning your way to a fix alone. It returns things
+you cannot derive from the code in front of you:
+  - whether this exact error has been seen before in this project, and how often
+  - the fix a human already confirmed worked for it, if there is one
+  - a verification state per fix: mechanically checked and passed, checked and
+    FAILED, or not checked at all (never treat "not checked" as verified)
+  - machine-applicable edits (exact old/new strings) you can apply directly
+
+After you apply or abandon a fix, call report_outcome with the debug_log_id.
+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.
+
+When you present findings that came from DebugAI's memory or verification,
+say so — "DebugAI has seen this 3 times; the confirmed fix is …" — so the user
+can tell which claims were checked and which are your own reasoning.
+
+Not signed in yet? The first tool call returns a short code and a URL. Read
+both out to the user; once they confirm in the browser, retry the same call.
+No config editing and no client restart needed.`;
 export function createServer(config) {
-    const server = new McpServer({ name: 'debugai', version: config.version }, { capabilities: { tools: { listChanged: true } } });
+    const server = new McpServer({ name: 'debugai', version: config.version }, { capabilities: { tools: { listChanged: true } }, instructions: INSTRUCTIONS });
     registerDebugError(server, config);
+    registerReportOutcome(server, config);
     return server;
 }

package/dist/tools/authGate.d.ts

@@ -0,0 +1,10 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { BackendConfig } from '../backend.js';
+export type AuthGate = {
+    ok: true;
+    config: BackendConfig;
+} | {
+    ok: false;
+    result: CallToolResult;
+};
+export declare function resolveAuth(config: BackendConfig): Promise<AuthGate>;