prism-mcp-server 1.5.0

package/src/utils/braveApi.ts

@@ -0,0 +1,375 @@
+/**
+ * Brave Search API Client
+ *
+ * This module handles all communication with Brave's Search APIs.
+ * Brave offers three search endpoints used by this server:
+ *
+ *   1. Web Search API (/v1/web/search)
+ *      - Standard internet search returning titles, descriptions, URLs
+ *      - Used by: brave_web_search, brave_web_search_code_mode
+ *
+ *   2. Local/POI Search API (/v1/local/pois + /v1/local/descriptions)
+ *      - Business/place search returning addresses, ratings, hours, etc.
+ *      - Uses a 3-step pipeline:  web search (to get location IDs)
+ *                                  → POI details (address, phone, hours)
+ *                                  → descriptions (business text)
+ *      - Used by: brave_local_search, brave_local_search_code_mode
+ *
+ *   3. AI Grounding / Chat Completions API (/v1/chat/completions)
+ *      - OpenAI-compatible endpoint for AI-grounded answers
+ *      - Used by: brave_answers
+ *
+ * Each function comes in two variants:
+ *   - "Raw" version (e.g., performWebSearchRaw): Returns raw JSON string from API
+ *     Used by code-mode handlers that need to pass raw data to the QuickJS sandbox
+ *   - "Formatted" version (e.g., performWebSearch): Returns human-readable text
+ *     Used by standard search handlers
+ *
+ * Authentication: All requests use the BRAVE_API_KEY via X-Subscription-Token header.
+ * The Brave Answers endpoint uses a separate BRAVE_ANSWERS_API_KEY via Bearer token.
+ */
+
+import { BRAVE_API_KEY, BRAVE_ANSWERS_API_KEY } from "../config.js";
+
+// ─── TypeScript Interfaces for Brave API Responses ────────────
+// These types match the shape of Brave's JSON responses so we get
+// type safety when accessing fields like data.web.results[0].title
+export interface BraveWeb {
+  web?: {
+    results?: Array<{
+      title: string;
+      description: string;
+      url: string;
+      language?: string;
+      published?: string;
+      rank?: number;
+    }>;
+  };
+  locations?: {
+    results?: Array<{
+      id: string;
+      title?: string;
+    }>;
+  };
+}
+
+export interface BraveLocation {
+  id: string;
+  name?: string;
+  title?: string;
+  address: {
+    streetAddress?: string;
+    addressLocality?: string;
+    addressRegion?: string;
+    postalCode?: string;
+  };
+  coordinates?: {
+    latitude: number;
+    longitude: number;
+  };
+  phone?: string;
+  rating?: {
+    ratingValue?: number;
+    ratingCount?: number;
+  };
+  openingHours?: string[];
+  priceRange?: string;
+}
+
+export interface BravePoiResponse {
+  results: BraveLocation[];
+}
+
+export interface BraveDescription {
+  descriptions: { [id: string]: string };
+}
+
+interface BraveAnswersMessage {
+  role: "user" | "system" | "assistant";
+  content: string;
+}
+
+interface BraveAnswersResponse {
+  id?: string;
+  model?: string;
+  choices?: Array<{
+    message?: {
+      role?: string;
+      content?: string;
+    };
+  }>;
+}
+
+// Brave Answers API call (AI Grounding/OpenAI-compatible)
+export async function performBraveAnswers(
+  query: string,
+  model: string = "brave"
+) {
+  if (!BRAVE_ANSWERS_API_KEY) {
+    throw new Error("BRAVE_ANSWERS_API_KEY is not configured");
+  }
+
+  const url = new URL("https://api.search.brave.com/res/v1/chat/completions");
+  const messages: BraveAnswersMessage[] = [{ role: "user", content: query }];
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${BRAVE_ANSWERS_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model,
+      stream: false,
+      messages,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Brave Answers API error: ${response.status} ${response.statusText
+      }\n${await response.text()}`
+    );
+  }
+
+  const data = (await response.json()) as BraveAnswersResponse;
+  const content = data.choices?.[0]?.message?.content?.trim();
+
+  if (!content) {
+    throw new Error("Brave Answers API returned an empty response");
+  }
+
+  return content;
+}
+
+// Raw web search API call
+export async function performWebSearchRaw(
+  query: string,
+  count: number = 10,
+  offset: number = 0
+): Promise<string> {
+  const url = new URL("https://api.search.brave.com/res/v1/web/search");
+  url.searchParams.set("q", query);
+  url.searchParams.set("count", Math.min(count, 20).toString()); // API limit
+  url.searchParams.set("offset", offset.toString());
+
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      "Accept-Encoding": "gzip",
+      "X-Subscription-Token": BRAVE_API_KEY!,
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Brave API error: ${response.status} ${response.statusText
+      }\n${await response.text()}`
+    );
+  }
+
+  return await response.text();
+}
+
+// Web search API call
+export async function performWebSearch(
+  query: string,
+  count: number = 10,
+  offset: number = 0
+) {
+  const textData = await performWebSearchRaw(query, count, offset);
+  const data = JSON.parse(textData) as BraveWeb;
+
+  // Extract just web results
+  const results = (data.web?.results || []).map((result) => ({
+    title: result.title || "",
+    description: result.description || "",
+    url: result.url || "",
+  }));
+
+  return results
+    .map(
+      (r) => `Title: ${r.title}\nDescription: ${r.description}\nURL: ${r.url}`
+    )
+    .join("\n\n");
+}
+
+// Get POI details
+export async function getPoisData(ids: string[]): Promise<BravePoiResponse> {
+  const url = new URL("https://api.search.brave.com/res/v1/local/pois");
+  ids.filter(Boolean).forEach((id) => url.searchParams.append("ids", id));
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      "Accept-Encoding": "gzip",
+      "X-Subscription-Token": BRAVE_API_KEY!,
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Brave API error: ${response.status} ${response.statusText
+      }\n${await response.text()}`
+    );
+  }
+
+  return (await response.json()) as BravePoiResponse;
+}
+
+// Get descriptions data
+export async function getDescriptionsData(
+  ids: string[]
+): Promise<BraveDescription> {
+  const url = new URL("https://api.search.brave.com/res/v1/local/descriptions");
+  ids.filter(Boolean).forEach((id) => url.searchParams.append("ids", id));
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      "Accept-Encoding": "gzip",
+      "X-Subscription-Token": BRAVE_API_KEY!,
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Brave API error: ${response.status} ${response.statusText
+      }\n${await response.text()}`
+    );
+  }
+
+  return (await response.json()) as BraveDescription;
+}
+
+function chunkArray<T>(arr: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+}
+
+// Raw local search API call with poi/details payload
+export async function performLocalSearchRaw(
+  query: string,
+  count: number = 5
+): Promise<string> {
+  // Initial search to get location IDs
+  const webUrl = new URL("https://api.search.brave.com/res/v1/web/search");
+  webUrl.searchParams.set("q", query);
+  webUrl.searchParams.set("search_lang", "en");
+  webUrl.searchParams.set("result_filter", "locations");
+  webUrl.searchParams.set("count", Math.min(count, 20).toString());
+
+  const webResponse = await fetch(webUrl, {
+    headers: {
+      Accept: "application/json",
+      "Accept-Encoding": "gzip",
+      "X-Subscription-Token": BRAVE_API_KEY!,
+    },
+  });
+
+  if (!webResponse.ok) {
+    throw new Error(
+      `Brave API error: ${webResponse.status} ${webResponse.statusText
+      }\n${await webResponse.text()}`
+    );
+  }
+
+  const webData = (await webResponse.json()) as BraveWeb;
+  const locationIds =
+    webData.locations?.results
+      ?.filter((r): r is { id: string; title?: string } => r.id != null)
+      .map((r) => r.id) || [];
+
+  if (locationIds.length === 0) {
+    const fallback = await performWebSearch(query, count);
+    return JSON.stringify({
+      source: "web_fallback",
+      query,
+      count,
+      formattedText: fallback,
+    });
+  }
+
+  // Batch IDs to avoid Brave query.ids validation errors
+  const uniqueIds = [...new Set(locationIds)];
+  const idBatches = chunkArray(uniqueIds, 5);
+
+  const [poisBatches, descBatches] = await Promise.all([
+    Promise.all(idBatches.map((ids) => getPoisData(ids))),
+    Promise.all(idBatches.map((ids) => getDescriptionsData(ids))),
+  ]);
+
+  const poisData: BravePoiResponse = {
+    results: poisBatches.flatMap((batch) => batch.results || []),
+  };
+
+  const descriptionsData: BraveDescription = {
+    descriptions: Object.assign(
+      {},
+      ...descBatches.map((batch) => batch.descriptions || {})
+    ),
+  };
+
+  return JSON.stringify({
+    source: "local",
+    query,
+    count,
+    locationIds,
+    poisData,
+    descriptionsData,
+  });
+}
+
+// Local search API call with poi details
+export async function performLocalSearch(query: string, count: number = 5) {
+  const rawData = await performLocalSearchRaw(query, count);
+  const parsed = JSON.parse(rawData) as {
+    source: "local" | "web_fallback";
+    formattedText?: string;
+    poisData?: BravePoiResponse;
+    descriptionsData?: BraveDescription;
+  };
+
+  if (parsed.source === "web_fallback") {
+    return parsed.formattedText || "No local results found";
+  }
+
+  return formatLocalResults(
+    parsed.poisData || { results: [] },
+    parsed.descriptionsData || { descriptions: {} }
+  );
+}
+
+// Format local search results
+export function formatLocalResults(
+  poisData: BravePoiResponse,
+  descData: BraveDescription
+): string {
+  return (
+    (poisData.results || [])
+      .map((poi) => {
+        const address =
+          [
+            poi.address?.streetAddress ?? "",
+            poi.address?.addressLocality ?? "",
+            poi.address?.addressRegion ?? "",
+            poi.address?.postalCode ?? "",
+          ]
+            .filter((part) => part !== "")
+            .join(", ") || "N/A";
+
+        return `Name: ${poi.name || poi.title || "N/A"}
+Address: ${address}
+Phone: ${poi.phone || "N/A"}
+Rating: ${poi.rating?.ratingValue ?? "N/A"} (${poi.rating?.ratingCount ?? 0
+          } reviews)
+Price Range: ${poi.priceRange || "N/A"}
+Hours: ${(poi.openingHours || []).join(", ") || "N/A"}
+Description: ${descData.descriptions[poi.id] || "No description available"}
+`;
+      })
+      .join("\n---\n") || "No local results found"
+  );
+}

