prism-mcp-server 6.1.8 → 6.1.9

package/README.md

@@ -77,7 +77,7 @@ Add to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`,
 | Semantic vector search | ❌ | ✅ `GOOGLE_API_KEY` |
 | Morning Briefings | ❌ | ✅ `GOOGLE_API_KEY` |
 | Auto-compaction | ❌ | ✅ `GOOGLE_API_KEY` |
-| Web Scholar research | ❌ | ✅ `BRAVE_API_KEY` + `FIRECRAWL_API_KEY` |
+| Web Scholar research | ❌ | ✅ `BRAVE_API_KEY` + `FIRECRAWL_API_KEY` (or `TAVILY_API_KEY`) |
 | VLM image captioning | ❌ | ✅ Provider key |
 
 > 🔑 The core Mind Palace works **100% offline** with zero API keys. Cloud keys unlock intelligence features. See [Environment Variables](#environment-variables).
@@ -382,7 +382,7 @@ Soft/hard delete (Art. 17), full export in JSON, Markdown, or Obsidian vault `.z
 ## 🆕 What's New
 
 ### v6.1 — Prism-Port, Cognitive Load & Semantic Search ✅
-> **Current stable release (v6.1.8).** Data sovereignty meets active memory intelligence.
+> **Current stable release (v6.1.9).** Data sovereignty meets active memory intelligence.
 
 - 📦 **Prism-Port Vault Export** — New `vault` format for `session_export_memory`. Generates a `.zip` of interlinked Markdown files with YAML frontmatter, `[[Wikilinks]]`, and auto-generated `Keywords/` backlink indices. Drop into Obsidian or Logseq for instant knowledge graph.
 - 🏛️ **Dashboard Export Vault Button** — "🏛️ Export Vault" button in the Mind Palace UI exports the full Prism-Port vault ZIP directly from the browser. Both `/api/export` and `/api/export/vault` now use the unified `buildVaultDirectory` path — same rich format as the MCP tool.
