@syndash/research-vault-mcp 1.1.2 → 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

@@ -17,12 +17,15 @@ bunx @syndash/research-vault-mcp --transport=stdio
 
 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.
 
-Use SSE only when you explicitly want a long-running HTTP server:
+**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=sse
-# health: http://127.0.0.1:8765/health
-# sse:    http://127.0.0.1:8765/sse
+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
@@ -76,6 +79,20 @@ export VAULT_ROOT=/path/to/research-vault
 
 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:
@@ -84,12 +101,14 @@ Current MCP contract:
 - `vault_status` — registry, retention, and decay health
 - `vault_taxonomy` — category tree and item counts
 - `vault_batch_analyze` — raw queue status and preview
-- `vault_note_save` — persist a markdown note into the vault
 - `vault_get` — retrieve a saved vault item by id
-- `vault_delete` — delete a saved vault item
-- `vault_raw_ingest` — queue a raw URL/text ingest job
+- `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:
@@ -116,6 +135,14 @@ score(d, q, t) = lexical(q,d)
 
 The Evensong benchmark evidence for hybrid retrieval and Dense RAR lives in the parent repo under `benchmarks/`.
 
+## Node compatibility status
+
+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
 
 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`.