@syndash/research-vault-mcp 1.1.0

package/README.md

@@ -0,0 +1,75 @@
+# @syndash/research-vault-mcp
+
+MCP (Model Context Protocol) server for [Nolan's research vault](https://github.com/Fearvox/dash-research-vault) — semantic search + memory persistence over 200+ markdown documents via local Gemma (Atomic Chat) or cloud LLM fallback.
+
+**Part of**: DASH SHATTER / SynDASH ecosystem.
+**Home**: [github.com/Fearvox/Evensong](https://github.com/Fearvox/Evensong) — `packages/research-vault-mcp/`
+**Status**: Wave 3+ — not yet published to npm. Plan: `docs/superpowers/plans/2026-04-19-wave2d-submodule-mcp-package-prep.md`.
+
+## Install & Run (future, post-publish)
+
+```bash
+# Via bun (recommended — native TS execution)
+bunx @syndash/research-vault-mcp
+
+# Via Node
+npx @syndash/research-vault-mcp
+```
+
+## Configure Claude Code / Claude Desktop
+
+Add to `~/.claude/settings.json` or Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "research-vault": {
+      "command": "bunx",
+      "args": ["@syndash/research-vault-mcp"]
+    }
+  }
+}
+```
+
+For direct local dev from this monorepo:
+
+```json
+{
+  "mcpServers": {
+    "research-vault-dev": {
+      "command": "bun",
+      "args": ["run", "packages/research-vault-mcp/src/server.ts"]
+    }
+  }
+}
+```
+
+## Tools Exposed (MCP contract)
+
+See `src/vault.ts` and `src/amplify.ts` for current tool definitions:
+
+- `vault_search` — hybrid search over analyzed knowledge base
+- `vault_status` — decay scores + retention health
+- `vault_taxonomy` — category tree + item counts
+- `vault_batch_analyze` — raw queue status + preview
+- `amplify_*` — remote RAG query layer (currently requires Amplify API key — see `docs.evermind.ai`; Wave 3+ will add local Gemma fallback path via `@syndash/research-vault-mcp`'s built-in retrieval chain)
+
+## Architecture
+
+Per parent spec [2026-04-19 vault foundation & preamble design](https://github.com/Fearvox/Evensong/blob/main/docs/superpowers/specs/2026-04-19-vault-foundation-and-preamble-design.md) §3.4, retrieval uses a **unified multi-signal ranker** (not 3 separate subsystems):
+
+```
+score(d, q, t) = 0.35·BM25(q,d) + 0.35·cosine(embed(q), embed(d))
+               + 0.15·exp(-(t - lastAccess)/stability)
+               + 0.10·log1p(accessCount)/log1p(MAX_ACCESS)
+               + 0.05·summary_level_weight(d)
+```
+
+**Primary LLM**: Atomic Chat local Gemma-4-E4B-Uncensored-Q4_K_M (`http://127.0.0.1:1337/v1`).
+**Fallback chain**: xai-fast → minimax-m27 → openrouter/qwen3.6-plus → openrouter/llama-3.1-8b-free.
+
+**Prior art**: EverMemOS (arxiv 2601.02163, EverMind/Shanda, 2026-01) — LLM-orchestrated hybrid retrieval. This package adopts their Stage-1 hybrid candidate generation but replaces Stage-2 verifier-loop with direct listwise LLM judge (simpler + more deterministic).
+
+## License
+
+`UNLICENSED` for now (pending org-level license decision). See parent repo LICENSE.

