@4da/mcp-server 6.0.1 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,321 @@
 # Changelog
 
+## 6.1.0 — 2026-10-10
+
+Fixes from an agent eval over stdio JSON-RPC against real projects (2026-10-07)
+and an engine-generalization test on 19 public repositories against
+osv-scanner, pip-audit and a fix-path oracle (2026-10-10): precision 1.00 over
+19,115 findings and recall 19,115 of 19,116 on the lockfiles the server reads
+(was 0.74 overall, with 44 langchain lockfiles dropped silently); the median
+`vulnerability_scan` over the corpus went from 27 s to 8.6 s.
+
+### Install: runs under npm 12 with no install scripts
+
+npm 12 blocks dependency install scripts unless allowed, so a default
+`npx @4da/mcp-server` or `npm install` left better-sqlite3's native module
+unbuilt and every tool failed (6.0.x documented an `allow-scripts` workaround).
+
+- The server uses Node's built-in `node:sqlite` when the runtime has it
+  (Node 22.13.0 and later; npm 12 itself requires 22.22.2+). No install
+  script, no native download. better-sqlite3 moved to `optionalDependencies`
+  and is used only where `node:sqlite` is missing (Node 22.0-22.12), if its
+  native module opens a database.
+- One driver interface (`src/sqlite-driver.ts`) covers what the server uses;
+  node:sqlite is adapted to match better-sqlite3: plain-object rows, BLOBs as
+  Buffers, error codes (`SQLITE_BUSY`, `SQLITE_NOTADB`, ...), the 5 s busy
+  timeout, savepoint-nested transactions, `readonly` / `fileMustExist`.
+  Read-only connections also set `PRAGMA query_only`.
+- With no usable driver at all the server no longer exits at import: it
+  starts, `vulnerability_scan`, `dependency_health`, `dependency_check` and
+  `upgrade_impact` run without a database (in-memory cache), and the other
+  tools return the fix (upgrade Node, or allow better-sqlite3's build).
+- `--doctor` reports the driver in use. `FOURDA_SQLITE_DRIVER=node|better|none`
+  forces one (tests, diagnostics). node:sqlite's one-time ExperimentalWarning
+  is filtered; other warnings pass.
+- Tests: the suite passes on each driver (CI runs it on both, and on Node
+  22.12, which has no node:sqlite); driver parity tests; the built server over
+  stdio with better-sqlite3's native module missing (fails on 6.0.2: every
+  tool answered "Could not locate the bindings file").
+
+### The server never changes the desktop app's schema
+
+The server opened the 4DA app's live `4da.db` read-write, created a
+`live_cache` table in it (2,774 rows on one machine) that the app's
+migrations do not own, and added `embedding` columns to app tables when an
+embedding provider was set.
+
+- Reads go through a `{ readonly: true, fileMustExist: true }` connection.
+  Nothing is created or altered in the app's database: no tables, columns
+  or indexes.
+- The response cache moved to `cache.db` in the server's own folder
+  (`%LOCALAPPDATA%\4da-mcp`, `~/Library/Application Support/4da-mcp`,
+  `~/.local/share/4da-mcp`; `FOURDA_MCP_HOME` moves it).
+- Decisions, agent memory and feedback still go into the app's own
+  `developer_decisions`, `agent_memory`, `interactions` and `feedback`
+  tables, so the app's decision UI and calibration see them. They go through a
+  separate write connection (busy timeout 3 s, one short transaction per
+  record). If the app's table or a column a record needs is missing (schema
+  drift), the record goes to the server's `standalone.db` and the response
+  says so in `_meta`; the server never creates it.
+- Semantic-recall embeddings are cached in the app's tables only when they
+  already have `embedding` / `embedding_model` columns; otherwise they are
+  computed per call.
+- Tests: the app's `sqlite_master` is identical after every tool ran, and
+  only those four tables gain rows; caching alone leaves the file
+  byte-for-byte unchanged.
+- The `live_cache` table already inside existing app databases is left
+  alone; the app owns that file and can drop it.
+
+### `upgrade_impact`
+
+- Reads changelog headings with inline HTML before the version (stripe:
+  `## <a id="23-0-0"></a>23.0.0 - 2026-09-30`). stripe 22.3.0 -> 23.0.0 went
+  from "no changelog" to 8 releases with 11 entries flagged breaking.
+- Bullets nested under an entry are that entry's `details`, not entries of
+  their own; a breaking detail makes the entry breaking. sqlx 0.8.6 -> 0.9.0
+  went from "83 entries flagged breaking" to 24 (its Breaking section's 23
+  bullets plus the MSRV statement).
+- "`Cargo.lock` Removed from Tracking" is no longer read as a Removed
+  category.
+- The parsed-changelog cache key carries the parser version
+  (`upgrade-impact:changelog:p2:...`). Parsed changelogs are cached for 7
+  days, so before this a parser fix in a release stayed invisible for a week
+  on every machine that had already read that package.
+
+### Breaking version ranges
+
+- `dependency_health` and `upgrade_planner` label a 0.x minor bump (and a
+  0.0.x patch bump) "major", as `upgrade_impact` and `dependency_check`
+  already did: under caret rules 0.12 -> 0.13 is breaking.
+- `dependency_check` returns `review` for a breaking range (a major, a 0.x
+  minor) with "breaking version range, run upgrade_impact". It returned
+  `proceed` for vitest 3 -> 5, reqwest 0.12 -> 0.13 and stripe 22 -> 23.
+- `what_should_i_know` counts a 0.x minor bump as a major one in
+  `majors_crossed` and the delegation verdict. It compared plain major
+  numbers, so "upgrade reqwest from 0.12 to 0.13" crossed 0 majors and came
+  back `safe_to_delegate`; it is now `review_needed`. Without a stated
+  "from", the furthest installed copy sets the distance.
+
+### Project scope
+
+- `upgrade_planner` and `what_should_i_know` take `project_path`. Default:
+  the project the server was started in; `"*"` for every project. Called
+  from 4DA, the app's plan led with navcal, verax and 4da-ledger steps; it
+  is now narrowed to the project's steps, lines and sites, and says how
+  many steps only touch other projects.
+
+### `what_should_i_know`
+
+- Expands the package families a task names ("all tauri plugins", "tauri
+  and its plugins", "@tauri-apps packages", "tauri-plugin-*") to the
+  project's direct dependencies in them. It matched only `tauri`.
+- For a task asking for the latest release, each package gets `latest`
+  (newest stable, installed vs latest major line, `on_latest_major`) and the
+  summary says which are already on the latest major.
+
+### `vulnerability_scan`
+
+- One recommendation per installed version, each advisory counted once.
+  "rsa 0.9.10 — 2 known vulnerabilities" was one advisory on two versions.
+
+### `vulnerability_scan` latency
+
+A cold scan (empty cache) through the server's own modules, same machine,
+same network, two runs each (2026-10-10):
+
+| Project | Dependencies | Before | After |
+|---|---|---|---|
+| superset | 4,516 | 71 s, 143 s | 9.4 s, 9.2 s |
+| proshop-mern | 1,545 | 34 s, 34 s | 6.5 s, 6.5 s |
+| nushell | 531 | 20 s, 17 s | 4.5 s, 4.4 s |
+
+- **Cache writes in one transaction.** A scan caches one row per dependency
+  and one per advisory, and each was its own autocommit: on superset the
+  network part of a cold scan ended at 12 s and the remaining ~40 s were
+  4,516 WAL commits. They are now one transaction per batch, and the cache
+  file runs `synchronous = NORMAL` (a cache: in WAL mode a crash can lose
+  only the last writes, never corrupt the file).
+- **Advisory details in a pool of 24, not rounds of 8.** OSV has no batch
+  endpoint for advisory records; rounds of 8 each waited for their slowest
+  request. A throttled (429), failed or timed-out detail request is retried
+  once instead of leaving the advisory without severity or summary.
+- **querybatch chunks (1,000 dependencies each) are sent 4 at a time**
+  instead of one after another; every chunk must answer or the scan fails, so
+  an unanswered chunk can never read as clean.
+- **No duplicate work beside the warm-up.** The startup warm-up scan and the
+  first tool call's scan ran side by side and both fetched every advisory
+  before either could cache it. An identical scan already running is now
+  awaited (a forced refresh still runs its own), and a detail request in
+  flight is shared by every scanner in the process.
+
+### What the standalone scan reads
+
+From the same 19-repository corpus, checked against osv-scanner and
+pip-audit.
+
+- **The project-tree walk is wider, and never silent about its bounds.**
+  langchain keeps 108 lockfiles up to three levels down; the walk (depth 2,
+  64 projects) read 64 and dropped 44 (4,852 advisory findings) without a
+  word in any answer. Bounds are now 4 levels and 256 projects (langchain:
+  about 2 s for the walk and every project scan). Past a bound the walk keeps
+  counting without scanning (up to 20,000 directories), and
+  `vulnerability_scan` returns a `coverage` block (concise and detailed:
+  `complete: false`, a note, `lockfiles_not_scanned`; detailed also lists
+  each skipped lockfile and why). `dependency_health` and `upgrade_planner`
+  say "Partial scan: ..." in their summaries.
+- **Python reads every source in a directory, merged:** poetry.lock, uv.lock,
+  pdm.lock (new), Pipfile.lock and every requirements file:
+  `*requirements*.txt` (requirements-dev.txt, _test_minimum_requirements.txt)
+  and the `.txt` files of a `requirements/` folder (superset keeps its 100
+  runtime pins in requirements/base.txt, which nothing read), plus a
+  `.txt` that `-r`-includes a requirements file and pins packages itself
+  (CTFd's development.txt). It read one source per directory, so langchain's
+  libs/community poetry.lock hid the _test_minimum_requirements.txt beside
+  it. `-r` includes are followed; a `-c` constraints file only gives a
+  version to a name a requirements file lists (it installs nothing by
+  itself). Against pip-audit on the newly read files: superset 149/152 rows
+  agree (the 3 others are advisories OSV lists and pip-audit's data does not
+  yet) and 262/262 of pip-audit's advisories are found; CTFd 6/6; langchain
+  libs 38/38 rows, 64/65 advisories (the miss is a langchainjs CVE pip-audit
+  files under the Python package).
+- A `dir/*/` .gitignore rule hid the files beside the ignored
+  subdirectories: `docs/api_reference/*/` made langchain's
+  docs/api_reference/requirements.txt look ignored. A directory-only rule now
+  ignores a file only through a directory above it.
+- **Dev scope from a requirements file's name, and only from it:**
+  requirements-dev.txt, requirements/testing.txt, docs-requirements.txt and
+  the like mark their packages dev. A package any other file lists keeps an
+  unknown scope (never "dev"), so a runtime package is never graded down by
+  a dev file that includes the runtime one.
+- **No lockfile: declared ranges are labelled, never scanned as installs.**
+  A package.json or Cargo.toml with no lockfile used to have its range
+  floors scanned as installed versions (nushell samples/wasm: 2 false
+  findings). Ranged dependencies now carry `declaredRange` ("^1.2.0") in
+  `dependency_health` and `upgrade_planner` and are not sent to OSV; exact
+  pins still are. `vulnerability_scan` lists each such manifest under
+  `coverage.unresolved_manifests` with the command that writes its lockfile.
+- A Cargo.toml read without Cargo.lock took `[package]`'s own `version =
+  "0.1.0"` and `edition = "2021"` for crates named "version" and "edition";
+  only dependency tables are read now.
+
+### Fix paths (`upgrade_planner`)
+
+From a fix-path oracle on 19 public repositories (2026-10-10): each
+recommended step was applied to a copy, the lockfile re-resolved and the
+project re-scanned with osv-scanner.
+
+- **A target is checked against every advisory of the package, not only the
+  ones the installed version has.** openssl 0.10.38 was sent to 0.10.79,
+  which GHSA-phqj-4mhp-q6mq affects (0.10.50 up to 0.10.80): the upgrade
+  traded old advisories for a new one. The target is now the smallest
+  published version at or above every per-advisory fix that no advisory
+  affects (0.10.80). The package's advisories come from one OSV `/v1/query`
+  per vulnerable package; versions from its registry (npm, crates.io sparse
+  index, PyPI, Go proxy), else from the advisories' own fix events. An
+  advisory no release fixes (braces GHSA-vfj7-8cjw-p6xm, last affected
+  3.0.3, the newest release) does not disqualify a target and is named in
+  the step. OSV `last_affected` events are read as closed ranges.
+- **"Waiting on upstream" only when a parent really blocks the fix.** Every
+  transitive finding used to be `waiting_on_upstream`; for minimist 1.2.5
+  (npm), braces 3.0.2 (pnpm) and mio 0.8.0 (Cargo) that was wrong: each
+  parent's declared requirement already admitted the fix, and a lockfile
+  refresh fixed all three. The planner now reads the parents of the
+  installed copy (package-lock v1-v3, yarn v1 and berry and bun.lock record
+  the ranges; pnpm and Cargo.lock do not, so the parent's requirement comes
+  from registry.npmjs.org or the crates.io sparse index) and returns
+  `action: "lockfile_refresh"` with `refreshCommands` (`npm update
+  minimist`, `pnpm update braces`, `yarn up -R`, `cargo update -p
+  mio@0.8.0 --precise 0.8.11`) when every requirement admits a clean
+  version. A step still waiting on upstream names the requirement that
+  blocks it (`left-pad 1.0.0 requires "1.2.5"`). Summary and
+  `lockfileRefreshes` count them.
+- A Cargo refresh names the locked crates `--precise` cannot move by itself.
+  `cargo update -p openssl@0.10.38 --precise 0.10.80` fails on nushell:
+  0.10.80 pulls syn 2, which needs quote ^1.0.25, and quote 1.0.15 is held
+  by rstest. The step is now `cargo update -p bytemuck@1.8.0 -p
+  proc-macro2@1.0.36 -p quote@1.0.15 && cargo update -p openssl@0.10.38
+  --precise 0.10.80`, found by walking the target's dependency requirements
+  against the lockfile.
+- Checked by applying every `lockfile_refresh` step of four plans to a copy
+  and re-scanning with osv-scanner: 104 of 104 steps cleared their
+  advisories (proshop-mern npm 45, taxonomy pnpm 21, chatgpt-tauri pnpm and
+  Cargo 26, nushell Cargo 12).
+- **`vulnerability_scan` and `what_should_i_know` run the same check** on
+  the targets they recommend. "Upgrade openssl 0.10.38 → 0.10.79" is now
+  "→ 0.10.80 (... 0.10.79, the highest per-advisory fix, is itself affected
+  by GHSA-phqj-4mhp-q6mq)". Concise rows carry `fix_checked`; detailed
+  output adds `fix_targets` per vulnerable package version, while each
+  advisory row keeps its own `fixed_version`. The check is cached and
+  bounded (5 s per call, most severe first); what it could not reach in time
+  says `installed_advisories_only`. On nushell, cold: 33 of 39 package
+  versions checked in the first call.
+- The test suite is offline by construction: `fetch` throws unless a test
+  stubs it (`FOURDA_TEST_NETWORK=1` lifts that), so no assertion can depend
+  on live OSV or registry data.
+- Each vulnerable step says how its target was checked: `fixPathChecked`
+  is `all_advisories`, or `installed_advisories_only` when OSV or the
+  registry did not answer (offline, or past the 25 s budget), and the
+  summary counts those.
+
+### Build
+
+- pnpm settings (overrides, onlyBuiltDependencies) moved from package.json
+  to pnpm-workspace.yaml: pnpm 11 ignores package.json's `pnpm` field, so
+  the CI audit ran without the security overrides. New override
+  source-map-js >= 1.2.2 (GHSA-68fv-2mgg-jv7q, high). Fixes the nightly CI
+  (#9).
+
+## 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

@@ -27,9 +27,7 @@ One command to install. No API keys. No accounts. Your code never leaves your ma
 
 Requires Node.js 22 or later.
 
-> **npm 12+:** npm 12 blocks dependency install scripts unless you allow them, which leaves the SQLite module (`better-sqlite3`) unbuilt. Allow it once, then clear the npx cache:
-> `npm config set allow-scripts=better-sqlite3 --location=user` and `npx clear-npx-cache`.
-> `npx @4da/mcp-server --doctor` checks this by opening a database. npm 10 and 11, which every current Node release ships, are not affected.
+The server uses Node's built-in `node:sqlite` (Node 22.13 and later), so it needs no install script and works with npm 12's default of blocking them. On Node 22.0-22.12 it uses the optional `better-sqlite3`, whose native module npm 10 and 11 build on install. `npx @4da/mcp-server --doctor` shows which one is in use.
 
 ```bash
 claude mcp add 4da -- npx @4da/mcp-server
@@ -45,9 +43,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 +61,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,17 +95,20 @@ 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?"**
 
 ## How It Works
 
-The server reads every lockfile of the project it is started in, including independently-locked projects below the root (a repo with `src-tauri/Cargo.lock` beside a root `pnpm-lock.yaml` is scanned whole) and skipping what `.gitignore` excludes: `package-lock.json` / `npm-shrinkwrap.json`, `pnpm-lock.yaml` (v5–v9), `yarn.lock` (v1 and berry), `bun.lock`, `Cargo.lock` (Cargo workspaces included), `poetry.lock`, `uv.lock`, `Pipfile.lock`, `requirements.txt` pins, and `go.mod` / `go.sum` (Go's build list). Every installed copy is scanned, not one version per name, with the lockfile's own dev flags. It re-reads them whenever a lockfile changes, and for npm it also checks what `node_modules` actually holds.
+The server reads every lockfile of the project it is started in, including independently-locked projects below the root (a repo with `src-tauri/Cargo.lock` beside a root `pnpm-lock.yaml` is scanned whole) and skipping what `.gitignore` excludes: `package-lock.json` / `npm-shrinkwrap.json`, `pnpm-lock.yaml` (v5–v9), `yarn.lock` (v1 and berry), `bun.lock`, `Cargo.lock` (Cargo workspaces included), `poetry.lock`, `uv.lock`, `pdm.lock`, `Pipfile.lock`, requirements pins (`*requirements*.txt`, `requirements/*.txt`, with `-r` and `-c`), and `go.mod` / `go.sum` (Go's build list). Every Python source in a folder is read, not only the first. Every installed copy is scanned, not one version per name, with the lockfile's own dev flags. It re-reads them whenever a lockfile changes, and for npm it also checks what `node_modules` actually holds. The walk goes 4 levels down and up to 256 projects; whatever it leaves out, and every manifest with no lockfile (its declared ranges are not installs and are not scanned), is listed in the answer's `coverage` block, never dropped silently.
 
-Measured against osv-scanner on 12 projects (npm, pnpm, Cargo, Poetry, requirements.txt, Go): precision 1.00, recall 0.995; re-run before release from the installed package on those and 11 more never used to build the readers (yarn, pnpm, bun, uv, Pipfile, Go included), with every difference settled by OSV or Go's own build list.
+Measured against osv-scanner on 19 public repositories (npm, pnpm v5-v9, yarn v1 and berry, bun, Cargo, Poetry, uv, Pipfile, requirements, Go; 2026-10-10), every difference settled by OSV's own API: precision 1.00 over 19,115 findings, recall 19,115 of 19,116 on the lockfiles it reads (Maven/Gradle are not read). Newly read requirement files were also checked against pip-audit.
 
 - **OSV.dev** for known vulnerabilities, matched to exact installed versions
 - **npm registry, crates.io, PyPI, Go module proxy** for versions, deprecations and yanks
@@ -119,6 +120,10 @@ Results are cached (24h for registry data, 1h for vulnerabilities, 30min for new
 
 **What's sent over the network:** package names and versions (the same data visible in your lockfile), and, only for `ecosystem_pulse`, the names of a few of your dependencies as search terms. No source code, no file paths, no personal data. The call-site scan of `upgrade_impact` runs locally. Set `FOURDA_OFFLINE=true` to disable all network calls.
 
+**What's written to disk, and where:** only files the server owns, in its folder in your user data directory (`%LOCALAPPDATA%\4da-mcp`, `~/Library/Application Support/4da-mcp` or `~/.local/share/4da-mcp`; `FOURDA_MCP_HOME` moves it): `cache.db` (registry, OSV and changelog responses; safe to delete) and `standalone.db` (without the desktop app: your project scan and the decisions, agent memory and feedback you record). Nothing is written inside your repository.
+
+When the 4DA desktop app is installed, the server reads the app's database (`4da.db`) through a **read-only** connection and never creates or alters anything in it: no tables, no columns, no cache. The only writes are rows in the four app-owned tables the tools exist to fill, so the app sees them: decisions (`decision_memory` -> `developer_decisions`), agent memory (`agent_memory`), and feedback (`record_feedback` -> `interactions` and `feedback`, which the app's calibration reads). Those go through a separate write connection that waits briefly for the app's lock. If your app version lacks the table or a column a record needs, the record goes to `standalone.db` instead and the response says so in `_meta`. (Before 6.1 the server also created a `live_cache` table inside the app's database; it now keeps that cache in `cache.db`.)
+
 > The one exception: if you *explicitly* configure an OpenAI embedding provider (`FOURDA_EMBED_PROVIDER=openai`) for semantic recall, the decision/memory text you store is sent to OpenAI to be embedded. The default — no embedding provider, or a local Ollama one — keeps everything on your machine, and `FOURDA_OFFLINE=true` overrides it regardless.
 
 **Ecosystems supported:** npm, crates.io (Rust), PyPI (Python), Go. `upgrade_impact`: npm and crates.io.
@@ -148,22 +153,22 @@ Results are cached (24h for registry data, 1h for vulnerabilities, 30min for new
 | Tool | What it does |
 |------|-------------|
 | `upgrade_impact` | What changes between the installed and a target version of one dependency: releases in between, changelog entries classified breaking / deprecation / security, the breaking ones that touch your code (symbols you import, and route or pattern syntax in your string literals, e.g. axum 0.8's `/:id` -> `/{id}`), the files that import it, advisories fixed. |
-| `vulnerability_scan` | Every installed copy in every lockfile matched against OSV.dev. Scope-adjusted severity, the fix version on your release line, where each version is pinned. Concise by default (one row per vulnerable package version, the 40 most severe, about 4k tokens on a 290-advisory project); `package` for one dependency; `response_format: "detailed"` for every advisory. |
+| `vulnerability_scan` | Every installed copy in every lockfile matched against OSV.dev. Scope-adjusted severity, an upgrade target checked against every advisory of the package (the highest per-advisory fix can itself be affected by another), where each version is pinned, and a `coverage` block whenever the scan is partial. Concise by default (one row per vulnerable package version, the 40 most severe, about 4k tokens on a 290-advisory project); `package` for one dependency; `response_format: "detailed"` for every advisory. |
 | `dependency_health` | Version freshness, deprecation (of the version you run) and vulnerability counts per dependency. |
-| `upgrade_planner` | The smallest version that fixes each vulnerability, majors flagged, transitive fixes waiting on upstream. `package` for a one-package plan. |
-| `dependency_check` | Call before adding a dependency or applying a bump. Verdict per item (`proceed` / `wait` / `review` / `avoid` / `unknown`) with evidence: advisories on the target, release age (holds releases under 3 days unless they fix an advisory you have), publish-trust drop, new install scripts, brand-new transitive dependencies, yanked or deprecated. npm and crates.io. |
+| `upgrade_planner` | The smallest version no advisory affects for each vulnerable package, majors flagged (a 0.x minor counts as a major). Transitive fixes: `lockfile_refresh` with the exact command (`npm update`, `pnpm update`, `yarn up -R`, `cargo update -p ... --precise`) when every parent's declared requirement already admits a clean version, else `waiting_on_upstream` naming the requirement that blocks it. For one project: `project_path` (default: the project the server was started in; `"*"` for every project the desktop app tracks). `package` for a one-package plan. |
+| `dependency_check` | Call before adding a dependency or applying a bump. Verdict per item (`proceed` / `wait` / `review` / `avoid` / `unknown`) with evidence: advisories on the target, release age (holds releases under 3 days unless they fix an advisory you have), publish-trust drop, new install scripts, brand-new transitive dependencies, yanked or deprecated, and a breaking version range (a major, or a 0.x minor) is `review` with a pointer to `upgrade_impact`. npm and crates.io. |
 
 ### Intelligence
 
 | Tool | What it does |
 |------|-------------|
-| `what_should_i_know` | Pre-task briefing built from the task: the dependencies it names, their versions and confirmed vulnerabilities, majors crossed, your recorded decisions, and a delegation verdict only confirmed evidence can raise. |
+| `what_should_i_know` | Pre-task briefing built from the task: the dependencies it names (and the families it names: "all tauri plugins" adds the project's tauri-*, tauri-plugin-* and @tauri-apps/* packages; for "latest", whether each is already on the newest major), their versions and confirmed vulnerabilities, majors crossed, your recorded decisions, and a delegation verdict only confirmed evidence can raise. |
 | `ecosystem_pulse` | Hacker News headlines that name your dependencies, then your languages (labelled as such). Fetched only when called. |
 | `get_context` | Your tech stack, resolved dependency versions, interests, detected topics. |
 | `get_relevant_content`* | Scored content feed that passed the desktop app's relevance judge. |
 | `get_actionable_signals`* | Judge-accepted feed items the app classified (advisories, breaking changes), plus your live vulnerabilities. |
 | `knowledge_gaps`* | Dependencies with judge-accepted advisories or releases you have not looked at. |
-| `record_feedback`* | Save or dismiss items so 4DA can record explicit interaction history. |
+| `record_feedback`* | Save or dismiss items; recorded in the app's own feedback tables, which its calibration reads. |
 
 ### Decisions & Memory
 
@@ -250,6 +255,7 @@ npx @4da/mcp-server --version    # Print version
 |----------|-------------|---------|
 | `FOURDA_DB_PATH` | Path to 4DA's SQLite database | Auto-detected |
 | `FOURDA_OFFLINE` | Disable all network calls | `false` |
+| `FOURDA_MCP_HOME` | Folder for the files the server writes (`cache.db`, `standalone.db`) | Your user data folder + `4da-mcp` |
 | `MCP_AUTH_SECRET` | Shared secret for verifying Bearer tokens on `--http` (HMAC-SHA256). Falls back to `JWT_SECRET`. Unset means no token is accepted. | Unset |
 | `MCP_AUTH_REQUIRED` | Require auth on a **loopback** `--http` bind. Always required on a non-loopback bind. | `false` |
 | `MCP_ALLOWED_HOSTS` | Extra comma-separated hostnames accepted in `Host`/`Origin` (needed when binding to `0.0.0.0`). | localhost only |

package/dist/db.d.ts

@@ -1,11 +1,29 @@
 /**
  * Database module for 4DA MCP Server
  *
- * Read-only access to the 4DA SQLite database.
- * Only the record_feedback function performs writes.
+ * The desktop app's database (`4da.db`) is opened READ-ONLY
+ * (`{ readonly: true, fileMustExist: true }`) for everything the server reads.
+ * The app owns that file and its migrations: the server never creates or
+ * alters anything in it. It writes rows into exactly the app-owned tables its
+ * tools exist to write (APP_WRITABLE_TABLES: decisions, agent memory, feedback
+ * and interactions, which the app's calibration and decision UI read), through
+ * a separate write connection opened only for those statements (writerFor).
+ *
+ * Everything else the server writes goes to files it owns, under
+ * serverDataDir():
+ * - `cache.db`: registry, OSV and changelog responses (LiveCache).
+ * - `standalone.db`: the standalone database when no app is installed, and
+ *   the fallback for a record the app's schema cannot hold (schema drift).
+ *
+ * Until 6.0.2 the server created a `live_cache` table inside the app's
+ * database (2,774 rows on one machine, 2026-10-07) and added `embedding`
+ * columns to two app tables when an embedding provider was set.
+ */
+import { type SqliteDatabase } from "./sqlite-driver.js";
+/**
+ * Null when a SQLite driver (node:sqlite, or better-sqlite3 with a working
+ * native module) can open a database here; otherwise why not, with the fix.
  */
-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 { RelevantItem, UserContext, FeedbackAction, FeedbackResult } from "./types.js";
 import type { ProjectScanResult } from "./project-scanner.js";
@@ -30,6 +48,28 @@ 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;
+/**
+ * The directory holding every file this server writes: a per-user data
+ * directory (`%LOCALAPPDATA%\4da-mcp`, `~/Library/Application Support/4da-mcp`,
+ * `$XDG_DATA_HOME/4da-mcp`). FOURDA_MCP_HOME overrides it (tests use a temp dir).
+ */
+export declare function serverDataDir(): string;
+/** The server's response cache (registry, OSV, changelogs). Disposable: deleting it costs refetches only. */
+export declare function serverCacheDbPath(): string;
+/**
+ * Whether an error says the database file itself is unreadable: not SQLite at
+ * all, or damaged. SQLite 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;
@@ -91,6 +131,20 @@ export declare function dedupeByTitle<T extends {
  * the `is_direct` standalone-schema gap slipped through precisely because the
  * two modes were only ever tested separately.
  */
+/**
+ * The app-owned tables this server is designed to write when the desktop app
+ * is installed: decisions (decision_memory), agent memory (agent_memory) and
+ * feedback (record_feedback -> the app's calibration). Nothing else in the
+ * app's database is ever written, and nothing in it is created or altered.
+ */
+export declare const APP_WRITABLE_TABLES: readonly ["developer_decisions", "agent_memory", "interactions", "feedback"];
+export type AppWritableTable = (typeof APP_WRITABLE_TABLES)[number];
+export interface WriteTarget {
+    raw: SqliteDatabase;
+    /** database = the open (standalone) database; app = the app's table; server_store = fallback on schema drift. */
+    target: "database" | "app" | "server_store";
+    note?: string;
+}
 export declare const DEPENDENCY_GROUP_QUERY = "SELECT DISTINCT package_name, language, project_path, is_dev, is_direct FROM project_dependencies";
 /**
  * 4DA Database accessor
@@ -98,12 +152,38 @@ 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
      * (no pre-existing 4DA desktop app database found).
      */
     get isStandalone(): boolean;
+    /** True for the desktop app's database, which this connection only reads. */
+    get isReadOnly(): boolean;
+    private memoryStore;
+    private appWriter;
+    /**
+     * The connection a record into one of the app-owned tables this server is
+     * designed to write (APP_WRITABLE_TABLES) goes through, and where it lands.
+     *
+     * - Standalone database: the database itself.
+     * - The desktop app's database: a SEPARATE writable connection, opened on
+     *   first use for these statements only (the main connection stays
+     *   read-only), with a busy timeout so a write waits briefly for the app
+     *   instead of failing. Only when the app's table has every column the
+     *   statement names; nothing is ever created or altered in the app's file.
+     * - Schema drift (table or column missing in the app): the record goes to
+     *   this server's own store (standaloneDbPath()) and `note` says so.
+     */
+    writerFor(table: AppWritableTable, columns: readonly string[]): WriteTarget;
+    /**
+     * The server's own store: its standalone database (standaloneDbPath()).
+     * Used for records the app's schema cannot hold (see writerFor). A
+     * standalone database is its own store.
+     */
+    getMemoryStore(): FourDADatabase;
     /**
      * Validate that a database file exists and is a readable SQLite database.
      *
@@ -112,7 +192,7 @@ export declare class FourDADatabase {
      * By default this runs a CHEAP probe (open + list tables, ~0.1s) which surfaces
      * a missing, locked, or corrupt-header file. It deliberately does NOT run a full
      * `PRAGMA integrity_check`: that is an O(database-size) scan (~11s on a 1.7 GB DB,
-     * and growing) and, because better-sqlite3 is synchronous, it blocks the event
+     * and growing) and, because the SQLite drivers are synchronous, it blocks the event
      * loop — running it on the startup path stalls the MCP stdio handshake until it
      * finishes, so the host's connect timeout can fire and the server looks like it
      * "failed to start". Pass `{ deep: true }` for the full integrity_check on the
@@ -126,9 +206,9 @@ export declare class FourDADatabase {
         deep?: boolean;
     }): DatabaseValidationResult;
     /**
-     * Get the raw better-sqlite3 database instance for custom queries
+     * Get the raw database connection (sqlite-driver.ts) for custom queries
      */
-    getRawDb(): BetterSqlite3.Database;
+    getRawDb(): SqliteDatabase;
     /**
      * Close the database connection
      */
@@ -176,6 +256,7 @@ export declare class FourDADatabase {
     getFreshness(): DataFreshness;
     /** `MAX(sources.last_fetch)`, tolerant of a missing `sources` table (returns null). */
     private safeMaxLastFetch;
+    hasTable(table: string): boolean;
     hasColumn(table: string, column: string): boolean;
     /**
      * Idempotently add a column to a table if it does not already exist.