@syndash/research-vault-mcp 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## Unreleased
+
+## 1.1.3 — 2026-05-10
+
+### Added
+
+- HTTP transport now supports Streamable HTTP at `POST /mcp`, while keeping the legacy `/sse` + `/messages` endpoints.
+- Added a Streamable HTTP regression test that initializes a session and lists MCP tools through `/mcp`.
+- Documented the default read-only MCP profile, including the public-safe read/evidence tool surface and the `full`/`admin` opt-in for mutation-capable tools.
+- Added public guidance for the provenance/freshness response envelope, including `agent_guidance` and evidence metadata on search, status, and batch responses.
+
+### Changed
+
+- `vault_get` is documented as bounded by default, with operator-approved `include_content:true` and `max_chars` caps for larger reads.
+- Mutation blocking guidance now tells operators to restart in `MCP_PROFILE=full` or `MCP_PROFILE=admin` before using write/configure tools.
+- Public-surface safety redaction is documented for local paths, credential markers, and private network values.
+
+## 1.1.2 — 2026-04-26
+
+### Changed
+
+- Default MCP transport is now `stdio`, matching command-launched MCP clients.
+- The npm bin is a Node-compatible launcher that delegates server execution to Bun.
+- Published package includes `dist/server.js` via `prepack` build and `files` allowlist.
+- README now documents Evensong hub vs Research Vault module, install commands, Claude config, Bun runtime requirement, and explicit SSE mode.
+- Package metadata now uses Evensong module wording and Apache-2.0 package license.
+
+### Verified
+
+- `bun --filter @syndash/research-vault-mcp test`
+- `bun --filter @syndash/research-vault-mcp build`
+- `npm pack --dry-run --json`
+- stdio smoke returning 13 MCP tools

package/README.md

@@ -1,74 +1,148 @@
 # @syndash/research-vault-mcp
 
-MCP (Model Context Protocol) server for Nolan's research vault (private) — semantic search + memory persistence over 200+ markdown documents via local Gemma (Atomic Chat) or cloud LLM fallback.
+Research Vault is the memory/search module inside **Evensong**. This package exposes it as an MCP server for agents that speak the Model Context Protocol.
 