package/bin/research-vault-mcp.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for @syndash/research-vault-mcp.
+ * Invoked via `npx @syndash/research-vault-mcp` or `bunx @syndash/research-vault-mcp`.
+ * Delegates to src/server.ts (compiled or via bun direct).
+ *
+ * Part of DASH SHATTER (Fearvox/Evensong repo, SynDASH org).
+ * See packages/research-vault-mcp/README.md for MCP client config.
+ */
+
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { existsSync } from 'fs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const pkgRoot = join(__dirname, '..')
+
+// Prefer compiled JS if available (post-build); fall back to bun direct execution of TS source.
+const compiledServer = join(pkgRoot, 'dist', 'server.js')
+const sourceServer = join(pkgRoot, 'src', 'server.ts')
+
+async function main() {
+  const args = process.argv.slice(2)
+  let transport = 'sse'
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--transport' && args[i + 1]) {
+      transport = args[i + 1]
+    } else if (args[i].startsWith('--transport=')) {
+      transport = args[i].split('=')[1]
+    }
+  }
+  process.env.MCP_TRANSPORT = transport
+
+  if (existsSync(compiledServer)) {
+    await import(compiledServer)
+  } else if (existsSync(sourceServer)) {
+    await import(sourceServer)
+  } else {
+    console.error('research-vault-mcp: neither dist/server.js nor src/server.ts found')
+    process.exit(1)
+  }
+}
+
+main().catch(err => {
+  console.error('research-vault-mcp fatal:', err)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@syndash/research-vault-mcp",
+  "version": "1.1.0",
+  "description": "MCP server for Nolan's research vault — semantic search + memory persistence over 200+ markdown docs via local Gemma (Atomic Chat) or cloud LLM fallback. Part of DASH SHATTER / SynDASH.",
+  "type": "module",
+  "bin": {
+    "research-vault-mcp": "./bin/research-vault-mcp.mjs"
+  },
+  "scripts": {
+    "dev": "bun run src/server.ts",
+    "build": "bun build src/server.ts --outdir=dist --target=bun",
+    "test": "bun test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Fearvox/Evensong.git",
+    "directory": "packages/research-vault-mcp"
+  },
+  "homepage": "https://github.com/Fearvox/Evensong/tree/main/packages/research-vault-mcp",
+  "bugs": {
+    "url": "https://github.com/Fearvox/Evensong/issues"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/**/*.ts",
+    "bin/**/*.mjs",
+    "README.md",
+    "package.json"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "research-vault",
+    "claude-code",
+    "evermind",
+    "dash-shatter",
+    "syndash"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.80.0",
+    "markitdown": "latest"
+  }
+}

package/src/amplify.ts

@@ -0,0 +1,245 @@
+// Amplify API MCP Tools
+// Vanderbilt AI Amplify platform — chat, models, file management
+
+const AMPLIFY_BASE = 'https://prod-api.vanderbilt.ai'
+
+export interface AmplifyConfig {
+  apiKey: string
+}
+
+let config: AmplifyConfig | null = null
+
+export function configureAmplify(apiKey: string) {
+  config = { apiKey }
+}
+
+function getHeaders() {
+  if (!config?.apiKey) throw new Error('Amplify API key not configured. Call configureAmplify() first.')
+  return {
+    'Authorization': `Bearer ${config.apiKey}`,
+    'Content-Type': 'application/json'
+  }
+}
+
+export interface ModelInfo {
+  id: string
+  name: string
+  provider: string
+  inputContextWindow: number
+  outputTokenLimit: number
+  supportsImages: boolean
+  supportsSystemPrompts: boolean
+  systemPrompt?: string
+}
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+export interface ChatOptions {
+  temperature?: number
+  maxTokens?: number
+  dataSources?: string[]
+  modelId?: string
+  ragOnly?: boolean
+  skipRag?: boolean
+}
+
+export const amplifyTools = [
+  {
+    name: 'amplify_list_models',
+    description: 'List available models on Vanderbilt Amplify. Returns model IDs, context windows, providers, and pricing tiers.',
+    inputSchema: { type: 'object', properties: {} },
+    call: async () => {
+      try {
+        const res = await fetch(`${AMPLIFY_BASE}/available_models`, {
+          headers: getHeaders()
+        })
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        const data = await res.json()
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(data, null, 2)
+          }]
+        }
+      } catch (e: any) {
+        return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true }
+      }
+    }
+  },
+
+  {
+    name: 'amplify_chat',
+    description: 'Send a streaming chat message to Amplify. Returns Claude/GPT/Mistral responses via SSE.',
+    inputSchema: {
+      type: 'object',
+      required: ['message'],
+      properties: {
+        message: { type: 'string', description: 'User message' },
+        modelId: { type: 'string', description: 'Model ID (from amplify_list_models)' },
+        systemPrompt: { type: 'string', description: 'Optional system prompt override' },
+        temperature: { type: 'number', description: 'Temperature (0-2, default 0.7)' },
+        maxTokens: { type: 'number', description: 'Max output tokens (default 4000)' },
+        stream: { type: 'boolean', description: 'If true, yield chunks via onProgress callback instead of waiting for complete response (default false)' }
+      }
+    },
+    call: async ({ message, modelId, systemPrompt, temperature = 0.7, maxTokens = 4000, stream = false }: {
+      message: string, modelId?: string, systemPrompt?: string, temperature?: number, maxTokens?: number, stream?: boolean
+    }, onProgress?: (data: { type: string; text?: string }) => void) => {
+      try {
+        const body: any = {
+          data: {
+            model: modelId || 'gpt-4o',
+            temperature,
+            max_tokens: maxTokens,
+            messages: [{ role: 'user', content: message }]
+          }
+        }
+        if (systemPrompt) {
+          body.data.messages.unshift({ role: 'system', content: systemPrompt })
+        }
+
+        const res = await fetch(`${AMPLIFY_BASE}/chat`, {
+          method: 'POST',
+          headers: getHeaders(),
+          body: JSON.stringify(body)
+        })
+
+        if (!res.ok) {
+          const err = await res.text()
+          throw new Error(`HTTP ${res.status}: ${err}`)
+        }
+
+        // Read SSE stream
+        const reader = res.body?.getReader()
+        if (!reader) throw new Error('No response body')
+
+        let fullText = ''
+        const decoder = new TextDecoder()
+
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) break
+          const chunk = decoder.decode(value, { stream: true })
+          // Parse SSE lines: data: {...}
+          for (const line of chunk.split('\n')) {
+            if (line.startsWith('data: ')) {
+              try {
+                const parsed = JSON.parse(line.slice(6))
+                if (parsed.data?.content) fullText += parsed.data.content
+                else if (parsed.data) fullText += typeof parsed.data === 'string' ? parsed.data : JSON.stringify(parsed.data)
+              } catch {}
+            }
+          }
+        }
+
+        // ── Stream mode: yield chunks via onProgress ─────────────────────────
+        if (stream && onProgress) {
+          const res2 = await fetch(`${AMPLIFY_BASE}/chat`, {
+            method: 'POST',
+            headers: getHeaders(),
+            body: JSON.stringify(body)
+          })
+          if (!res2.ok) throw new Error(`HTTP ${res2.status}`)
+          const reader2 = res2.body?.getReader()
+          if (!reader2) throw new Error('No response body')
+          const decoder2 = new TextDecoder()
+          let buffer2 = ''
+          while (true) {
+            const { done, value } = await reader2.read()
+            if (done) break
+            buffer2 += decoder2.decode(value, { stream: true })
+            for (const line of buffer2.split('\n')) {
+              if (line.startsWith('data: ')) {
+                try {
+                  const parsed = JSON.parse(line.slice(6))
+                  if (parsed.data?.content) {
+                    onProgress({ type: 'chunk', text: parsed.data.content })
+                  }
+                } catch {}
+              }
+            }
+          }
+          return { content: [{ type: 'text', text: '(streamed)' }] }
+        }
+
+        return {
+          content: [{ type: 'text', text: fullText || '(no response)' }]
+        }
+      } catch (e: any) {
+        return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true }
+      }
+    }
+  },
+
+  {
+    name: 'amplify_files_query',
+    description: 'Query uploaded files on Amplify using semantic search. Returns relevant file chunks.',
+    inputSchema: {
+      type: 'object',
+      required: ['query'],
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        limit: { type: 'number', description: 'Max results (default 5)' }
+      }
+    },
+    call: async ({ query, limit = 5 }: { query: string, limit?: number }) => {
+      try {
+        const res = await fetch(`${AMPLIFY_BASE}/files/query`, {
+          method: 'POST',
+          headers: getHeaders(),
+          body: JSON.stringify({ query, limit })
+        })
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        const data = await res.json()
+        return {
+          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
+        }
+      } catch (e: any) {
+        return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true }
+      }
+    }
+  },
+
+  {
+    name: 'amplify_files_list',
+    description: 'List tags/categories of uploaded files on Amplify.',
+    inputSchema: { type: 'object', properties: {} },
+    call: async () => {
+      try {
+        const res = await fetch(`${AMPLIFY_BASE}/files/tags/list`, {
+          headers: getHeaders()
+        })
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        const data = await res.json()
+        return {
+          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
+        }
+      } catch (e: any) {
+        return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true }
+      }
+    }
+  },
+
+  {
+    name: 'amplify_assistants_list',
+    description: 'List your Amplify assistants.',
+    inputSchema: { type: 'object', properties: {} },
+    call: async () => {
+      try {
+        const res = await fetch(`${AMPLIFY_BASE}/assistant/list`, {
+          headers: getHeaders()
+        })
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        const data = await res.json()
+        return {
+          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
+        }
+      } catch (e: any) {
+        return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true }
+      }
+    }
+  }
+]