package/src/utils/embeddingApi.ts

@@ -0,0 +1,97 @@
+/**
+ * Embedding Generation Utility (v0.4.0 — Enhancement #4)
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * REVIEWER NOTE: This module wraps Google's text-embedding-004 model
+ * to generate 768-dimensional vector embeddings for text.
+ *
+ * USAGE — Called in two places:
+ *   1. sessionSaveLedgerHandler — embeds summary+decisions at save time
+ *      (fire-and-forget, non-blocking)
+ *   2. sessionSearchMemoryHandler — embeds the user's search query
+ *      to find semantically similar past sessions
+ *
+ * WHY GEMINI: We already have @google/generative-ai as a dependency
+ * and GOOGLE_API_KEY configured for the research paper analysis tool.
+ * Using a separate embedding service (OpenAI, Cohere) would add
+ * another API key dependency and increase configuration complexity.
+ *
+ * COST: Gemini's text-embedding-004 is free tier for <1500 req/min.
+ * At typical usage (~10-50 ledger saves/day), we'll never approach
+ * this limit.
+ *
+ * TRUNCATION GUARD: text-embedding-004 has a token limit per API call
+ * (~8192 tokens ≈ ~32K characters). If the input text exceeds this,
+ * the API returns a 400 Bad Request. We implement a hard character
+ * limit (default 8000 chars) to guarantee the API call never crashes.
+ * This is applied before sending to the API, not after.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import { GOOGLE_API_KEY } from "../config.js";
+
+// ─── Constants ────────────────────────────────────────────────
+
+// REVIEWER NOTE: Maximum characters to send to the embedding API.
+// text-embedding-004 supports ~8192 tokens. At ~4 chars per token,
+// 8000 chars is a safe ceiling. Truncation is silent and non-fatal —
+// the embedding still captures the semantic meaning of the first
+// ~2000 tokens, which is more than enough for similarity search.
+const MAX_EMBEDDING_CHARS = 8000;
+
+// ─── Embedding Client ─────────────────────────────────────────
+
+/**
+ * Generates a 768-dimensional embedding vector for the given text.
+ *
+ * @param text - The text to embed (summary + decisions, search query, etc.)
+ * @returns Array of 768 floating-point numbers representing the text's
+ *          semantic meaning in vector space.
+ * @throws Error if GOOGLE_API_KEY is not configured or API call fails.
+ *
+ * REVIEWER NOTE: The truncation happens BEFORE the API call, not after.
+ * If the text is longer than MAX_EMBEDDING_CHARS, we silently truncate
+ * and log a warning to stderr. This prevents 400 Bad Request errors
+ * from the Gemini API without blocking the caller.
+ */
+export async function generateEmbedding(text: string): Promise<number[]> {
+  if (!GOOGLE_API_KEY) {
+    throw new Error(
+      "Cannot generate embeddings: GOOGLE_API_KEY is not configured. " +
+      "Set this environment variable to enable semantic search."
+    );
+  }
+
+  // Truncation guard — prevent exceeding API token limits
+  // REVIEWER NOTE (v1.5.0 fix): JavaScript's substring() counts UTF-16
+  // code units. If the cut point lands in the middle of a surrogate pair
+  // (e.g., emoji 🚀 or complex CJK characters), the result contains an
+  // invalid trailing byte (\uFFFD) that some APIs reject with 400.
+  // Fix: truncate at the last word boundary before the limit.
+  let inputText = text;
+  if (inputText.length > MAX_EMBEDDING_CHARS) {
+    console.error(
+      `[embedding] Input text truncated from ${inputText.length} to ~${MAX_EMBEDDING_CHARS} chars (word-safe)`
+    );
+    inputText = inputText.substring(0, MAX_EMBEDDING_CHARS);
+    // Snap back to the last space to avoid splitting a word or surrogate pair
+    const lastSpace = inputText.lastIndexOf(' ');
+    if (lastSpace > 0) {
+      inputText = inputText.substring(0, lastSpace);
+    }
+  }
+
+  // Skip empty or whitespace-only text
+  if (!inputText.trim()) {
+    throw new Error("Cannot generate embedding for empty text");
+  }
+
+  const genAI = new GoogleGenerativeAI(GOOGLE_API_KEY);
+  const model = genAI.getGenerativeModel({ model: "text-embedding-004" });
+
+  console.error(`[embedding] Generating 768-dim embedding for ${inputText.length} chars`);
+
+  const result = await model.embedContent(inputText);
+  return result.embedding.values;
+}