-**Part of**: DASH SHATTER / SynDASH ecosystem.
-**Home**: [github.com/Fearvox/Evensong](https://github.com/Fearvox/Evensong) — `packages/research-vault-mcp/`
+It is not the whole Evensong product. Evensong is the hub: runtime, benchmark evidence, handoff pages, and modules. Research Vault MCP is the installable knowledge-base module.
 
-## Install & Run
+## Install
 
 ```bash
-# Via bun (recommended — native TS execution)
-bunx @syndash/research-vault-mcp
+# MCP clients usually launch the package for you.
+# The npm shim still delegates runtime execution to Bun.
+npx @syndash/research-vault-mcp --transport=stdio
 
-# Via Node
-npx @syndash/research-vault-mcp
+# Bun direct launch:
+bunx @syndash/research-vault-mcp --transport=stdio
 ```
 
-## Configure Claude Code / Claude Desktop
+Default transport is `stdio`, because command-launched MCP servers are expected to speak JSON-RPC over stdin/stdout. Install [Bun](https://bun.sh) before using either `npx` or `bunx`; the server itself is Bun-native.
 
-Add to `~/.claude/settings.json` or Claude Desktop config:
+**Runtime note:** `@syndash/research-vault-mcp` is Bun-native. `npx` is supported as an install/launch shim, but the target machine must have `bun` available on `PATH`. If you need a pure Node runtime, treat that as a separate compatibility track rather than assuming this package already provides it.
+
+Use HTTP only when you explicitly want a long-running remote MCP server. The HTTP server exposes both the current Streamable HTTP endpoint and the legacy SSE endpoint:
+
+```bash
+MCP_PORT=8765 npx @syndash/research-vault-mcp --transport=http
+# streamable: http://127.0.0.1:8765/mcp
+# legacy sse: http://127.0.0.1:8765/sse
+# health:     http://127.0.0.1:8765/health
+```
+
+## Configure an MCP client
+
+Claude Desktop / Claude Code style config:
+
+```json
+{
+  "mcpServers": {
+    "research_vault": {
+      "command": "npx",
+      "args": ["-y", "@syndash/research-vault-mcp", "--transport=stdio"]
+    }
+  }
+}
+```
+
+Bun variant:
 
 ```json
 {
   "mcpServers": {
-    "research-vault": {
+    "research_vault": {
       "command": "bunx",
-      "args": ["@syndash/research-vault-mcp"]
+      "args": ["--bun", "@syndash/research-vault-mcp", "--transport=stdio"]
     }
   }
 }
 ```
 
-For direct local dev from this monorepo:
+Local monorepo development:
 
 ```json
 {
   "mcpServers": {
-    "research-vault-dev": {
+    "research_vault_dev": {
       "command": "bun",
-      "args": ["run", "packages/research-vault-mcp/src/server.ts"]
+      "args": ["run", "packages/research-vault-mcp/src/server.ts", "--transport=stdio"]
     }
   }
 }
 ```
 
-## Tools Exposed (MCP contract)
+## Configure the vault root
+
+Set the vault location with an environment variable before launching your MCP client:
 
-See `src/vault.ts` and `src/amplify.ts` for current tool definitions:
+```bash
+export VAULT_ROOT=/path/to/research-vault
+```
 
-- `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 relay layer powered by SynDASH (Amplify-compatible API endpoint, self-hosted relay; no external vendor required)
+The package is designed for markdown-based knowledge bases. Keep private vault contents outside the public Evensong repo.
+
+## MCP Profiles
+
+`MCP_PROFILE=readonly` is the default public-safe autonomous-agent profile. It exposes only read/evidence tools:
+
+- `vault_status`
+- `vault_taxonomy`
+- `vault_search`
+- `vault_get`
+- `vault_batch_analyze`
+
+Mutation tools are hidden and blocked in `readonly`. `MCP_PROFILE=full` enables non-destructive mutators such as `vault_raw_ingest` and `vault_note_save`. `MCP_PROFILE=admin` is required for destructive or admin tools such as `vault_delete`.
+
+`vault_get` is bounded by default: it returns an excerpt unless the operator approves `include_content:true`, and even full-content requests are capped by `max_chars`. Search, status, and batch responses include `agent_guidance` plus evidence metadata for provenance, freshness, profile, and public-safety state.
+
+## Tools exposed
+
+Current MCP contract:
+
+- `vault_search` — search analyzed knowledge-base entries
+- `vault_status` — registry, retention, and decay health
+- `vault_taxonomy` — category tree and item counts
+- `vault_batch_analyze` — raw queue status and preview
+- `vault_get` — retrieve a saved vault item by id
+- `vault_raw_ingest` — queue a raw URL/text ingest job (`full` or `admin` profile only)
+- `vault_note_save` — persist a markdown note into the vault (`full` or `admin` profile only)
+- `vault_delete` — delete a saved vault item (`admin` profile only; destructive)
+- `amplify_*` — optional remote RAG query layer when Amplify credentials are configured
+
+Public MCP responses are redacted before they leave the server if they contain local paths, credential markers, or private network values. Use a private operator session for diagnostics that need raw source details.
+
+## Package mechanics
+
+Published packages include:
+
+- `bin/research-vault-mcp.mjs`
+- `dist/server.js`
+- `src/**/*.ts` for source inspection
+- `README.md`
+- `package.json`
+
+The bin prefers `dist/server.js`. In a monorepo checkout without `dist`, it falls back to `bun run src/server.ts` so development remains fast without a separate compile step.
 
 ## Architecture
 
-Retrieval uses a **unified multi-signal ranker** (not 3 separate subsystems):
+Research Vault MCP uses a multi-signal ranker for candidate retrieval:
 
+```text
+score(d, q, t) = lexical(q,d)
+               + semantic(embed(q), embed(d))
+               + recency/stability(d,t)
+               + access frequency(d)
+               + summary-level weight(d)
 ```
-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.
+The Evensong benchmark evidence for hybrid retrieval and Dense RAR lives in the parent repo under `benchmarks/`.
+
+## Node compatibility status
 
-**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).
+The package is intentionally Bun-native today because the server uses Bun APIs and the parent Evensong repo is Bun-only. The npm bin is Node-compatible only as a launcher: it locates `dist/server.js` or `src/server.ts`, then delegates execution to `bun`. This keeps package installation convenient while avoiding a misleading claim that the MCP server itself runs under plain Node.js.
 
 ## License
 
-`UNLICENSED` for now (pending org-level license decision). See parent repo LICENSE.
+Apache-2.0 for package code. Research artifacts in the parent repo may use separate licenses; check the repository root license files.
+
+## Releases
+
+See [CHANGELOG.md](./CHANGELOG.md). Current npm release: `1.1.2`.

package/bin/research-vault-mcp.mjs

@@ -1,49 +1,65 @@
 #!/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.
+ * The server is Bun-native. The npm bin is a small Node-compatible shim so
+ * `npx` can install the package, then delegate execution to `bun`.
  */
 
 import { fileURLToPath } from 'url'
 import { dirname, join } from 'path'
 import { existsSync } from 'fs'
+import { spawn } from 'child_process'
 
 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'
-
+function parseTransport(args) {
   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]
-    }
+    if (args[i] === '--transport' && args[i + 1]) return args[i + 1]
+    if (args[i]?.startsWith('--transport=')) return args[i].split('=')[1]
   }
-  process.env.MCP_TRANSPORT = transport
+  return 'stdio'
+}
+
+function runWithBun(entrypoint, args) {
+  const child = spawn('bun', [entrypoint, ...args], {
+    cwd: pkgRoot,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      MCP_TRANSPORT: parseTransport(args),
+    },
+  })
+
+  child.on('exit', (code, signal) => {
+    if (signal) process.kill(process.pid, signal)
+    process.exit(code ?? 1)
+  })
+
+  child.on('error', err => {
+    console.error('research-vault-mcp: failed to spawn bun')
+    console.error('Install Bun first: https://bun.sh')
+    console.error(err.message)
+    process.exit(1)
+  })
+}
+
+function main() {
+  const args = process.argv.slice(2)
 
   if (existsSync(compiledServer)) {
-    await import(compiledServer)
+    runWithBun(compiledServer, args)
   } else if (existsSync(sourceServer)) {
-    await import(sourceServer)
+    runWithBun(sourceServer, args)
   } 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)
-})
+main()