package/src/ingest/arxiv.ts

@@ -0,0 +1,64 @@
+import type { ArxivMetadata } from '../types.js'
+
+const ARXIV_API = 'https://export.arxiv.org/api/query'
+
+/**
+ * Parse an ArXiv ID from various URL formats.
+ * Handles:
+ *   https://arxiv.org/abs/2501.00001
+ *   http://arxiv.org/abs/2501.00001v2
+ *   abs/2501.00001
+ *   2501.00001v2
+ */
+export function parseArxivId(value: string): string | null {
+  // Bare versioned ID: 2501.00001v2
+  if (/^\d{4}\.\d{4,}(v\d+)?$/.test(value.trim())) {
+    return value.trim()
+  }
+  // URL or abs/ shorthand
+  const m = value.match(/(?:arxiv\.org\/abs\/|abs\/?)(\d{4}\.\d{4,}(?:v\d+)?)/i)
+  return m ? m[1] : null
+}
+
+export async function fetchArxivMetadata(id: string): Promise<ArxivMetadata> {
+  const url = `${ARXIV_API}?id_list=${id}`
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`ArXiv API error: ${res.status}`)
+  const xml = await res.text()
+  return parseArxivXml(xml)
+}
+
+function parseArxivXml(xml: string): ArxivMetadata {
+  // Extract title
+  const titleMatch = xml.match(/<title[^>]*>([\s\S]*?)<\/title>/i)
+  const title = titleMatch
+    ? titleMatch[1].replace(/\s+/g, ' ').trim()
+    : null
+
+  // Extract abstract/summary
+  const summaryMatch = xml.match(/<summary[^>]*>([\s\S]*?)<\/summary>/i)
+  const abstract = summaryMatch
+    ? summaryMatch[1].replace(/\s+/g, ' ').trim()
+    : null
+
+  // Extract all authors
+  const authors: string[] = []
+  const authorRe = /<author>[\s\S]*?<name>([\s\S]*?)<\/name>[\s\S]*?<\/author>/gi
+  let m
+  while ((m = authorRe.exec(xml)) !== null) {
+    authors.push(m[1].replace(/\s+/g, ' ').trim())
+  }
+
+  // Extract categories
+  const categories: string[] = []
+  const catRe = /<category[^>]*term="([^"]+)"/gi
+  while ((m = catRe.exec(xml)) !== null) categories.push(m[1])
+
+  return {
+    title,
+    authors: authors.length ? authors : null,
+    abstract,
+    arxivId: null,  // set by caller
+    categories: categories.length ? categories : null
+  }
+}

