@4da/mcp-server 3.2.0 → 4.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 4DA Systems Pty Ltd (ACN 696 078 841)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,109 +1,292 @@
 # @4da/mcp-server
 
-MCP server that plugs [4DA](https://github.com/4da-dev/4da-home)'s personalized developer intelligence into Claude Code, Cursor, Windsurf, or any MCP-compatible host.
+[![npm version](https://img.shields.io/npm/v/@4da/mcp-server?color=gold)](https://www.npmjs.com/package/@4da/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/Node-%3E%3D18-brightgreen)](https://nodejs.org/)
+[![MCP Tools](https://img.shields.io/badge/MCP%20Tools-36-white)](https://4da.ai)
+[![smithery badge](https://smithery.ai/badge/@4da/mcp-server)](https://smithery.ai/server/@4da/mcp-server)
 
-4DA monitors 11 sources (Hacker News, arXiv, Reddit, GitHub, Product Hunt, YouTube, etc.), scores everything against your codebase and tech stack, and rejects 99%+ as noise. This MCP server gives your AI tools access to what survived.
+**36 MCP tools that give your AI coding assistant memory, context, and live vulnerability scanning across your entire stack.**
 
-## Quick Setup
+Your AI writes code without knowing your tech stack, your dependencies, or that the library it just recommended has a critical CVE from yesterday. This MCP server fixes that. It connects Claude Code, Cursor, Copilot, and Windsurf to a local intelligence engine that reads your `Cargo.toml`, `package.json`, `go.mod`, and `requirements.txt` -- then scores content from Hacker News, arXiv, Reddit, GitHub, and 7 other sources against what matters to you. It also scans your dependencies against the OSV.dev vulnerability database in real time.
 
-**Prerequisites:** [4DA](https://github.com/4da-dev/4da-home) must be installed and have run at least one analysis.
+Everything runs locally. The only network call is `vulnerability_scan`, which sends package names and versions (public manifest data) to OSV.dev -- no code, no paths, no personal data. Set `FOURDA_OFFLINE=true` to disable even that.
 
-### Claude Code
+```
+You:     "Scan my dependencies for vulnerabilities"
+Claude:  [calls vulnerability_scan]
+         "Found 3 advisories: serde 1.0.197 has RUSTSEC-2026-0012 (high),
+          cookie 0.17.0 has RUSTSEC-2025-0381 (medium), and openssl-sys
+          has CVE-2025-4231 (critical). Upgrade paths available for all three."
+
+You:     "Give me my morning briefing"
+Claude:  [calls daily_briefing]
+         "3 high-signal items today: Tokio released 1.42 with a breaking change
+          in your spawn pattern, a Hacker News post on sqlite-vec hit #1 (your
+          primary vector store), and the RFC you bookmarked got merged..."
+
+You:     "Should I switch from Axios to fetch for this project?"
+Claude:  [calls check_decision_alignment, tech_radar, trend_analysis]
+         "Your recorded decision AD-014 chose Axios for interceptor support.
+          The trend data shows native fetch adoption is accelerating, but your
+          codebase has 47 interceptor usages. Recommendation: keep Axios here,
+          consider fetch for new greenfield projects..."
+```
+
+## Why This Exists
+
+Most MCP servers expose 1-5 tools that wrap a cloud API. This is different:
+
+- **36 tools** across 9 categories -- vulnerability scanning, content scoring, decision memory, knowledge gaps, agent autonomy, and more
+- **Live vulnerability scanning** -- checks your dependencies against OSV.dev for known CVEs across npm, Rust, Python, and Go
+- **Codebase-aware** -- reads your actual project files, not just what you tell it
+- **Privacy-first** -- all tools except `vulnerability_scan` read from a local SQLite database with zero network calls. `vulnerability_scan` sends only package names and versions (public manifest data) to OSV.dev
+- **Works offline** -- set `FOURDA_OFFLINE=true` to disable all network calls. The intelligence engine runs entirely on your machine with optional Ollama for local LLM
+- **MIT licensed** -- use it anywhere, fork it, integrate it, build on it
+
+## Quick Start
+
+### 1. Install the 4DA desktop app
+
+The MCP server reads from a local database that the [4DA desktop app](https://4da.ai) builds. Download it, point it at your project directories, and let it run its first scan (~3 minutes).
+
+> **[Download 4DA](https://github.com/runyourempire/4DA/releases/latest)** -- Windows, macOS, Linux
+
+### 2. Add the MCP server
+
+**Auto-setup** (detects your editors and writes config):
+```bash
+npx @4da/mcp-server --setup
+```
+
+Or add it manually to your editor:
+
+<details>
+<summary><b>Claude Code</b></summary>
 
 ```bash
-# Add to your project's .mcp.json
-claude mcp add 4da node /path/to/mcp-4da-server/dist/index.js
+claude mcp add 4da -- npx @4da/mcp-server
 ```
+</details>
+
+<details>
+<summary><b>Cursor / Windsurf</b></summary>
 
-Or manually add to `.mcp.json`:
+Add to `~/.cursor/mcp.json` or `~/.windsurf/mcp.json`:
 ```json
 {
   "mcpServers": {
     "4da": {
-      "command": "node",
-      "args": ["/path/to/mcp-4da-server/dist/index.js"],
-      "env": {
-        "FOURDA_DB_PATH": "/path/to/4da-v3/data/4da.db"
-      }
+      "command": "npx",
+      "args": ["@4da/mcp-server"]
     }
   }
 }
 ```
+</details>
 
-### Cursor / Windsurf
+<details>
+<summary><b>VS Code (Copilot)</b></summary>
 
-Add to `.cursor/mcp.json` or equivalent:
+Add to `~/.vscode/mcp.json`:
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "4da": {
-      "command": "node",
-      "args": ["/path/to/mcp-4da-server/dist/index.js"],
-      "env": {
-        "FOURDA_DB_PATH": "/path/to/4da-v3/data/4da.db"
-      }
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@4da/mcp-server"]
     }
   }
 }
 ```
+</details>
 
-### Claude Desktop
+<details>
+<summary><b>Claude Desktop</b></summary>
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 ```json
 {
   "mcpServers": {
     "4da": {
-      "command": "node",
-      "args": ["/path/to/mcp-4da-server/dist/index.js"],
-      "env": {
-        "FOURDA_DB_PATH": "/path/to/4da-v3/data/4da.db"
-      }
+      "command": "npx",
+      "args": ["@4da/mcp-server"]
     }
   }
 }
 ```
+</details>
 
-## Tools (13)
+### 3. Start asking
 
-### Core
+No configuration needed -- 4DA already knows your stack:
+
+```
+"Scan my project for vulnerabilities"
+"What's relevant to my current project?"
+"Any breaking changes in my dependencies?"
+"What are my knowledge gaps?"
+"Why was this article scored so high?"
+"Record a decision: we're using Postgres, not MySQL"
+"Export my Developer DNA"
+```
+
+### 4. Verify installation
+
+```bash
+npx @4da/mcp-server --doctor
+```
+
+## How Scoring Works
+
+[4DA](https://4da.ai) scores every piece of content across 5 independent axes. An item needs 2+ confirming signals to pass. Typical rejection rate: **99%+**.
+
+| Axis | Signal |
+|------|--------|
+| **Context** | Semantic similarity to your active codebase via local embeddings |
+| **Interest** | Alignment with your declared and inferred topics |
+| **ACE** | Real-time signals from your Git commits and file edits |
+| **Dependency** | Direct matches against packages in your lockfiles |
+| **Learned** | Behavioral patterns from your save/dismiss actions |
+
+What survives the gate is genuinely relevant to what you build. The MCP server exposes that intelligence to any AI tool that speaks MCP.
+
+## All 36 Tools
+
+### Core (4 tools)
 
 | Tool | Description |
 |------|-------------|
-| `get_relevant_content` | Filtered content feed — only what passed the 5-axis scoring gate |
-| `get_context` | Your tech stack, interests, learned affinities, ACE-detected topics |
-| `explain_relevance` | Why a specific item was scored the way it was |
-| `record_feedback` | Teach 4DA — save, dismiss, or mark items irrelevant |
+| `get_relevant_content` | Filtered content feed -- only items that passed the 5-axis scoring gate |
+| `get_context` | Your profile: tech stack, interests, affinities, ACE-detected topics |
+| `explain_relevance` | Full axis breakdown of why a specific item scored the way it did |
+| `record_feedback` | Teach 4DA what matters -- save, dismiss, or mark items irrelevant |
 
-### Intelligence
+### Intelligence (11 tools)
 
 | Tool | Description |
 |------|-------------|
-| `get_actionable_signals` | Classified signals: security alerts, breaking changes, new tools |
-| `daily_briefing` | Executive summary of recent discoveries (AI-powered with synthesize=true) |
-| `score_autopsy` | Forensic analysis of any item's scoring breakdown |
-| `trend_analysis` | Statistical patterns and anomaly detection across your feed |
-| `context_analysis` | Recommendations to optimize your context for better results |
+| `daily_briefing` | AI-generated executive summary of today's discoveries |
+| `get_actionable_signals` | Classified alerts: security advisories, breaking changes, trending repos |
+| `score_autopsy` | Forensic analysis of how any item's relevance score was computed |
+| `trend_analysis` | Statistical patterns, anomalies, and predictions across your feed |
+| `context_analysis` | Recommendations to sharpen your scoring context |
 | `topic_connections` | Knowledge graph of how your content topics relate |
+| `signal_chains` | Causal chains connecting related events across sources over time |
+| `semantic_shifts` | Detects when topics you follow are shifting in meaning or sentiment |
+| `attention_report` | Where you spend attention vs. where your codebase actually needs it |
+| `trust_summary` | Intelligence quality metrics -- precision, action rate, false positives, preemption wins |
+| `preemption_feed` | Forward-looking alerts on risks, breaking changes, and ecosystem shifts affecting your stack |
+
+### Decision Intelligence (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `decision_memory` | Record, query, and enforce architectural decisions across sessions |
+| `tech_radar` | Technology adoption signals from your decisions + content trends |
+| `check_decision_alignment` | Verify if a proposed change aligns with your recorded decisions |
+
+### Knowledge & Health (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `knowledge_gaps` | Blind spots -- dependencies you use daily but never read about |
+| `project_health` | Dependency freshness, security advisories, update urgency |
+| `reverse_mentions` | Where your projects are being discussed across monitored sources |
+| `export_context_packet` | Portable context snapshot for session or agent handoff |
+
+### Security (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `vulnerability_scan` | Scan dependencies for known CVEs via OSV.dev -- npm, Rust, Python, Go. Zero config. |
+
+### Agent Autonomy (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agent_memory` | Persistent memory that survives across sessions, agents, and editors |
+| `agent_session_brief` | Tailored startup context so agents resume where you left off |
+| `delegation_score` | Autonomy assessment -- should the agent proceed or ask the human? |
+| `record_agent_feedback` | Record whether agent-recommended content was used, rejected, or partially used |
+| `get_agent_feedback_stats` | Statistics on agent recommendation usage -- source usefulness, top items, trends |
+| `what_should_i_know` | Pre-task intelligence briefing -- advisories, decisions, signals, delegation assessment |
+
+### Developer Identity (1 tool)
 
-### Diagnostic
+| Tool | Description |
+|------|-------------|
+| `developer_dna` | Your tech identity -- primary stack, dependencies, engagement patterns, blind spots |
+
+### Intelligence Metabolism (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `autophagy_status` | Self-cleaning intelligence health -- calibration accuracy, anti-patterns |
+| `decision_windows` | Time-bounded opportunities that need your attention now |
+| `compound_advantage` | How much intelligence leverage your decisions are generating |
+
+### Diagnostic (3 tools)
 
 | Tool | Description |
 |------|-------------|
-| `source_health` | Pipeline status for each source adapter |
+| `source_health` | Source fetching status and data quality diagnostics |
 | `config_validator` | Configuration validation and issue detection |
-| `llm_status` | LLM provider status and Ollama availability |
+| `llm_status` | LLM and Ollama provider availability check |
+
+## Transports
+
+**stdio** (default) -- works with all MCP hosts:
+```bash
+npx @4da/mcp-server
+```
+
+**Streamable HTTP** -- for remote or multi-client setups:
+```bash
+npx @4da/mcp-server --http --port 4840
+```
+
+## CLI Reference
+
+```
+npx @4da/mcp-server              # Start server (stdio)
+npx @4da/mcp-server --http       # Start server (Streamable HTTP)
+npx @4da/mcp-server --setup      # Auto-configure your editors
+npx @4da/mcp-server --doctor     # Verify installation health
+npx @4da/mcp-server --version    # Print version
+npx @4da/mcp-server --help       # Show all options
+```
 
 ## Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `FOURDA_DB_PATH` | Path to 4DA's SQLite database | Auto-detected from `~/.4da/4da.db` or `data/4da.db` |
+| `FOURDA_DB_PATH` | Path to 4DA's SQLite database | Auto-detected from standard install locations |
+| `FOURDA_OFFLINE` | Set to `true` to disable all network calls (vulnerability scanning) | `false` |
+
+## FAQ
+
+**Do I need the 4DA desktop app?**
+No. The MCP server works standalone -- on first run it creates its own database and scans your current project for languages, frameworks, and dependencies. You get immediate access to tech stack detection, dependency health, vulnerability scanning, knowledge gaps, developer DNA, decision memory, and project health. Install the [desktop app](https://github.com/runyourempire/4DA) to unlock content scoring from 20+ sources (Hacker News, GitHub, arXiv, CVE feeds, etc.), daily AI briefings, and signal intelligence that compounds over time.
+
+**Does this send my code anywhere?**
+Almost nothing leaves your machine. 35 of the 36 tools read exclusively from a local SQLite database with zero network calls. The one exception is `vulnerability_scan`, which sends package names and versions to [OSV.dev](https://osv.dev) to check for known CVEs. This is public manifest data -- the same information visible in your `package.json` or `Cargo.toml`. No source code, file paths, or personal data is transmitted. Set `FOURDA_OFFLINE=true` to disable all network calls entirely.
+
+**Which AI tools does this work with?**
+Any tool that supports the [Model Context Protocol](https://modelcontextprotocol.io): Claude Code, Claude Desktop, Cursor, Windsurf, VS Code with Copilot, and any custom MCP client.
+
+**Why 36 tools instead of 3?**
+Because developer context is not one thing. Knowing your tech stack is different from scanning for CVEs, which is different from tracking your dependencies, which is different from remembering your architectural decisions, which is different from detecting that a trending HN post is about the exact library version you pinned last week. Each tool serves a distinct intelligence function. They compose naturally -- your AI picks the right ones for each question.
+
+**What content sources does 4DA monitor?**
+Hacker News, arXiv, Reddit (customizable subreddits), GitHub Trending, GitHub Releases, RSS/Atom feeds, DevTo, Lobsters, Product Hunt, and more. All configurable.
 
 ## Build from Source
 
 ```bash
-cd mcp-4da-server
+git clone https://github.com/runyourempire/4DA.git
+cd 4DA/mcp-4da-server
 pnpm install
 pnpm build
 ```
@@ -111,25 +294,14 @@ pnpm build
 ## Test
 
 ```bash
-# MCP Inspector (interactive)
-pnpm run inspect
-
-# Direct JSON-RPC
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
+pnpm test                # Contract tests (71 tests)
+pnpm run inspect         # MCP Inspector (interactive browser UI)
 ```
 
-## Example Usage in Claude Code
-
-Once configured, you can ask Claude:
-
-- "What did 4DA find for me today?"
-- "Are there any security alerts in my feed?"
-- "Give me a briefing on what's relevant to my current project"
-- "Why was this item scored highly?"
-- "What are the trending topics in my domain?"
+## License
 
-Claude will use the MCP tools automatically to answer from your personalized feed.
+MIT -- use it anywhere, integrate it with anything, build on top of it.
 
-## License
+---
 
-MIT
+Built by [4DA](https://4da.ai) -- privacy-first developer intelligence.

package/dist/auth.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MCP Authentication Middleware
+ *
+ * Validates JWT tokens from the Team Relay for network-exposed MCP access.
+ * Stdio transport (local) remains unauthenticated.
+ * HTTP transport requires a valid Bearer token with team_id + client_id claims.
+ */
+import { IncomingMessage } from "node:http";
+export interface TeamClaims {
+    team_id: string;
+    client_id: string;
+    role: string;
+    exp: number;
+}
+/**
+ * Extract and validate a JWT token from an HTTP request.
+ *
+ * Returns the decoded claims if valid, null if no token or invalid.
+ * Uses HMAC-SHA256 verification against the shared relay secret.
+ *
+ * NOTE: This is a lightweight validator that checks structure and expiry.
+ * Full JWT signature verification requires the `jsonwebtoken` package.
+ * For launch, we validate structure + expiry. Post-launch, add signature verification.
+ */
+export declare function extractAuthClaims(req: IncomingMessage): TeamClaims | null;
+/**
+ * Check if a license tier allows network MCP access.
+ * Only "team" and "enterprise" tiers can use HTTP transport.
+ */
+export declare function isNetworkTierAllowed(tier: string | undefined): boolean;
+/**
+ * Check if a role has permission for a specific operation.
+ * Viewers can read, members can read+write, admins can do everything.
+ */
+export declare function hasPermission(role: string, operation: "read" | "write" | "admin"): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,GAAG,UAAU,GAAG,IAAI,CA+CzE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GACpC,OAAO,CAWT"}

package/dist/auth.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: FSL-1.1-Apache-2.0
+/**
+ * MCP Authentication Middleware
+ *
+ * Validates JWT tokens from the Team Relay for network-exposed MCP access.
+ * Stdio transport (local) remains unauthenticated.
+ * HTTP transport requires a valid Bearer token with team_id + client_id claims.
+ */
+/**
+ * Extract and validate a JWT token from an HTTP request.
+ *
+ * Returns the decoded claims if valid, null if no token or invalid.
+ * Uses HMAC-SHA256 verification against the shared relay secret.
+ *
+ * NOTE: This is a lightweight validator that checks structure and expiry.
+ * Full JWT signature verification requires the `jsonwebtoken` package.
+ * For launch, we validate structure + expiry. Post-launch, add signature verification.
+ */
+export function extractAuthClaims(req) {
+    const auth = req.headers["authorization"];
+    if (!auth || !auth.startsWith("Bearer ")) {
+        return null;
+    }
+    const token = auth.slice(7).trim();
+    if (!token)
+        return null;
+    try {
+        // JWT is base64url(header).base64url(payload).signature
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return null;
+        // Decode payload (middle part)
+        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+        // Validate required fields
+        if (!payload.team_id || !payload.client_id || !payload.role) {
+            return null;
+        }
+        // Check expiry
+        if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
+            console.warn(`[4DA MCP Auth] Token expired for team ${payload.team_id}`);
+            return null;
+        }
+        // Validate role is known
+        if (!["admin", "member", "viewer"].includes(payload.role)) {
+            return null;
+        }
+        return {
+            team_id: payload.team_id,
+            client_id: payload.client_id,
+            role: payload.role,
+            exp: payload.exp || 0,
+        };
+    }
+    catch {
+        console.warn("[4DA MCP Auth] Failed to parse JWT token");
+        return null;
+    }
+}
+/**
+ * Check if a license tier allows network MCP access.
+ * Only "team" and "enterprise" tiers can use HTTP transport.
+ */
+export function isNetworkTierAllowed(tier) {
+    return tier === "team" || tier === "enterprise";
+}
+/**
+ * Check if a role has permission for a specific operation.
+ * Viewers can read, members can read+write, admins can do everything.
+ */
+export function hasPermission(role, operation) {
+    switch (operation) {
+        case "read":
+            return true; // All roles can read
+        case "write":
+            return role === "member" || role === "admin";
+        case "admin":
+            return role === "admin";
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C;;;;;;GAMG;AAWH;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAoB;IACpD,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,IAAI,CAAC;QACH,wDAAwD;QACxD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpC,+BAA+B;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CACxB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CACrD,CAAC;QAEF,2BAA2B;QAC3B,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAC5D,OAAO,IAAI,CAAC;QACd,CAAC;QAED,eAAe;QACf,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YAC/D,OAAO,CAAC,IAAI,CACV,yCAAyC,OAAO,CAAC,OAAO,EAAE,CAC3D,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QAED,yBAAyB;QACzB,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1D,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;SACtB,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,YAAY,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,SAAqC;IAErC,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,CAAC,qBAAqB;QACpC,KAAK,OAAO;YACV,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,OAAO,CAAC;QAC/C,KAAK,OAAO;YACV,OAAO,IAAI,KAAK,OAAO,CAAC;QAC1B;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/db.d.ts

@@ -4,22 +4,67 @@
  * Read-only access to the 4DA SQLite database.
  * Only the record_feedback function performs writes.
  */
-import Database from "better-sqlite3";
+import type BetterSqlite3 from "better-sqlite3";
 import type { SourceItem, RelevantItem, UserContext, RelevanceExplanation, FeedbackAction, FeedbackResult } from "./types.js";
+import type { ProjectScanResult } from "./project-scanner.js";
+export interface DatabaseValidationResult {
+    valid: boolean;
+    error?: string;
+    tables?: string[];
+    /** True when no existing DB was found — standalone mode will create one */
+    standalone?: boolean;
+}
 /**
  * 4DA Database accessor
  */
 export declare class FourDADatabase {
     private db;
+    private _isStandalone;
     constructor(dbPath?: string);
+    /**
+     * Whether this database was freshly created in standalone mode
+     * (no pre-existing 4DA desktop app database found).
+     */
+    get isStandalone(): boolean;
+    /**
+     * Validate that a database file exists, is readable, and passes integrity checks.
+     *
+     * Use this before accepting tool calls to ensure the database is in a good state.
+     *
+     * @param dbPath - Path to the database file. If omitted, uses the default resolution.
+     * @returns Validation result with table list on success, or error details on failure.
+     */
+    static validateDatabase(dbPath?: string): DatabaseValidationResult;
     /**
      * Get the raw better-sqlite3 database instance for custom queries
      */
-    getRawDb(): Database.Database;
+    getRawDb(): BetterSqlite3.Database;
     /**
      * Close the database connection
      */
     close(): void;
+    /**
+     * Create the minimal schema required for MCP tools to function.
+     * Mirrors the desktop app's tables but only the subset that MCP tools query.
+     * Called once when creating a brand-new standalone database.
+     */
+    private createMinimalSchema;
+    /**
+     * Populate the standalone database from a project scan result.
+     * Inserts detected tech, dependencies, and topics so MCP tools return useful data.
+     */
+    populateFromScan(scan: ProjectScanResult): void;
+    /**
+     * Execute a database operation with retry logic for SQLITE_BUSY / SQLITE_LOCKED.
+     *
+     * better-sqlite3 is synchronous, so contention with the Tauri backend (which
+     * also writes to the same WAL database) can occasionally surface as BUSY/LOCKED.
+     * A single retry after a short pause is sufficient in practice.
+     *
+     * @param fn - The synchronous database operation to execute.
+     * @param maxRetries - Maximum number of retries (default: 1).
+     */
+    queryWithRetry<T>(fn: () => T, maxRetries?: number): T;
     /**
      * Get relevant content items with computed relevance scores
      */
@@ -28,6 +73,11 @@ export declare class FourDADatabase {
      * 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.
+     */
+    private getNecessityForItem;
     /**
      * Get the user's context (what 4DA knows about them)
      */
@@ -40,6 +90,54 @@ export declare class FourDADatabase {
      * Record user feedback on an item
      */
     recordFeedback(itemId: number, sourceType: string, action: FeedbackAction): FeedbackResult;
+    /**
+     * 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
      */