@4da/mcp-server 6.0.0 → 6.0.2

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # 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
+
+`@4da/mcp-server` now lives at
+[github.com/4DA-Systems/4da-mcp-server](https://github.com/4DA-Systems/4da-mcp-server),
+with its full history, instead of a folder of the 4DA desktop app's monorepo.
+Issues, releases and the Claude Code plugin marketplace move with it:
+
+```bash
+claude plugin marketplace add 4DA-Systems/4da-mcp-server
+claude plugin install 4da@4da
+```
+
+The package, its name in the MCP Registry (`io.github.4DA-Systems/4da-mcp-server`)
+and every tool are unchanged.
+
+- **Published with provenance.** Releases are built and published from this
+  repository's `release.yml` through npm trusted publishing, so each version
+  carries a SLSA provenance attestation tying it to the commit it was built from.
+- **App-schema contract.** The server reads the desktop app's database, which
+  is now maintained in a different repository. `pnpm run contract` checks every
+  statement the server issues, and every column it probes for, against the
+  schema the app's migrations produce (`contract/app-schema.sql`, generated in
+  the app's CI). The app's CI runs the same check before a migration merges.
+- **Removed dead code.** `explainRelevance`, `getSourceItem`,
+  `recordAgentFeedback` and `getAgentFeedbackStats` had no callers since their
+  tools were removed; the standalone schema no longer creates the unused
+  `agent_feedback` table.
+- The Claude Code plugin pins the exact server version it was released with.
+
 ## 6.0.0 — 2026-10-02
 
 ### New: `upgrade_impact`

package/README.md

@@ -2,8 +2,8 @@
 
 [![npm version](https://img.shields.io/npm/v/@4da/mcp-server?color=gold)](https://www.npmjs.com/package/@4da/mcp-server)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
-[![Node](https://img.shields.io/badge/Node-%3E%3D20-brightgreen)](https://nodejs.org/)
-[![smithery badge](https://smithery.ai/badge/@4da/mcp-server)](https://smithery.ai/server/@4da/mcp-server)
+[![Node](https://img.shields.io/badge/Node-%3E%3D22-brightgreen)](https://nodejs.org/)
+[![CI](https://github.com/4DA-Systems/4da-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/4DA-Systems/4da-mcp-server/actions/workflows/ci.yml)
 
 **Upgrade intelligence for AI coding agents.** Before your agent bumps a dependency it learns what changes between the version you run and the one you want, which of your files that touches, and which vulnerabilities the move fixes, from your own lockfiles, on your machine. Plus vulnerability scanning at osv-scanner parity, ranked upgrade plans and decision memory. Zero config, no account.
 
@@ -38,16 +38,16 @@ claude mcp add 4da -- npx @4da/mcp-server
 **As a Claude Code plugin** (the MCP server plus a hook):
 
 ```bash
-claude plugin marketplace add 4DA-Systems/4DA --sparse .claude-plugin mcp-4da-server
+claude plugin marketplace add 4DA-Systems/4da-mcp-server
 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?"**
@@ -268,11 +271,11 @@ Any tool that supports [MCP](https://modelcontextprotocol.io): Claude Code, Clau
 ## Build from Source
 
 ```bash
-git clone https://github.com/4DA-Systems/4DA.git
-cd 4DA/mcp-4da-server
+git clone https://github.com/4DA-Systems/4da-mcp-server.git
+cd 4da-mcp-server
 pnpm install
 pnpm build
-pnpm test    # 662 tests, offline
+pnpm test    # offline
 ```
 
 ## License

package/dist/db.d.ts

@@ -7,7 +7,7 @@
 import type BetterSqlite3 from "better-sqlite3";
 /** Null when better-sqlite3 can open a database here; otherwise why not, with the fix. */
 export declare function nativeBindingProblem(): string | null;
-import type { SourceItem, RelevantItem, UserContext, RelevanceExplanation, FeedbackAction, FeedbackResult } from "./types.js";
+import type { RelevantItem, UserContext, FeedbackAction, FeedbackResult } from "./types.js";
 import type { ProjectScanResult } from "./project-scanner.js";
 /**
  * Where the deployed desktop app keeps its database, mirroring
@@ -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
@@ -193,10 +209,6 @@ export declare class FourDADatabase {
      * Fallback: TypeScript keyword scoring for standalone mode (no Rust pipeline).
      */
     private getRelevantContentFallback;
-    /**
-     * Get a single source item by ID and type
-     */
-    getSourceItem(itemId: number, sourceType: string): SourceItem | null;
     /**
      * Look up persisted necessity scores for an item (written by Rust analysis pipeline).
      * Returns defaults (0.0/null) if no necessity data exists yet.
@@ -206,10 +218,6 @@ export declare class FourDADatabase {
      * Get the user's context (what 4DA knows about them)
      */
     getUserContext(includeAce?: boolean, includeLearned?: boolean): UserContext;
-    /**
-     * Explain why an item was considered relevant
-     */
-    explainRelevance(itemId: number, sourceType: string): RelevanceExplanation | null;
     /**
      * Record user feedback on an item
      */
@@ -221,54 +229,6 @@ export declare class FourDADatabase {
      * so against the desktop database this is a no-op.
      */
     private ensureFeedbackTable;
-    /**
-     * Ensure the agent_feedback table exists.
-     * Called on first use so existing databases (created before this feature)
-     * get the table added without requiring a migration.
-     */
-    private ensureAgentFeedbackTable;
-    /**
-     * Record agent feedback on recommended content items
-     */
-    recordAgentFeedback(itemIds: string[], outcome: string, context?: string, sessionTask?: string): {
-        success: boolean;
-        message: string;
-        recorded_count: number;
-    };
-    /**
-     * Get agent feedback statistics for the given period
-     */
-    getAgentFeedbackStats(days?: number): {
-        period_days: number;
-        outcomes: {
-            used: number;
-            rejected: number;
-            partially_used: number;
-            total: number;
-        };
-        by_source: Array<{
-            source_type: string;
-            used: number;
-            rejected: number;
-            partially_used: number;
-            total: number;
-            usefulness_rate: number;
-        }>;
-        top_used_items: Array<{
-            item_id: string;
-            title: string | null;
-            source_type: string | null;
-            used_count: number;
-            rejected_count: number;
-        }>;
-        recent_feedback: Array<{
-            item_id: string;
-            outcome: string;
-            context: string | null;
-            session_task: string | null;
-            recorded_at: string;
-        }>;
-    };
     /**
      * Compute relevance score for an item based on user context
      */