@debugai/mcp 1.0.0 → 1.1.0

package/README.md

@@ -14,6 +14,19 @@ This package is the same server, standalone. No VS Code required.
 2. Copy your API key (`dbg_...`) from [debugai.io/dashboard](https://debugai.io/dashboard).
 3. Add the server to your MCP client (snippets below). Node 18+ required.
 
+### Set the key once for every client (optional)
+
+Instead of repeating the key in each client's `env` block, write it to
+`~/.debugai/config.json`:
+
+```json
+{ "api_key": "dbg_your_key_here" }
+```
+
+Every MCP client launching `npx -y @debugai/mcp` picks it up — you can then
+drop the `env` block from the snippets below entirely. An explicit
+`DEBUGAI_API_KEY` env var still wins over the file.
+
 ### Claude Code
 
 ```bash
@@ -123,9 +136,10 @@ Example, in Claude Code:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `DEBUGAI_API_KEY` | (none) | Your API key. Required for real analyses. |
-| `DEBUGAI_API_BASE` | DebugAI production | Override for self-hosted or staging setups. |
+| `DEBUGAI_API_KEY` | (none) | Your API key. Falls back to `api_key` in the config file. |
+| `DEBUGAI_API_BASE` | DebugAI production | Override for self-hosted or staging setups. Falls back to `api_base` in the config file. |
 | `DEBUGAI_TIMEOUT_MS` | `150000` | Per-request deadline. Deep analyses can take 30-90s. |
+| `DEBUGAI_CONFIG_PATH` | `~/.debugai/config.json` | Alternate config file location. Rarely needed. |
 
 ## Limits and honesty
 
@@ -140,7 +154,8 @@ Example, in Claude Code:
 ## Troubleshooting
 
 - **"authentication failed"**: key missing or wrong. Check the `env` block in
-  your client config, restart the client. Keys start with `dbg_`.
+  your client config or `~/.debugai/config.json`, restart the client. Keys
+  start with `dbg_`.
 - **Nothing happens on `npx @debugai/mcp`**: correct. It's a stdio server that
   waits for an MCP client to speak first. Run `npx @debugai/mcp --help` to
   verify the install.

package/dist/config.d.ts

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

package/dist/config.js

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

package/dist/index.js

@@ -5,6 +5,7 @@ import { dirname, join } from 'node:path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server.js';
 import { DEFAULT_TIMEOUT_MS } from './backend.js';
+import { configPath, resolveSettings } from './config.js';
 const DEFAULT_API_BASE = 'https://debugai-mvp-production.up.railway.app/api';
 function packageVersion() {
     try {
@@ -27,10 +28,14 @@ Usage:
   npx @debugai/mcp --help
 
 Environment:
-  DEBUGAI_API_KEY      required — your API key (dbg_...) from https://debugai.io/dashboard
+  DEBUGAI_API_KEY      your API key (dbg_...) from https://debugai.io/dashboard
   DEBUGAI_API_BASE     optional — API base URL (default: DebugAI production)
   DEBUGAI_TIMEOUT_MS   optional — per-request deadline in ms (default: ${DEFAULT_TIMEOUT_MS})
 
+Config file (set the key once, every MCP client picks it up):
+  ~/.debugai/config.json    {"api_key": "dbg_..."}
+  Env vars win over the file. api_base is also accepted.
+
 This is a stdio MCP server: it is meant to be launched BY an MCP client
 (Claude Desktop, Claude Code, Cursor, Zed, ...), not run interactively.
 Config snippets: https://www.npmjs.com/package/@debugai/mcp
@@ -51,13 +56,13 @@ function main() {
         process.exitCode = 1;
         return;
     }
-    const apiKey = (process.env.DEBUGAI_API_KEY ?? '').trim();
-    const apiBase = (process.env.DEBUGAI_API_BASE ?? DEFAULT_API_BASE).trim().replace(/\/+$/, '');
+    const { apiKey, apiBase, keySource } = resolveSettings(DEFAULT_API_BASE);
     const rawTimeout = Number(process.env.DEBUGAI_TIMEOUT_MS);
     const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : DEFAULT_TIMEOUT_MS;
     if (!apiKey) {
-        console.error('[debugai-mcp] DEBUGAI_API_KEY not set — tools will return auth errors. ' +
-            'Get a key at https://debugai.io/dashboard and add it to the "env" block of your MCP client config.');
+        console.error('[debugai-mcp] no API key found — tools will return auth errors. ' +
+            'Get a key at https://debugai.io/dashboard, then either set DEBUGAI_API_KEY in your ' +
+            `MCP client config or write it once to ${configPath()} as {"api_key": "dbg_..."}.`);
     }
     else if (!apiKey.startsWith('dbg_')) {
         console.error('[debugai-mcp] warning: DEBUGAI_API_KEY does not look like a DebugAI key (expected dbg_ prefix).');
@@ -70,7 +75,7 @@ function main() {
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGTERM', () => shutdown('SIGTERM'));
     const transport = new StdioServerTransport();
-    server.connect(transport).then(() => console.error(`[debugai-mcp] v${VERSION} connected on stdio (api: ${apiBase})`), (err) => {
+    server.connect(transport).then(() => console.error(`[debugai-mcp] v${VERSION} connected on stdio (api: ${apiBase}, key: ${keySource})`), (err) => {
         console.error('[debugai-mcp] fatal:', err);
         process.exit(1);
     });

package/package.json

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