@4da/mcp-server 6.0.1 → 6.0.2

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 6.0.2 — 2026-10-04
+
+### `--setup` writes the files editors actually read
+
+Three of the four editors `--setup` reported as configured were configured in
+files those editors never read, so nothing happened:
+
+| Editor | Before | Now |
+|---|---|---|
+| VS Code | `~/.vscode/mcp.json` | the user profile's `mcp.json`: `%APPDATA%\Code\User\` (Windows), `~/Library/Application Support/Code/User/` (macOS), `$XDG_CONFIG_HOME/Code/User/` (Linux, default `~/.config`), key `servers`, `"type": "stdio"` |
+| Windsurf | `~/.windsurf/mcp.json` | `~/.codeium/windsurf/mcp_config.json`, key `mcpServers` |
+| Claude Code | `mcpServers` in the project's `.claude/settings.json` (or, outside a project, rewrote `~/.claude.json`) | prints `claude mcp add --scope user 4da -- npx @4da/mcp-server`; `~/.claude.json` is never edited |
+
+Added: VS Code Insiders, Claude Desktop (`claude_desktop_config.json`) and
+Devin Desktop / Devin CLI (`~/.config/devin/mcp_config.json`,
+`%APPDATA%\devin\` on Windows), Windsurf's successor. Cursor
+(`~/.cursor/mcp.json`) was already right.
+
+- **A config file setup cannot parse is left untouched.** It used to be read
+  as `{}`, so a VS Code `mcp.json` with a comment or a trailing comma (both
+  legal there) was replaced by our entry alone, deleting every other server.
+  Files are now parsed as JSONC and edited in place with `jsonc-parser`
+  (Microsoft's, the parser VS Code uses; no dependencies of its own), which
+  keeps comments, formatting, other servers and other keys. A file that does
+  not parse is reported with the entry to add by hand.
+- An existing `4da` entry is updated, not duplicated, and keeps its other
+  fields (`env`); an identical one is left alone, so a second run writes
+  nothing.
+- Every modified file is backed up first (`<file>.bak`; an earlier backup is
+  never overwritten) and replaced atomically (temp file, then rename).
+- `--setup --dry-run` wrote anyway when run through `npx @4da/mcp-server`
+  (only the `4da-mcp-setup` entry honoured the flag). It now writes nothing on
+  either, and prints each file and the exact entry it would add.
+
+### Clearer answers when the database cannot help
+
+- A desktop-only tool (`get_relevant_content`, `get_actionable_signals`,
+  `knowledge_gaps`, `record_feedback`, `developer_dna`) called without the
+  desktop app's database answered `[]`, which reads as "nothing relevant". It
+  now carries a `desktop_app_note` saying it needs the app.
+- A database file that is damaged or not SQLite answered every call with
+  SQLite's bare "file is not a database". The message now names the file and
+  what to do, and never advises deleting it (`--doctor`'s integrity check used
+  to say "Try deleting data/4da.db"). The handle a failed open left behind is
+  closed, so on Windows the file can be moved aside while the server runs.
+- The database lookup no longer checks `data/4da.db` two directories above the
+  server's own files, a leftover from when the server was a folder of the app
+  repository; installed, it pointed into `node_modules/@4da/`.
+
+- Dependencies: `@modelcontextprotocol/server` ^2.2.0, `hono` ^4.13.12; dev: `@types/node` ^26.6.3, `vitest` ^5.0.3 (#2).
+
 ## 6.0.1 — 2026-10-04
 
 ### The server has its own repository

package/README.md

@@ -45,9 +45,9 @@ claude plugin install 4da@4da
 The hook: when your agent edits a dependency's version in `package.json`, `Cargo.toml`, `pyproject.toml`, `requirements.txt` or `go.mod`, it is told which packages moved and given the exact `dependency_check` and `upgrade_impact` calls to make before it installs and builds. The hook is plain Node, contacts nothing, and stays silent for every other edit.
 
 <details>
-<summary><b>Cursor / Windsurf</b></summary>
+<summary><b>Cursor / Windsurf / Devin Desktop</b></summary>
 
-Add to `~/.cursor/mcp.json` or `~/.windsurf/mcp.json`:
+Add to `~/.cursor/mcp.json` (Cursor), `~/.codeium/windsurf/mcp_config.json` (Windsurf), or `~/.config/devin/mcp_config.json` (Devin Desktop and Devin CLI; `%APPDATA%devinmcp_config.json` on Windows):
 ```json
 {
   "mcpServers": {
@@ -63,7 +63,7 @@ Add to `~/.cursor/mcp.json` or `~/.windsurf/mcp.json`:
 <details>
 <summary><b>VS Code (Copilot)</b></summary>
 
-Add to `~/.vscode/mcp.json`:
+Run **MCP: Open User Configuration** and add the entry, or edit the file directly: `%APPDATA%CodeUsermcp.json` (Windows), `~/Library/Application Support/Code/User/mcp.json` (macOS), `~/.config/Code/User/mcp.json` (Linux). VS Code uses `servers`, not `mcpServers`:
 ```json
 {
   "servers": {
@@ -97,8 +97,11 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 <summary><b>Auto-setup</b> (detects all installed editors)</summary>
 
 ```bash
+npx @4da/mcp-server --setup --dry-run   # show each file and entry, write nothing
 npx @4da/mcp-server --setup
 ```
+
+Writes Cursor, VS Code (and Insiders), Windsurf, Devin Desktop and Claude Desktop configs it finds, merging into what is there: other servers, settings and comments are kept, a backup (`.bak`) is written first, and a file it cannot parse is left untouched with the entry to add by hand. For Claude Code it prints the `claude mcp add` command instead of editing `~/.claude.json`.
 </details>
 
 Then ask your AI: **"What changes if I upgrade X to Y?"**, **"Scan for vulnerabilities"** or **"What should I upgrade first?"**

package/dist/db.d.ts

@@ -30,6 +30,20 @@ export declare function desktopAppDbPaths(platform?: NodeJS.Platform, env?: Node
  * in, so agent memory and decisions did not follow the user between projects.
  */
 export declare function standaloneDbPath(): string;
+/**
+ * Whether an error says the database file itself is unreadable: not SQLite at
+ * all, or damaged. better-sqlite3 reports these as SQLITE_NOTADB ("file is not
+ * a database") and SQLITE_CORRUPT ("database disk image is malformed").
+ */
+export declare function isUnreadableDbError(error: unknown): boolean;
+/**
+ * What to tell the user about an unreadable database. Every tool call used to
+ * answer with the bare SQLite text ("file is not a database"), with no way
+ * out. Nothing is deleted or moved automatically: the desktop app's database
+ * can be the user's whole corpus, and the standalone one holds their recorded
+ * decisions and agent memory.
+ */
+export declare function unreadableDbMessage(absolutePath: string, error: unknown): string;
 export interface DatabaseValidationResult {
     valid: boolean;
     error?: string;
@@ -98,6 +112,8 @@ export declare const DEPENDENCY_GROUP_QUERY = "SELECT DISTINCT package_name, lan
 export declare class FourDADatabase {
     private db;
     private _isStandalone;
+    /** Absolute path of the open database file. */
+    readonly dbPath: string;
     constructor(dbPath?: string);
     /**
      * Whether this database was freshly created in standalone mode

package/dist/db.js

@@ -8,8 +8,6 @@
 import path from "path";
 import * as fs from "fs";
 import * as os from "os";
-import { fileURLToPath } from "node:url";
-import { dirname } from "node:path";
 import { checkNativeBindings, isNativeBindingError, nativeBindingMessage } from "./native-bindings.js";
 let Database;
 try {
@@ -23,38 +21,37 @@ catch (err) {
 export function nativeBindingProblem() {
     return checkNativeBindings(Database);
 }
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
 import { dbRecoveryNote, readDbRecoveredMarker, readEngineBlockMarker } from "./freshness-markers.js";
 /**
  * Resolve the database path by checking multiple locations in priority order:
  * 1. FOURDA_DB_PATH env var
- * 2. data/4da.db relative to cwd (development)
- * 3. data/4da.db relative to project root (mcp-4da-server is inside project root)
- * 4. Platform-specific Tauri app data dirs (production)
- * 5. Final fallback: data/4da.db relative to cwd
+ * 2. data/4da.db relative to cwd: the desktop app's development database,
+ *    when the server is started in a checkout of the app's repository
+ * 3. The deployed desktop app's database (desktopAppDbPaths)
+ * 4. Otherwise the standalone database (standaloneDbPath), created on first use
+ *
+ * Until 6.0.2 a step between 2 and 3 looked for data/4da.db two directories
+ * above this file, which found the app's database while this server was the
+ * app repository's mcp-4da-server/ folder. Since the server moved to its own
+ * repository (6.0.1) that resolves to node_modules/@4da/ or to the folder
+ * holding a clone, never to an app database, so it was removed.
  */
 function getDefaultDbPath() {
     // 1. Environment variable (highest priority)
     if (process.env.FOURDA_DB_PATH) {
         return process.env.FOURDA_DB_PATH;
     }
-    // 2. Relative to cwd (development)
+    // 2. Relative to cwd (the app repository's development database)
     const cwdPath = path.resolve(process.cwd(), "data", "4da.db");
     if (fs.existsSync(cwdPath)) {
         return cwdPath;
     }
-    // 3. Relative to project root (mcp-4da-server is inside project root)
-    const projectRootPath = path.resolve(__dirname, "..", "..", "data", "4da.db");
-    if (fs.existsSync(projectRootPath)) {
-        return projectRootPath;
-    }
-    // 4. The desktop app's own database, where the deployed app keeps it.
+    // 3. The desktop app's own database, where the deployed app keeps it.
     for (const appDataPath of desktopAppDbPaths()) {
         if (fs.existsSync(appDataPath))
             return appDataPath;
     }
-    // 5. No desktop database: the standalone database, in the user's data dir.
+    // 4. No desktop database: the standalone database, in the user's data dir.
     return standaloneDbPath();
 }
 /**
@@ -104,6 +101,38 @@ export function standaloneDbPath() {
             : process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
     return path.join(base, "4da-mcp", "standalone.db");
 }
+/**
+ * Whether an error says the database file itself is unreadable: not SQLite at
+ * all, or damaged. better-sqlite3 reports these as SQLITE_NOTADB ("file is not
+ * a database") and SQLITE_CORRUPT ("database disk image is malformed").
+ */
+export function isUnreadableDbError(error) {
+    const code = error?.code;
+    if (code === "SQLITE_NOTADB" || code === "SQLITE_CORRUPT")
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /file is not a database|database disk image is malformed/i.test(message);
+}
+/**
+ * What to tell the user about an unreadable database. Every tool call used to
+ * answer with the bare SQLite text ("file is not a database"), with no way
+ * out. Nothing is deleted or moved automatically: the desktop app's database
+ * can be the user's whole corpus, and the standalone one holds their recorded
+ * decisions and agent memory.
+ */
+export function unreadableDbMessage(absolutePath, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const isStandaloneFile = path.resolve(absolutePath) === path.resolve(standaloneDbPath());
+    const remedy = isStandaloneFile
+        ? "It is this server's standalone database: move it aside (keep it if it holds decisions or agent " +
+            "memory you want) and the next call creates a new one."
+        : process.env.FOURDA_DB_PATH
+            ? "FOURDA_DB_PATH points at it: point it at a valid 4DA database, or unset it to use the default."
+            : "If it is the 4DA desktop app's database, start the app, which checks its database on startup. " +
+                "Do not delete it: it may be your only copy of the app's data.";
+    return (`The 4DA database at ${absolutePath} cannot be read (${detail}): the file is damaged or is not ` +
+        `a SQLite database. ${remedy} Run \`npx @4da/mcp-server --doctor\` for details.`);
+}
 /** Marker table written into every standalone database. */
 const STANDALONE_MARKER = "mcp_standalone";
 /**
@@ -200,6 +229,8 @@ export const DEPENDENCY_GROUP_QUERY = "SELECT DISTINCT package_name, language, p
 export class FourDADatabase {
     db;
     _isStandalone = false;
+    /** Absolute path of the open database file. */
+    dbPath;
     constructor(dbPath) {
         const resolvedPath = dbPath || getDefaultDbPath();
         // Resolve path - if relative, resolve from cwd
@@ -214,15 +245,29 @@ export class FourDADatabase {
                 fs.mkdirSync(dir, { recursive: true });
             }
         }
+        let opened = null;
         try {
-            this.db = new Database(absolutePath, { readonly: false }); // Need write for feedback
-            this.db.pragma("journal_mode = WAL");
+            opened = new Database(absolutePath, { readonly: false }); // Need write for feedback
+            opened.pragma("journal_mode = WAL");
         }
         catch (error) {
+            // Close the handle a failed pragma leaves open: every tool call retries
+            // the open, and on Windows each leaked handle also keeps the file locked
+            // against the move-aside the message below suggests.
+            try {
+                opened?.close();
+            }
+            catch {
+                // Nothing to close when the open itself failed.
+            }
             throw new Error(isNativeBindingError(error)
                 ? nativeBindingMessage(error)
-                : `Failed to open 4DA database at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
+                : isUnreadableDbError(error)
+                    ? unreadableDbMessage(absolutePath, error)
+                    : `Failed to open 4DA database at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
+        this.db = opened;
+        this.dbPath = absolutePath;
         // Standalone mode: create schema for a brand-new database, and recognise
         // an existing standalone database as one on every later session.
         if (isNew) {
@@ -302,8 +347,10 @@ export class FourDADatabase {
                 if (integrityStatus !== "ok") {
                     return {
                         valid: false,
-                        error: `Database integrity check failed: ${integrityStatus}. `
-                            + "The database file may be corrupt. Try deleting data/4da.db and restarting 4DA.",
+                        // It used to say "Try deleting data/4da.db": a path that is not
+                        // where the app keeps its database, and advice that destroys the
+                        // user's only copy of it.
+                        error: unreadableDbMessage(absolutePath, new Error(`integrity check failed: ${integrityStatus}`)),
                     };
                 }
             }
@@ -322,8 +369,9 @@ export class FourDADatabase {
         catch (error) {
             return {
                 valid: false,
-                error: `Failed to open database at ${absolutePath}: `
-                    + (error instanceof Error ? error.message : String(error)),
+                error: isUnreadableDbError(error)
+                    ? unreadableDbMessage(absolutePath, error)
+                    : `Failed to open database at ${absolutePath}: ` + (error instanceof Error ? error.message : String(error)),
             };
         }
         finally {

package/dist/index.js

@@ -68,7 +68,7 @@ const SERVER_VERSION = (() => {
         return "0.0.0";
     }
 })();
-import { createDatabase, DEPENDENCY_GROUP_QUERY, FourDADatabase } from "./db.js";
+import { createDatabase, DEPENDENCY_GROUP_QUERY, FourDADatabase, isUnreadableDbError, unreadableDbMessage, } from "./db.js";
 // =============================================================================
 // Server Setup
 // =============================================================================
@@ -376,7 +376,14 @@ export function buildServer() {
             return await dispatchTool(name, database, args);
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            // A database that turns out damaged mid-session (SQLITE_CORRUPT on a
+            // page the open did not touch) gets the same guidance as one that
+            // fails to open, instead of the bare SQLite text.
+            const errorMessage = db && isUnreadableDbError(error)
+                ? unreadableDbMessage(db.dbPath, error)
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
             return {
                 content: [
                     {
@@ -441,6 +448,7 @@ async function main() {
                         refused unless MCP_AUTH_SECRET is set; authentication
                         is then mandatory for every request.
     --setup             Detect editors and write MCP config
+    --dry-run           With --setup: print each file and entry, write nothing
     --doctor            Validate database, bindings, and LLM providers
 
   Environment:
@@ -463,7 +471,7 @@ async function main() {
     }
     // Setup command: configure editors
     if (args.includes("--setup") || args.includes("setup")) {
-        runSetup();
+        runSetup(args.includes("--dry-run"));
         return;
     }
     // Doctor command: validate installation health

package/dist/setup.d.ts

@@ -6,12 +6,85 @@
  * the user can start using 4DA tools immediately after install.
  *
  * Usage:
- *   npx @4da/mcp-server --setup
- *   4da-mcp-setup
+ *   npx @4da/mcp-server --setup [--dry-run]
+ *   4da-mcp-setup [--dry-run]
  *   pnpm run setup
+ *
+ * Audited 2026-10-05: three of the four editors were configured in files the
+ * editor never reads (`~/.vscode/mcp.json`, `~/.windsurf/mcp.json`, and
+ * `mcpServers` in a project's `.claude/settings.json`), and any config file
+ * that failed `JSON.parse` (VS Code's `mcp.json` is JSONC: comments and
+ * trailing commas are legal) was replaced by `{}` plus our entry, deleting
+ * every other server the user had. Each path below cites the doc it was
+ * checked against, and a file that cannot be parsed is never written.
+ */
+/** The Claude Code command printed instead of editing `~/.claude.json`. */
+export declare const CLAUDE_CODE_COMMAND = "claude mcp add --scope user 4da -- npx @4da/mcp-server";
+/** Where the paths are resolved: injected so tests can stand in any platform. */
+export interface SetupContext {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    home: string;
+}
+export declare function currentContext(): SetupContext;
+/** An editor whose MCP config file this setup writes. */
+export interface EditorTarget {
+    name: string;
+    /** Config file the server entry goes into. */
+    configPath: string;
+    /** Directory whose existence means the editor is installed. */
+    detectDir: string;
+    /** Top-level key holding the servers: VS Code uses `servers`, the rest `mcpServers`. */
+    key: "mcpServers" | "servers";
+    /** The value written under `<key>["4da"]`. */
+    entry: Record<string, unknown>;
+    /** Where the path and key were verified. */
+    docs: string;
+}
+/**
+ * Every editor this setup can write, with its config path on `ctx.platform`.
+ * Pure: nothing is read from disk here.
+ */
+export declare function editorTargets(ctx?: SetupContext): EditorTarget[];
+/**
+ * Claude Code keeps user- and local-scope servers in `~/.claude.json`
+ * (`$CLAUDE_CONFIG_DIR/.claude.json` when set), a file it rewrites itself and
+ * that also holds the sign-in session and per-project state. Setup never
+ * edits it: it prints the `claude mcp add` command, which does.
+ * https://code.claude.com/docs/en/mcp
+ */
+export declare function claudeCodeConfigPath(ctx?: SetupContext): string;
+export type PlanAction = "create" | "update" | "unchanged" | "refuse";
+export interface ConfigPlan {
+    action: PlanAction;
+    /** The full new file content for create/update. */
+    content?: string;
+    /** Why a file is refused, for the user. */
+    reason?: string;
+}
+/**
+ * Decide what writing `entry` under `<key>["4da"]` does to a config file whose
+ * current text is `existing` (null when it does not exist).
+ *
+ * The file is parsed as JSONC (comments and trailing commas allowed) and
+ * edited in place with `jsonc-parser`'s `modify`, so other servers, other keys,
+ * comments and formatting all survive. A file that does not parse is refused,
+ * never replaced. An existing `4da` entry keeps its other fields (`env`, say);
+ * only the fields setup owns are set.
+ */
+export declare function planConfig(existing: string | null, key: string, entry: Record<string, unknown>): ConfigPlan;
+/**
+ * Write `content` to `filePath`: back up an existing file first, then write a
+ * temp file beside it and rename it over the original, so an interrupted run
+ * leaves either the old file or the new one, never half of one. A symlinked
+ * config (a dotfiles repo) is written through to its target.
+ * @returns The backup path, when one was made.
  */
+export declare function writeConfigAtomic(filePath: string, content: string): string | null;
+type Log = (line: string) => void;
 /**
  * Run the setup wizard: detect editors and write MCP configurations.
  * @param dryRun If true, only report what would be written without modifying files.
  */
-export declare function runSetup(dryRun?: boolean): void;
+export declare function runSetup(dryRun?: boolean, ctx?: SetupContext, log?: Log): void;
+export {};

package/dist/setup.js

@@ -7,160 +7,343 @@
  * the user can start using 4DA tools immediately after install.
  *
  * Usage:
- *   npx @4da/mcp-server --setup
- *   4da-mcp-setup
+ *   npx @4da/mcp-server --setup [--dry-run]
+ *   4da-mcp-setup [--dry-run]
  *   pnpm run setup
+ *
+ * Audited 2026-10-05: three of the four editors were configured in files the
+ * editor never reads (`~/.vscode/mcp.json`, `~/.windsurf/mcp.json`, and
+ * `mcpServers` in a project's `.claude/settings.json`), and any config file
+ * that failed `JSON.parse` (VS Code's `mcp.json` is JSONC: comments and
+ * trailing commas are legal) was replaced by `{}` plus our entry, deleting
+ * every other server the user had. Each path below cites the doc it was
+ * checked against, and a file that cannot be parsed is never written.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import path from "node:path";
 import { homedir } from "node:os";
+import jsonc from "jsonc-parser";
+/** The command every editor runs. */
+const SERVER_COMMAND = { command: "npx", args: ["@4da/mcp-server"] };
 /** MCP config snippet for editors that use the standard mcpServers format */
 const MCP_CONFIG = {
-    "4da": {
-        command: "npx",
-        args: ["@4da/mcp-server"],
-    },
+    "4da": SERVER_COMMAND,
 };
+/** The Claude Code command printed instead of editing `~/.claude.json`. */
+export const CLAUDE_CODE_COMMAND = "claude mcp add --scope user 4da -- npx @4da/mcp-server";
+export function currentContext() {
+    return { platform: process.platform, env: process.env, home: homedir() };
+}
+function pathFor(ctx) {
+    return ctx.platform === "win32" ? path.win32 : path.posix;
+}
+/** `%APPDATA%` on Windows, the Electron-style config base elsewhere. */
+function roamingDir(ctx) {
+    const p = pathFor(ctx);
+    return ctx.env.APPDATA?.trim() || p.join(ctx.home, "AppData", "Roaming");
+}
+function xdgConfigDir(ctx) {
+    return ctx.env.XDG_CONFIG_HOME?.trim() || pathFor(ctx).join(ctx.home, ".config");
+}
 /**
- * Safely read and parse a JSON file, returning empty object on failure.
+ * The per-platform user-data dir of a desktop app (Electron `appData`):
+ * `%APPDATA%\<name>`, `~/Library/Application Support/<name>`,
+ * `$XDG_CONFIG_HOME/<name>` (default `~/.config/<name>`).
  */
-function readJsonSafe(filePath) {
-    if (!existsSync(filePath))
-        return {};
-    try {
-        return JSON.parse(readFileSync(filePath, "utf-8"));
-    }
-    catch {
-        return {};
-    }
+function appDataDir(ctx, name) {
+    const p = pathFor(ctx);
+    if (ctx.platform === "win32")
+        return p.join(roamingDir(ctx), name);
+    if (ctx.platform === "darwin")
+        return p.join(ctx.home, "Library", "Application Support", name);
+    return p.join(xdgConfigDir(ctx), name);
 }
 /**
- * Ensure directory exists and write JSON to file.
+ * Every editor this setup can write, with its config path on `ctx.platform`.
+ * Pure: nothing is read from disk here.
  */
-function writeJsonFile(filePath, data) {
-    const dir = dirname(filePath);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
-}
-const editors = [
-    {
-        name: "Claude Code",
-        detect: () => {
-            // Project-level config takes priority
-            const projectClaudeDir = join(process.cwd(), ".claude");
-            if (existsSync(projectClaudeDir)) {
-                return join(projectClaudeDir, "settings.json");
-            }
-            // Fall back to global config
-            return join(homedir(), ".claude.json");
-        },
-        write: (configPath) => {
-            const config = readJsonSafe(configPath);
-            const mcpServers = (config.mcpServers || {});
-            mcpServers["4da"] = MCP_CONFIG["4da"];
-            config.mcpServers = mcpServers;
-            writeJsonFile(configPath, config);
-            console.log(`  Written: ${configPath}`);
-        },
-    },
-    {
-        name: "Cursor",
-        detect: () => {
-            const cursorDir = join(homedir(), ".cursor");
-            if (existsSync(cursorDir)) {
-                return join(cursorDir, "mcp.json");
-            }
-            return null;
-        },
-        write: (configPath) => {
-            const config = readJsonSafe(configPath);
-            const mcpServers = (config.mcpServers || {});
-            mcpServers["4da"] = MCP_CONFIG["4da"];
-            config.mcpServers = mcpServers;
-            writeJsonFile(configPath, config);
-            console.log(`  Written: ${configPath}`);
-        },
-    },
-    {
-        name: "VS Code (Copilot)",
-        detect: () => {
-            const vscodePath = join(homedir(), ".vscode");
-            if (existsSync(vscodePath)) {
-                return join(vscodePath, "mcp.json");
-            }
-            return null;
+export function editorTargets(ctx = currentContext()) {
+    const p = pathFor(ctx);
+    const vscodeEntry = { type: "stdio", ...SERVER_COMMAND };
+    const vscode = (name, product) => {
+        const userDir = p.join(appDataDir(ctx, product), "User");
+        return {
+            name,
+            // The default profile's user-level file; it sits beside settings.json.
+            // A non-default profile keeps its own under User/profiles/<id>/, which
+            // VS Code does not name anywhere setup could find it.
+            configPath: p.join(userDir, "mcp.json"),
+            detectDir: userDir,
+            key: "servers",
+            entry: vscodeEntry,
+            docs: "https://code.visualstudio.com/docs/copilot/reference/mcp-configuration",
+        };
+    };
+    const devinDir = ctx.platform === "win32" ? p.join(roamingDir(ctx), "devin") : p.join(xdgConfigDir(ctx), "devin");
+    const windsurfDir = p.join(ctx.home, ".codeium", "windsurf");
+    return [
+        {
+            name: "Cursor",
+            configPath: p.join(ctx.home, ".cursor", "mcp.json"),
+            detectDir: p.join(ctx.home, ".cursor"),
+            key: "mcpServers",
+            entry: SERVER_COMMAND,
+            docs: "https://cursor.com/docs/mcp",
         },
-        write: (configPath) => {
-            const config = readJsonSafe(configPath);
-            // VS Code uses "servers" key instead of "mcpServers"
-            const servers = (config.servers || {});
-            servers["4da"] = {
-                type: "stdio",
-                command: "npx",
-                args: ["@4da/mcp-server"],
-            };
-            config.servers = servers;
-            writeJsonFile(configPath, config);
-            console.log(`  Written: ${configPath}`);
+        vscode("VS Code (Copilot)", "Code"),
+        vscode("VS Code Insiders (Copilot)", "Code - Insiders"),
+        {
+            name: "Windsurf",
+            configPath: p.join(windsurfDir, "mcp_config.json"),
+            detectDir: windsurfDir,
+            key: "mcpServers",
+            entry: SERVER_COMMAND,
+            docs: "https://docs.devin.ai/cli/reference/configuration/read-config-from",
         },
-    },
-    {
-        name: "Windsurf",
-        detect: () => {
-            const windsurfDir = join(homedir(), ".windsurf");
-            if (existsSync(windsurfDir)) {
-                return join(windsurfDir, "mcp.json");
-            }
-            return null;
+        {
+            // Windsurf's successor. Its Cascade agent and the Devin CLI read the
+            // same user-level file.
+            name: "Devin Desktop / Devin CLI",
+            configPath: p.join(devinDir, "mcp_config.json"),
+            detectDir: devinDir,
+            key: "mcpServers",
+            entry: SERVER_COMMAND,
+            docs: "https://docs.devin.ai/desktop/cascade/mcp",
         },
-        write: (configPath) => {
-            const config = readJsonSafe(configPath);
-            const mcpServers = (config.mcpServers || {});
-            mcpServers["4da"] = MCP_CONFIG["4da"];
-            config.mcpServers = mcpServers;
-            writeJsonFile(configPath, config);
-            console.log(`  Written: ${configPath}`);
+        {
+            name: "Claude Desktop",
+            configPath: p.join(appDataDir(ctx, "Claude"), "claude_desktop_config.json"),
+            detectDir: appDataDir(ctx, "Claude"),
+            key: "mcpServers",
+            entry: SERVER_COMMAND,
+            docs: "https://modelcontextprotocol.io/docs/develop/connect-local-servers",
         },
-    },
-];
+    ];
+}
+/**
+ * Claude Code keeps user- and local-scope servers in `~/.claude.json`
+ * (`$CLAUDE_CONFIG_DIR/.claude.json` when set), a file it rewrites itself and
+ * that also holds the sign-in session and per-project state. Setup never
+ * edits it: it prints the `claude mcp add` command, which does.
+ * https://code.claude.com/docs/en/mcp
+ */
+export function claudeCodeConfigPath(ctx = currentContext()) {
+    const p = pathFor(ctx);
+    const configDir = ctx.env.CLAUDE_CONFIG_DIR?.trim();
+    return configDir ? p.join(configDir, ".claude.json") : p.join(ctx.home, ".claude.json");
+}
+function lineOf(text, offset) {
+    return text.slice(0, offset).split("\n").length;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function sameJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Decide what writing `entry` under `<key>["4da"]` does to a config file whose
+ * current text is `existing` (null when it does not exist).
+ *
+ * The file is parsed as JSONC (comments and trailing commas allowed) and
+ * edited in place with `jsonc-parser`'s `modify`, so other servers, other keys,
+ * comments and formatting all survive. A file that does not parse is refused,
+ * never replaced. An existing `4da` entry keeps its other fields (`env`, say);
+ * only the fields setup owns are set.
+ */
+export function planConfig(existing, key, entry) {
+    if (existing === null || existing.trim() === "") {
+        return {
+            action: existing === null ? "create" : "update",
+            content: JSON.stringify({ [key]: { "4da": entry } }, null, 2) + "\n",
+        };
+    }
+    const errors = [];
+    const root = jsonc.parse(existing, errors, { allowTrailingComma: true, disallowComments: false });
+    if (errors.length > 0) {
+        const first = errors[0];
+        return {
+            action: "refuse",
+            reason: `it does not parse (${jsonc.printParseErrorCode(first.error)} at line ${lineOf(existing, first.offset)})`,
+        };
+    }
+    if (!isPlainObject(root)) {
+        return { action: "refuse", reason: "its top level is not a JSON object" };
+    }
+    const servers = root[key];
+    if (servers !== undefined && !isPlainObject(servers)) {
+        return { action: "refuse", reason: `its "${key}" is not an object` };
+    }
+    const current = servers?.["4da"];
+    if (current !== undefined && !isPlainObject(current)) {
+        return { action: "refuse", reason: `its "${key}"."4da" is not an object` };
+    }
+    if (current && Object.entries(entry).every(([field, value]) => sameJson(current[field], value))) {
+        return { action: "unchanged" };
+    }
+    const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+    const indent = /^([ \t]+)\S/m.exec(existing)?.[1] ?? "  ";
+    const formattingOptions = {
+        insertSpaces: !indent.startsWith("\t"),
+        tabSize: indent.startsWith("\t") ? 1 : indent.length,
+        eol,
+    };
+    let content = existing;
+    // Field by field when the entry exists, so its other fields and any
+    // comments inside it stay; whole when it does not.
+    const edits = current
+        ? Object.entries(entry).map(([field, value]) => [[key, "4da", field], value])
+        : [[[key, "4da"], entry]];
+    for (const [jsonPath, value] of edits) {
+        content = jsonc.applyEdits(content, jsonc.modify(content, jsonPath, value, { formattingOptions }));
+    }
+    return { action: "update", content };
+}
+/** Read a config file's text; null when it does not exist. */
+function readConfig(filePath) {
+    return existsSync(filePath) ? readFileSync(filePath, "utf-8") : null;
+}
+/** `<file>.bak`, or a timestamped name when that is taken: an earlier backup is never overwritten. */
+function backupPath(filePath) {
+    const plain = `${filePath}.bak`;
+    if (!existsSync(plain))
+        return plain;
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..*$/, "");
+    for (let n = 0;; n++) {
+        const candidate = `${filePath}.${stamp}${n === 0 ? "" : `-${n}`}.bak`;
+        if (!existsSync(candidate))
+            return candidate;
+    }
+}
+/**
+ * Write `content` to `filePath`: back up an existing file first, then write a
+ * temp file beside it and rename it over the original, so an interrupted run
+ * leaves either the old file or the new one, never half of one. A symlinked
+ * config (a dotfiles repo) is written through to its target.
+ * @returns The backup path, when one was made.
+ */
+export function writeConfigAtomic(filePath, content) {
+    // Only a symlinked file is resolved: resolving the whole path would turn
+    // macOS's /var/... into /private/var/... in every path reported back.
+    const target = existsSync(filePath) && lstatSync(filePath).isSymbolicLink() ? realpathSync(filePath) : filePath;
+    mkdirSync(path.dirname(target), { recursive: true });
+    let backup = null;
+    if (existsSync(target)) {
+        backup = backupPath(target);
+        copyFileSync(target, backup);
+    }
+    const temp = `${target}.4da-${process.pid}.tmp`;
+    try {
+        writeFileSync(temp, content);
+        renameSync(temp, target);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    }
+    return backup;
+}
+/** The snippet an editor gets, as printed in a dry run and for manual setup. */
+function snippet(target) {
+    return JSON.stringify({ [target.key]: { "4da": target.entry } }, null, 2)
+        .split("\n")
+        .map((line) => `    ${line}`)
+        .join("\n");
+}
+/** Whether `~/.claude.json` already has a user-scope `4da` server. Read-only. */
+function claudeCodeHas4da(configPath) {
+    try {
+        const root = JSON.parse(readFileSync(configPath, "utf-8"));
+        return isPlainObject(root) && isPlainObject(root.mcpServers) && "4da" in root.mcpServers;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Run the setup wizard: detect editors and write MCP configurations.
  * @param dryRun If true, only report what would be written without modifying files.
  */
-export function runSetup(dryRun = false) {
-    console.log("\n  4DA MCP Server — Setup\n");
+export function runSetup(dryRun = false, ctx = currentContext(), log = console.log) {
+    log("\n  4DA MCP Server — Setup\n");
     if (dryRun)
-        console.log("  [DRY RUN] No files will be modified.\n");
-    console.log("  Detecting editors...\n");
-    let configured = 0;
-    for (const editor of editors) {
-        const configPath = editor.detect();
-        if (configPath) {
-            console.log(`  Found: ${editor.name}`);
-            if (dryRun) {
-                console.log(`  Would write: ${configPath}`);
+        log("  [DRY RUN] No files will be modified.\n");
+    log("  Detecting editors...\n");
+    let found = 0;
+    let refused = 0;
+    // Claude Code: print the command, never edit ~/.claude.json.
+    const claudeJson = claudeCodeConfigPath(ctx);
+    const claudeDir = pathFor(ctx).join(ctx.home, ".claude");
+    if (existsSync(claudeJson) || existsSync(claudeDir)) {
+        found++;
+        log("  Found: Claude Code");
+        if (claudeCodeHas4da(claudeJson)) {
+            log(`  Already configured (user scope, ${claudeJson}).`);
+        }
+        else {
+            log("  Claude Code keeps its MCP servers in ~/.claude.json, which it rewrites");
+            log("  itself; setup does not edit it. Add the server with:");
+            log(`    ${CLAUDE_CODE_COMMAND}`);
+        }
+        log("");
+    }
+    for (const target of editorTargets(ctx)) {
+        if (!existsSync(target.detectDir))
+            continue;
+        found++;
+        log(`  Found: ${target.name}`);
+        let plan;
+        try {
+            plan = planConfig(readConfig(target.configPath), target.key, target.entry);
+        }
+        catch (error) {
+            plan = { action: "refuse", reason: `it could not be read (${error instanceof Error ? error.message : String(error)})` };
+        }
+        if (plan.action === "unchanged") {
+            log(`  Already configured: ${target.configPath}`);
+        }
+        else if (plan.action === "refuse") {
+            refused++;
+            log(`  Not modified: ${target.configPath}`);
+            log(`  Setup left it untouched because ${plan.reason}. Add this by hand:`);
+            log(snippet(target));
+        }
+        else if (dryRun) {
+            log(`  Would ${plan.action === "create" ? "create" : "update"}: ${target.configPath}`);
+            log(`  Adding under "${target.key}":`);
+            log(snippet(target));
+        }
+        else {
+            try {
+                const backup = writeConfigAtomic(target.configPath, plan.content ?? "");
+                log(`  Written: ${target.configPath}`);
+                if (backup)
+                    log(`  Backup:  ${backup}`);
             }
-            else {
-                editor.write(configPath);
+            catch (error) {
+                refused++;
+                log(`  Could not write ${target.configPath}: ${error instanceof Error ? error.message : String(error)}`);
+                log("  Add this by hand:");
+                log(snippet(target));
             }
-            configured++;
-            console.log("");
         }
+        log("");
+    }
+    if (found === 0) {
+        log("  No supported editors detected.\n");
+        log("  Manual setup — add to your editor's MCP config:\n");
+        log(`  ${JSON.stringify({ mcpServers: MCP_CONFIG }, null, 2)}\n`);
+        log(`  Claude Code: ${CLAUDE_CODE_COMMAND}\n`);
     }
-    if (configured === 0) {
-        console.log("  No supported editors detected.\n");
-        console.log("  Manual setup — add to your editor's MCP config:\n");
-        console.log(`  ${JSON.stringify(MCP_CONFIG, null, 2)}\n`);
-    }
-    console.log("  Done. Restart your editor to activate 4DA.");
-    console.log("");
-    console.log("  Note: This server reads data from the 4DA desktop app.");
-    console.log("  If you haven't installed it yet:");
-    console.log("    https://github.com/4DA-Systems/4DA/releases/latest");
-    console.log("");
-    console.log("  Run: npx @4da/mcp-server --doctor  to verify everything works.\n");
+    if (refused > 0)
+        log(`  ${refused} config file${refused === 1 ? " needs" : "s need"} the entry added by hand (above).`);
+    log("  Done. Restart your editor to activate 4DA.");
+    log("");
+    log("  The server works on its own; with the 4DA desktop app installed it");
+    log("  also reads the app's scored feed:");
+    log("    https://github.com/4DA-Systems/4DA/releases/latest");
+    log("");
+    log("  Run: npx @4da/mcp-server --doctor  to verify everything works.\n");
 }
 // Run directly if invoked as a script (bin entry or pnpm run setup)
 const isDirectRun = process.argv[1]?.endsWith("setup.js") || process.argv[1]?.endsWith("setup.ts");

package/dist/tool-dispatch.d.ts

@@ -20,6 +20,8 @@ export type ToolExecutor = (db: FourDADatabase, params: any) => unknown | Promis
  * context; the host already owns the process).
  */
 export declare function dispatchTool(name: string, db: FourDADatabase, args: Record<string, unknown> | undefined): Promise<CallToolResult>;
+/** What a desktop-only tool says when no desktop app database was found. */
+export declare function desktopAppNote(name: string): string;
 /** Check if a tool exists in the dispatch map */
 export declare function hasDispatchTool(name: string): boolean;
 /** Get count of registered tool executors */

package/dist/tool-dispatch.js

@@ -8,6 +8,7 @@
 import { assertToolPermission } from "./auth-context.js";
 import { checkBuildStaleness } from "./build-staleness.js";
 import { cleanStrings } from "./tool-args.js";
+import { TOOL_REGISTRY } from "./schema-registry.js";
 import { executeGetRelevantContent, executeGetContext, executeRecordFeedback, executeGetActionableSignals, executeKnowledgeGaps, executeDecisionMemory, executeCheckDecisionAlignment, executeAgentMemory, executeDeveloperDna, executeWhatShouldIKnow, executeVulnerabilityScan, executeEcosystemPulse, executeDependencyHealth, executeUpgradePlanner, executeDependencyCheck, executeUpgradeImpact, } from "./tools/index.js";
 import { getLiveIntelligence } from "./live-singleton.js";
 /**
@@ -86,7 +87,11 @@ export async function dispatchTool(name, db, args) {
     // Feed freshness describes the desktop app's feed; a standalone install has
     // none, and telling it to "run fourda-engine" is noise.
     const withFreshness = FRESHNESS_TOOLS.has(name) && !db.isStandalone;
-    const payload = cleanStrings(withFreshness ? attachFreshness(db, result) : result);
+    // A desktop-only tool called without the desktop app's database (tools/list
+    // hides these in standalone mode, but a host can call one by name) used to
+    // answer `[]`, which reads as "nothing relevant" rather than "no app".
+    const desktopOnly = db.isStandalone && TOOL_REGISTRY[name]?.standalone === false;
+    const payload = cleanStrings(withFreshness ? attachFreshness(db, result) : desktopOnly ? attachDesktopAppNote(name, result) : result);
     // An executor that returns `{ error: "<message>" }` failed: say so in the
     // protocol, not only in the body, so the host and model treat it as an error.
     const failed = payload !== null && typeof payload === "object" && typeof payload.error === "string";
@@ -140,6 +145,21 @@ function attachFreshness(db, result) {
     }
     return { data_freshness, ...extras, result };
 }
+/** What a desktop-only tool says when no desktop app database was found. */
+export function desktopAppNote(name) {
+    return (`${name} reads the 4DA desktop app's database, and none was found (standalone mode), so this result is empty or partial. ` +
+        "Install the app (https://github.com/4DA-Systems/4DA/releases/latest) or set FOURDA_DB_PATH to its database. " +
+        "The dependency, vulnerability, upgrade and decision tools work without it.");
+}
+/** Same wrapping as attachFreshness: an array becomes { desktop_app_note, item_count, items }. */
+function attachDesktopAppNote(name, result) {
+    const desktop_app_note = desktopAppNote(name);
+    if (Array.isArray(result))
+        return { desktop_app_note, item_count: result.length, items: result };
+    if (result && typeof result === "object")
+        return { desktop_app_note, ...result };
+    return { desktop_app_note, result };
+}
 /** Check if a tool exists in the dispatch map */
 export function hasDispatchTool(name) {
     return name in DISPATCH_MAP;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4da/mcp-server",
-  "version": "6.0.1",
+  "version": "6.0.2",
   "mcpName": "io.github.4DA-Systems/4da-mcp-server",
   "description": "Upgrade intelligence for AI coding agents: what changes between your installed and target version (changelog, breaking changes, the files you import it from), a pre-install verdict on each bump, vulnerability scanning at osv-scanner parity across npm/pnpm/yarn, Cargo, Python and Go lockfiles, ranked upgrade plans, task-scoped briefings, decision memory. Local, no account; works standalone, and reads the 4DA desktop app's scored feed when it is installed.",
   "type": "module",
@@ -81,16 +81,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/node": "^2.0.0",
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.2.0",
     "better-sqlite3": "^12.9.0",
-    "hono": "^4.12.34"
+    "hono": "^4.13.12",
+    "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.6.3",
     "typescript": "^7.0.2",
     "vite": "~7.3.5",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=22.0.0"