package/src/utils/executor.ts

@@ -0,0 +1,105 @@
+/**
+ * QuickJS Sandbox Executor
+ *
+ * This module runs user-provided JavaScript code in a secure, isolated
+ * environment using QuickJS (a lightweight JavaScript engine compiled to WASM).
+ *
+ * Why a sandbox?
+ *   The "code mode" tools let the AI write JavaScript to extract specific
+ *   fields from large API responses. Running untrusted code directly in
+ *   Node.js would be a security risk. QuickJS provides:
+ *     - Memory isolation (50MB limit, separate heap)
+ *     - Execution timeout (10 seconds default)
+ *     - No access to Node.js APIs, filesystem, or network
+ *
+ * How it works:
+ *   1. The raw data (e.g., Brave Search API response) is injected as a
+ *      global variable called "DATA" (a JSON string)
+ *   2. The user's code reads DATA, parses it, extracts what it needs
+ *   3. The code calls console.log() to output the result
+ *   4. We capture the console.log output and return it
+ *
+ * Example user code:
+ *   const r = JSON.parse(DATA);
+ *   console.log(r.web.results.map(x => x.title).join('\\n'));
+ *
+ * Returns:
+ *   { stdout: "captured output", error?: "if something went wrong", executionTimeMs: 42 }
+ */
+
+import { getQuickJS } from "quickjs-emscripten";
+
+export interface SandboxResult {
+    stdout: string;
+    error?: string;
+    executionTimeMs: number;
+}
+
+/**
+ * Runs the given javascript `code` in a sandboxed QuickJS environment.
+ * Injects a global variable `DATA` which contains the stringified payload.
+ */
+export async function runInSandbox(dataStr: string, code: string, timeoutMs: number = 10000): Promise<SandboxResult> {
+    const QuickJS = await getQuickJS();
+
+    // Set memory limit to 50MB (arbitrary safe limit for extraction)
+    const vm = QuickJS.newContext();
+    vm.runtime.setMemoryLimit(50 * 1024 * 1024);
+
+    const startTime = Date.now();
+    let stdout = "";
+
+    try {
+        // Inject console.log to capture stdout
+        const logHandle = vm.newFunction("log", (...args) => {
+            const parts = args.map((arg) => vm.getString(arg));
+            stdout += parts.join(" ") + "\n";
+        });
+
+        const consoleHandle = vm.newObject();
+        vm.setProp(consoleHandle, "log", logHandle);
+        vm.setProp(vm.global, "console", consoleHandle);
+        consoleHandle.dispose();
+        logHandle.dispose();
+
+        // Inject the raw API response string as "DATA"
+        const dataHandle = vm.newString(dataStr);
+        vm.setProp(vm.global, "DATA", dataHandle);
+        dataHandle.dispose();
+
+        // Set execution timeout via interrupt handler periodically
+        vm.runtime.setInterruptHandler(() => {
+            if (Date.now() - startTime > timeoutMs) {
+                return true; // interrupt execution
+            }
+            return false;
+        });
+
+        const result = vm.evalCode(code);
+
+        if (result.error) {
+            const errorMsg = vm.dump(result.error);
+            result.error.dispose();
+            return {
+                stdout,
+                error: `Script Error: ${errorMsg}`,
+                executionTimeMs: Date.now() - startTime
+            };
+        } else {
+            result.value.dispose();
+        }
+
+        return {
+            stdout,
+            executionTimeMs: Date.now() - startTime
+        };
+    } catch (err: any) {
+        return {
+            stdout,
+            error: `Runtime Exception: ${err.message}`,
+            executionTimeMs: Date.now() - startTime
+        };
+    } finally {
+        vm.dispose();
+    }
+}