@@ -392,6 +392,11 @@ Soft/hard delete (Art. 17), full export in JSON, Markdown, or Obsidian vault `.z
 - 📊 **Deep Purge Visualization** — A zero-overhead "Memory Density" analytic providing instant signal-to-noise ratio visibility (Graduated ideas vs raw concepts).
 - 🛡️ **Context-Boosted Search** — Biases semantic queries by intelligently interleaving your current project workspace.
 
+#### v6.1.9 — Web Scholar Tavily Integration
+- 🌐 **Tavily Core** — The Web Scholar now supports `@tavily/core` as an all-in-one search and extraction alternative to Brave+Firecrawl.
+- 📦 **API Chunking Limits** — Advanced looping logic transparently works around `tavily.extract` 20-URL boundaries.
+- 🛡️ **Network Resilience** — Handled promise rejections prevent data loss out-of-bounds due to chunk extraction or upstream network timeouts.
+
 #### v6.1.8 — Type Guard Hardening (Production Safety)
 - 🛡️ **Missing Guard Added** — `isSessionCompactLedgerArgs` was absent; an LLM passing `{threshold: "many"}` would reach the handler as a string. Added full validation for all four optional fields.
 - ✅ **Array Field Validation** — `isSessionSaveLedgerArgs` now guards `todos`, `files_changed`, and `decisions` with `Array.isArray` checks — prevents a hallucinated `{todos: "string"}` from bypassing the type system.
@@ -568,7 +573,8 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `BRAVE_API_KEY` | No | Brave Search Pro API key |
-| `FIRECRAWL_API_KEY` | No | Firecrawl API key — required for Web Scholar |
+| `FIRECRAWL_API_KEY` | No | Firecrawl API key — required for Web Scholar (unless using Tavily) |
+| `TAVILY_API_KEY` | No | Tavily Search API key — alternative to Brave+Firecrawl for Web Scholar |
 | `PRISM_STORAGE` | No | `"local"` (default) or `"supabase"` — restart required |
 | `PRISM_ENABLE_HIVEMIND` | No | `"true"` to enable multi-agent tools — restart required |
 | `PRISM_INSTANCE` | No | Instance name for multi-server PID isolation |

package/dist/config.js

@@ -145,11 +145,13 @@ export const PRISM_SCHEDULER_INTERVAL_MS = parseInt(process.env.PRISM_SCHEDULER_
 );
 // ─── v5.4: Autonomous Web Scholar ─────────────────────────────
 // Background LLM research pipeline powered by Brave Search + Firecrawl.
+// Tavily can be used as an alternative when TAVILY_API_KEY is set.
 // Defaults are conservative to prevent runaway API costs.
 export const FIRECRAWL_API_KEY = process.env.FIRECRAWL_API_KEY;
+export const TAVILY_API_KEY = process.env.TAVILY_API_KEY;
 export const PRISM_SCHOLAR_ENABLED = process.env.PRISM_SCHOLAR_ENABLED === "true"; // Opt-in
-if (PRISM_SCHOLAR_ENABLED && !FIRECRAWL_API_KEY) {
-    console.error("Warning: FIRECRAWL_API_KEY environment variable is missing. Web Scholar will be unavailable.");
+if (PRISM_SCHOLAR_ENABLED && !FIRECRAWL_API_KEY && !TAVILY_API_KEY) {
+    console.error("Warning: Neither FIRECRAWL_API_KEY nor TAVILY_API_KEY is set. Web Scholar will fall back to free search.");
 }
 export const PRISM_SCHOLAR_INTERVAL_MS = parseInt(process.env.PRISM_SCHOLAR_INTERVAL_MS || "0", 10 // Default manual-only
 );

package/dist/scholar/webScholar.js

@@ -1,9 +1,10 @@
-import { BRAVE_API_KEY, FIRECRAWL_API_KEY, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN, PRISM_USER_ID, PRISM_SCHOLAR_TOPICS, PRISM_ENABLE_HIVEMIND } from "../config.js";
+import { BRAVE_API_KEY, FIRECRAWL_API_KEY, TAVILY_API_KEY, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN, PRISM_USER_ID, PRISM_SCHOLAR_TOPICS, PRISM_ENABLE_HIVEMIND } from "../config.js";
 import { getStorage } from "../storage/index.js";
 import { debugLog } from "../utils/logger.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
 import { randomUUID } from "node:crypto";
 import { performWebSearchRaw } from "../utils/braveApi.js";
+import { performTavilySearch, performTavilyExtract } from "../utils/tavilyApi.js";
 import { getTracer } from "../utils/telemetry.js";
 import { searchYahooFree, scrapeArticleLocal } from "./freeSearch.js";
 // ─── Hivemind Integration Helpers ────────────────────────────
@@ -129,7 +130,13 @@ export async function runWebScholar() {
     const tracer = getTracer();
     const span = tracer.startSpan("background.web_scholar");
     try {
-        const useFreeFallback = !BRAVE_API_KEY || !FIRECRAWL_API_KEY;
+        // Pipeline priority:
+        //   1. Brave + Firecrawl (when both keys present)
+        //   2. Tavily Search + Extract (when TAVILY_API_KEY set but Brave/Firecrawl missing)
+        //   3. Yahoo + Readability free fallback (no paid keys)
+        const useBraveFirecrawl = !!(BRAVE_API_KEY && FIRECRAWL_API_KEY);
+        const useTavily = !useBraveFirecrawl && !!TAVILY_API_KEY;
+        const useFreeFallback = !useBraveFirecrawl && !useTavily;
         if (!PRISM_SCHOLAR_TOPICS || PRISM_SCHOLAR_TOPICS.length === 0) {
             debugLog("[WebScholar] Skipped: No topics configured in PRISM_SCHOLAR_TOPICS");
             span.setAttribute("scholar.skipped_reason", "no_topics");
@@ -148,16 +155,21 @@ export async function runWebScholar() {
         // 3. Search for articles
         await hivemindHeartbeat(`Searching for: ${topic}`);
         let urls = [];
-        if (useFreeFallback) {
-            debugLog("[WebScholar] API keys missing, falling back to Local Free Search (Yahoo + Readability)");
-            const ddgResults = await searchYahooFree(topic, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN);
-            urls = ddgResults.map(r => r.url).filter(Boolean);
-        }
-        else {
+        if (useBraveFirecrawl) {
             const braveResponse = await performWebSearchRaw(topic, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN);
             const braveData = JSON.parse(braveResponse);
             urls = (braveData.web?.results || []).map((r) => r.url).filter(Boolean);
         }
+        else if (useTavily) {
+            debugLog("[WebScholar] Using Tavily Search for URL discovery");
+            const tavilyResults = await performTavilySearch(TAVILY_API_KEY, topic, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN);
+            urls = tavilyResults.map(r => r.url).filter(Boolean);
+        }
+        else {
+            debugLog("[WebScholar] API keys missing, falling back to Local Free Search (Yahoo + Readability)");
+            const ddgResults = await searchYahooFree(topic, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN);
+            urls = ddgResults.map(r => r.url).filter(Boolean);
+        }
         if (urls.length === 0) {
             debugLog(`[WebScholar] No articles found for "${topic}"`);
             span.setAttribute("scholar.skipped_reason", "no_search_results");
@@ -168,44 +180,62 @@ export async function runWebScholar() {
         // 4. Scrape each URL
         await hivemindHeartbeat(`Scraping ${urls.length} articles on: ${topic}`);
         const scrapedTexts = [];
-        for (const url of urls) {
-            if (useFreeFallback) {
-                try {
-                    debugLog(`[WebScholar] Scraping local fallback: ${url}`);
-                    const article = await scrapeArticleLocal(url);
-                    const trimmed = article.content.slice(0, 15_000);
-                    scrapedTexts.push(`Source: ${url}\nTitle: ${article.title}\n\n${trimmed}\n\n---\n`);
-                }
-                catch (err) {
-                    console.error(`[WebScholar] Failed to locally scrape ${url}:`, err);
+        if (useTavily) {
+            // Tavily Extract: batch all URLs at once (up to 20)
+            try {
+                debugLog(`[WebScholar] Extracting ${urls.length} URLs via Tavily Extract`);
+                const extracted = await performTavilyExtract(TAVILY_API_KEY, urls);
+                for (const item of extracted) {
+                    if (item.rawContent) {
+                        const trimmed = item.rawContent.slice(0, 15_000);
+                        scrapedTexts.push(`Source: ${item.url}\n\n${trimmed}\n\n---\n`);
+                    }
                 }
             }
-            else {
-                try {
-                    debugLog(`[WebScholar] Scraping Firecrawl: ${url}`);
-                    const scrapeRes = await fetch("https://api.firecrawl.dev/v1/scrape", {
-                        method: "POST",
-                        headers: {
-                            "Content-Type": "application/json",
-                            "Authorization": `Bearer ${FIRECRAWL_API_KEY}`
-                        },
-                        body: JSON.stringify({
-                            url,
-                            formats: ["markdown"],
-                        })
-                    });
-                    if (!scrapeRes.ok) {
-                        console.error(`[WebScholar] Firecrawl failed for ${url}: ${scrapeRes.status}`);
-                        continue;
+            catch (err) {
+                console.error("[WebScholar] Tavily Extract failed:", err);
+            }
+        }
+        else {
+            for (const url of urls) {
+                if (useFreeFallback) {
+                    try {
+                        debugLog(`[WebScholar] Scraping local fallback: ${url}`);
+                        const article = await scrapeArticleLocal(url);
+                        const trimmed = article.content.slice(0, 15_000);
+                        scrapedTexts.push(`Source: ${url}\nTitle: ${article.title}\n\n${trimmed}\n\n---\n`);
                     }
-                    const result = (await scrapeRes.json());
-                    if (result.success && result.data?.markdown) {
-                        const trimmed = result.data.markdown.slice(0, 15_000);
-                        scrapedTexts.push(`Source: ${url}\n\n${trimmed}\n\n---\n`);
+                    catch (err) {
+                        console.error(`[WebScholar] Failed to locally scrape ${url}:`, err);
                     }
                 }
-                catch (err) {
-                    console.error(`[WebScholar] Failed to scrape ${url}:`, err);
+                else {
+                    try {
+                        debugLog(`[WebScholar] Scraping Firecrawl: ${url}`);
+                        const scrapeRes = await fetch("https://api.firecrawl.dev/v1/scrape", {
+                            method: "POST",
+                            headers: {
+                                "Content-Type": "application/json",
+                                "Authorization": `Bearer ${FIRECRAWL_API_KEY}`
+                            },
+                            body: JSON.stringify({
+                                url,
+                                formats: ["markdown"],
+                            })
+                        });
+                        if (!scrapeRes.ok) {
+                            console.error(`[WebScholar] Firecrawl failed for ${url}: ${scrapeRes.status}`);
+                            continue;
+                        }
+                        const result = (await scrapeRes.json());
+                        if (result.success && result.data?.markdown) {
+                            const trimmed = result.data.markdown.slice(0, 15_000);
+                            scrapedTexts.push(`Source: ${url}\n\n${trimmed}\n\n---\n`);
+                        }
+                    }
+                    catch (err) {
+                        console.error(`[WebScholar] Failed to scrape ${url}:`, err);
+                    }
                 }
             }
         }

package/dist/tools/sessionMemoryDefinitions.js

@@ -133,8 +133,16 @@ export const SESSION_LOAD_CONTEXT_TOOL = {
                 type: "integer",
                 description: "Maximum token budget for context response. Uses 1 token ≈ 4 chars heuristic. When set, the response is truncated to fit within the budget. Default: unlimited.",
             },
+            toolAction: {
+                type: "string",
+                description: "Brief 2-5 word summary of what this tool is doing. Capitalize like a sentence.",
+            },
+            toolSummary: {
+                type: "string",
+                description: "Brief 2-5 word noun phrase describing what this tool call is about.",
+            },
         },
-        required: ["project"],
+        required: ["project", "toolAction", "toolSummary"],
     },
 };
 // ─── Knowledge Search ─────────────────────────────────────────
@@ -181,6 +189,7 @@ export const KNOWLEDGE_SEARCH_TOOL = {
                     "latency breakdown, and scoring metadata for explainability. Default: false.",
             },
         },
+        required: ["query"],
     },
 };
 // ─── Knowledge Forget ─────────────────────────────────────────
@@ -421,9 +430,9 @@ export function isKnowledgeSearchArgs(args) {
     if (typeof args !== "object" || args === null)
         return false;
     const a = args;
-    if (a.project !== undefined && typeof a.project !== "string")
+    if (typeof a.query !== "string")
         return false;
-    if (a.query !== undefined && typeof a.query !== "string")
+    if (a.project !== undefined && typeof a.project !== "string")
         return false;
     if (a.category !== undefined && typeof a.category !== "string")
         return false;
@@ -444,12 +453,12 @@ export function isSessionSaveLedgerArgs(args) {
         return false;
     if (typeof a.summary !== "string")
         return false;
-    // Optional array fields — guard against LLM passing a string instead of string[]
-    if (a.todos !== undefined && !Array.isArray(a.todos))
+    // Optional array fields — guard against LLM passing a string instead of string[] and check elements
+    if (a.todos !== undefined && (!Array.isArray(a.todos) || !a.todos.every(t => typeof t === "string")))
         return false;
-    if (a.files_changed !== undefined && !Array.isArray(a.files_changed))
+    if (a.files_changed !== undefined && (!Array.isArray(a.files_changed) || !a.files_changed.every(t => typeof t === "string")))
         return false;
-    if (a.decisions !== undefined && !Array.isArray(a.decisions))
+    if (a.decisions !== undefined && (!Array.isArray(a.decisions) || !a.decisions.every(t => typeof t === "string")))
         return false;
     if (a.role !== undefined && typeof a.role !== "string")
         return false;
@@ -466,7 +475,7 @@ export function isSessionSaveHandoffArgs(args) {
         return false;
     if (a.expected_version !== undefined && typeof a.expected_version !== "number")
         return false;
-    if (a.open_todos !== undefined && !Array.isArray(a.open_todos))
+    if (a.open_todos !== undefined && (!Array.isArray(a.open_todos) || !a.open_todos.every(t => typeof t === "string")))
         return false;
     if (a.active_branch !== undefined && typeof a.active_branch !== "string")
         return false;
@@ -516,10 +525,12 @@ export function isBackfillEmbeddingsArgs(args) {
     return true;
 }
 export function isBackfillLinksArgs(args) {
-    return (typeof args === "object" &&
-        args !== null &&
-        "project" in args &&
-        typeof args.project === "string");
+    if (typeof args !== "object" || args === null)
+        return false;
+    const a = args;
+    if (typeof a.project !== "string")
+        return false;
+    return true;
 }
 export function isSessionLoadContextArgs(args) {
     if (typeof args !== "object" || args === null)
@@ -533,6 +544,10 @@ export function isSessionLoadContextArgs(args) {
         return false;
     if (a.max_tokens !== undefined && typeof a.max_tokens !== "number")
         return false;
+    if (a.toolAction !== undefined && typeof a.toolAction !== "string")
+        return false;
+    if (a.toolSummary !== undefined && typeof a.toolSummary !== "string")
+        return false;
     return true;
 }
 // ─── v2.0: Time Travel Tool Definitions ──────────────────────
@@ -659,12 +674,14 @@ export function isSessionSaveImageArgs(args) {
     return true;
 }
 export function isSessionViewImageArgs(args) {
-    return (typeof args === "object" &&
-        args !== null &&
-        "project" in args &&
-        typeof args.project === "string" &&
-        "image_id" in args &&
-        typeof args.image_id === "string");
+    if (typeof args !== "object" || args === null)
+        return false;
+    const a = args;
+    if (typeof a.project !== "string")
+        return false;
+    if (typeof a.image_id !== "string")
+        return false;
+    return true;
 }
 // ─── v2.2.0: Health Check (fsck) Tool Definition ─────────────
 /**
@@ -675,12 +692,12 @@ export function isSessionViewImageArgs(args) {
 export const SESSION_HEALTH_CHECK_TOOL = {
     name: "session_health_check",
     description: "Run integrity checks on the agent's memory (like fsck for filesystems). " +
-        "Scans for missing embeddings, duplicate entries, orphaned handoffs, and stale rollups.\\n\\n" +
-        "Checks performed:\\n" +
-        "1. **Missing embeddings** — entries that can't be found via semantic search\\n" +
-        "2. **Duplicate entries** — near-identical summaries wasting context tokens\\n" +
-        "3. **Orphaned handoffs** — handoff state with no backing ledger entries\\n" +
-        "4. **Stale rollups** — compaction artifacts with no archived originals\\n\\n" +
+        "Scans for missing embeddings, duplicate entries, orphaned handoffs, and stale rollups.\n\n" +
+        "Checks performed:\n" +
+        "1. **Missing embeddings** — entries that can't be found via semantic search\n" +
+        "2. **Duplicate entries** — near-identical summaries wasting context tokens\n" +
+        "3. **Orphaned handoffs** — handoff state with no backing ledger entries\n" +
+        "4. **Stale rollups** — compaction artifacts with no archived originals\n\n" +
         "Use auto_fix=true to automatically repair missing embeddings and clean up orphans.",
     inputSchema: {
         type: "object",
@@ -864,12 +881,14 @@ export const KNOWLEDGE_SET_RETENTION_TOOL = {
     },
 };
 export function isKnowledgeSetRetentionArgs(args) {
-    return (typeof args === "object" &&
-        args !== null &&
-        "project" in args &&
-        typeof args.project === "string" &&
-        "ttl_days" in args &&
-        typeof args.ttl_days === "number");
+    if (typeof args !== "object" || args === null)
+        return false;
+    const a = args;
+    if (typeof a.project !== "string")
+        return false;
+    if (typeof a.ttl_days !== "number")
+        return false;
+    return true;
 }
 // ─── v4.0: Active Behavioral Memory Tools ────────────────────
 export const SESSION_SAVE_EXPERIENCE_TOOL = {
@@ -929,7 +948,11 @@ export function isSessionSaveExperienceArgs(args) {
     const a = args;
     if (typeof a.project !== "string")
         return false;
-    if (typeof a.event_type !== "string")
+    if (typeof a.event_type !== "string" ||
+        (a.event_type !== "correction" &&
+            a.event_type !== "success" &&
+            a.event_type !== "failure" &&
+            a.event_type !== "learning"))
         return false;
     if (typeof a.context !== "string")
         return false;
@@ -977,10 +1000,12 @@ export const KNOWLEDGE_DOWNVOTE_TOOL = {
     },
 };
 export function isKnowledgeVoteArgs(args) {
-    return (typeof args === "object" &&
-        args !== null &&
-        "id" in args &&
-        typeof args.id === "string");
+    if (typeof args !== "object" || args === null)
+        return false;
+    const a = args;
+    if (typeof a.id !== "string")
+        return false;
+    return true;
 }
 // ─── v4.2: Knowledge Sync Rules Tool ─────────────────────────
 export const KNOWLEDGE_SYNC_RULES_TOOL = {

package/dist/utils/tavilyApi.js

@@ -0,0 +1,70 @@
+/**
+ * Tavily API Client
+ *
+ * This module provides Tavily Search and Extract helpers for the Web Scholar
+ * pipeline. It serves as an additive alternative to Brave Search + Firecrawl
+ * when TAVILY_API_KEY is set.
+ *
+ *   1. performTavilySearch — Web search returning URLs (mirrors Brave web search)
+ *   2. performTavilyExtract — URL content extraction returning markdown (mirrors Firecrawl scrape)
+ */
+import { tavily } from "@tavily/core";
+function getClient(apiKey) {
+    return tavily({ apiKey });
+}
+/**
+ * Searches the web via Tavily and returns an array of result objects.
+ */
+export async function performTavilySearch(apiKey, query, maxResults = 10) {
+    try {
+        const client = getClient(apiKey);
+        const response = await client.search(query, {
+            maxResults,
+            searchDepth: "advanced",
+            topic: "general",
+        });
+        return (response.results || []).map((r) => ({
+            title: r.title || "",
+            url: r.url || "",
+            content: r.content || "",
+            score: r.score ?? 0,
+        }));
+    }
+    catch (error) {
+        console.error(`[Tavily Search] Error performing search for query "${query}":`, error);
+        return [];
+    }
+}
+/**
+ * Extracts article content from URLs via Tavily Extract.
+ * Returns markdown content for each successfully extracted URL.
+ */
+export async function performTavilyExtract(apiKey, urls) {
+    if (urls.length === 0)
+        return [];
+    const client = getClient(apiKey);
+    const allResults = [];
+    // Tavily extract accepts up to 20 URLs at once
+    for (let i = 0; i < urls.length; i += 20) {
+        const batch = urls.slice(i, i + 20);
+        try {
+            const response = await client.extract(batch, {
+                extractDepth: "basic",
+            });
+            // Optionally log failed URLs from this batch
+            if (response.failedResults && response.failedResults.length > 0) {
+                console.warn(`[Tavily Extract] Failed to extract ${response.failedResults.length} URLs in this batch.`, response.failedResults);
+            }
+            const mapped = (response.results || []).map((r) => ({
+                url: r.url || "",
+                rawContent: r.rawContent || "",
+            }));
+            allResults.push(...mapped);
+        }
+        catch (error) {
+            // Log the error but continue to the next batch to prevent total data loss
+            console.error(`[Tavily Extract] Error extracting batch ${i} to ${Math.min(i + 20, urls.length)}:`, error);
+        }
+    }
+    return allResults;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "6.1.8",
+  "version": "6.1.9",
   "mcpName": "io.github.dcostenco/prism-mcp",
   "description": "The Mind Palace for AI Agents — persistent memory (SQLite/Supabase), behavioral learning & IDE rules sync, multimodal VLM image captioning, pluggable LLM providers (OpenAI/Anthropic/Gemini/Ollama), OpenTelemetry distributed tracing, GDPR export, multi-agent Hivemind sync, time travel, visual Mind Palace dashboard. Zero-config local mode.",
   "module": "index.ts",
@@ -87,6 +87,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.80.0",
+    "@tavily/core": "^0.6.0",
     "@google-cloud/discoveryengine": "^2.5.3",
     "@google/generative-ai": "^0.24.1",
     "@libsql/client": "^0.17.2",