package/src/ingest/html.ts

@@ -0,0 +1,46 @@
+// packages/research-vault-mcp/src/ingest/html.ts
+
+/**
+ * Fetch a URL and convert HTML to plain markdown-like text.
+ * Strips scripts, styles, nav, footer, header, aside elements.
+ * Uses Bun's native fetch — no external dependencies.
+ */
+export async function fetchHtml(url: string): Promise<string> {
+  const res = await fetch(url, {
+    headers: {
+      'User-Agent': 'Mozilla/5.0 research-vault-mcp/1.1.0',
+      'Accept': 'text/html'
+    }
+  })
+  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`)
+  const html = await res.text()
+
+  let text = html
+    .replace(/<script[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[\s\S]*?<\/style>/gi, '')
+    .replace(/<nav[\s\S]*?<\/nav>/gi, '')
+    .replace(/<footer[\s\S]*?<\/footer>/gi, '')
+    .replace(/<header[\s\S]*?<\/header>/gi, '')
+    .replace(/<aside[\s\S]*?<\/aside>/gi, '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+
+  // Block elements → newlines
+  text = text.replace(/<\/(p|div|br|h[1-6]|li|tr)>/gi, '\n')
+
+  // Remove all remaining tags
+  text = text.replace(/<[^>]+>/g, '')
+
+  // Decode common HTML entities
+  text = text
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+
+  // Collapse whitespace
+  text = text.replace(/\n{3,}/g, '\n\n').trim()
+
+  return text
+}

package/src/ingest/pdf.ts

@@ -0,0 +1,30 @@
+// packages/research-vault-mcp/src/ingest/pdf.ts
+
+/**
+ * Convert PDF to markdown using markitdown (preferred) or pandoc.
+ * Uses Bun.spawn for process execution — no child_process module needed.
+ * Returns null if neither tool is available.
+ */
+export async function convertPdfToMarkdown(pdfPath: string): Promise<string | null> {
+  // Try markitdown first
+  try {
+    const proc = Bun.spawn(['markitdown', pdfPath], { timeout: 60_000 })
+    const [exited] = await proc.exited
+    if (exited === 0) {
+      const output = await new Response(proc.stdout as Blob).text()
+      if (output.trim()) return output
+    }
+  } catch {}
+
+  // Fallback: pandoc
+  try {
+    const proc = Bun.spawn(['pandoc', '--to', 'markdown', pdfPath], { timeout: 60_000 })
+    const [exited] = await proc.exited
+    if (exited === 0) {
+      const output = await new Response(proc.stdout as Blob).text()
+      if (output.trim()) return output
+    }
+  } catch {}
+
+  return null
+}