package/src/utils/googleAi.ts

@@ -0,0 +1,107 @@
+/**
+ * Google Gemini AI Client
+ *
+ * This module integrates with Google's Gemini AI models for research
+ * paper analysis. It uses the @google/generative-ai SDK (Google AI Studio).
+ *
+ * Current model: gemini-2.0-flash (fast, high-quality, good for long documents)
+ *
+ * The main function (analyzePaperWithGemini) takes a paper's full text and
+ * generates a detailed analysis based on the requested type:
+ *   - "summary"           → research question, methodology, findings, conclusions
+ *   - "critique"          → methodology assessment, validity, limitations
+ *   - "literature review" → how it fits in the broader research landscape
+ *   - "key findings"      → most significant results and implications
+ *   - "comprehensive"     → all of the above combined (default)
+ *
+ * Requires: GOOGLE_API_KEY environment variable
+ *
+ * Note: This module also exports an MCP client factory (createMcpClient)
+ * which can be used for testing or inter-server communication.
+ */
+
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import { Readable } from "stream";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+export const googleGenAi = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY!);
+
+export function bufferToStream(buffer: Buffer): Readable {
+  const stream = new Readable();
+  stream.push(buffer);
+  stream.push(null); // Signal the end of the stream
+  return stream;
+}
+
+/**
+ * Creates an MCP client connected to the Brave Search server
+ */
+export async function createMcpClient() {
+  const transport = new StdioClientTransport({
+    command: "node",
+    args: ["index.js"], // Server entry point
+  });
+
+  const client = new Client(
+    { name: "gemini-mcp-client", version: "1.0.0" },
+    { capabilities: { tools: {} } }
+  );
+
+  await client.connect(transport);
+  return { client, transport };
+}
+
+/**
+ * Analyzes research paper content using Google's Gemini-2.0-flash model
+ * @param paperContent - The text content of the research paper
+ * @param analysisType - The type of analysis to perform (summary, critique, etc.)
+ * @param additionalContext - Any additional context or specific questions
+ * @returns Detailed analysis of the research paper
+ */
+export async function analyzePaperWithGemini(
+  paperContent: string,
+  analysisType: string,
+  additionalContext?: string
+): Promise<string> {
+  try {
+    // Initialize the Gemini Pro model
+    const model = googleGenAi.getGenerativeModel({ model: "gemini-2.0-flash" });
+
+    // Create the prompt based on analysis type
+    let prompt = `I need you to perform a detailed ${analysisType} analysis of the following research paper.\n\n`;
+    
+    if (additionalContext) {
+      prompt += `Additional context: ${additionalContext}\n\n`;
+    }
+    
+    prompt += `Research paper content:\n${paperContent}\n\n`;
+    
+    switch (analysisType.toLowerCase()) {
+      case "summary":
+        prompt += "Provide a comprehensive summary including the research question, methodology, key findings, and conclusions.";
+        break;
+      case "critique":
+        prompt += "Provide a critical evaluation of the research methodology, validity of findings, limitations, and suggestions for improvement.";
+        break;
+      case "literature review":
+        prompt += "Analyze how this paper fits into the broader research landscape, identifying key related works and research gaps.";
+        break;
+      case "key findings":
+        prompt += "Extract and explain the most significant findings and their implications.";
+        break;
+      default:
+        prompt += "Perform a comprehensive analysis including summary, methodology assessment, key findings, limitations, and significance.";
+    }
+
+    // Generate content using Gemini
+    const result = await model.generateContent(prompt);
+    const response = await result.response;
+    const text = response.text();
+    
+    return text;
+  } catch (error) {
+    console.error("Error analyzing paper with Gemini:", error);
+    throw new Error(`Failed to analyze paper: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}