Skip to content
Back to search

vault-mcp

Personal knowledge vault as a remote MCP server with built-in single-user OAuth 2.1, hybrid retrieval and a retrieval eval

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/igmizo--vault-mcp/badge.svg)](/listings/igmizo--vault-mcp)

HTML

<a href="/listings/igmizo--vault-mcp"><img src="/api/listings/igmizo--vault-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 213 lines
  1. # vault-mcp
  2. Personal knowledge vault, served to Claude.
  3. A plain-markdown, git-versioned vault exposed as a **remote MCP server** with
  4. its own **single-user OAuth 2.1 authorization server**, published through a
  5. Cloudflare Tunnel and usable as a Claude custom connector from any device.
  6. An earlier build of this code has been running in production since
  7. mid-2026, guarding its owner's private notes.
  8. What is interesting in here:
  9. - **Remote MCP, stateless.** Streamable HTTP, a fresh server per request, no
  10. session state anywhere. Six tools.
  11. - **OAuth 2.1 written from the spec, for exactly one user.** Discovery
  12. metadata, Dynamic Client Registration, PKCE S256 only, rotating refresh
  13. tokens with reuse detection, tokens stored as hashes. About 800 lines,
  14. no auth library — [`server/src/oauth.ts`](server/src/oauth.ts).
  15. - **Hybrid retrieval.** A ripgrep keyword leg and a local-embedding semantic
  16. leg (EmbeddingGemma, no API, no key), fused with reciprocal rank fusion.
  17. The index heals itself on every query.
  18. - **A retrieval eval.** A labelled question set over a public fixture
  19. corpus; hit@k, MRR, nDCG, per-category breakdown, baseline diffs and a CI
  20. gate — [`docs/eval.md`](docs/eval.md).
  21. - **Backups you can restore.** Nightly encrypted git bundle plus restic,
  22. with a written restore drill — [`ops/README.md`](ops/README.md).
  23. - **One test that covers the lot.** `npm run smoke` boots the server against
  24. a throwaway vault and runs 107 end-to-end checks in seconds.
  25. ## Run it
  26. ```bash
  27. cd server
  28. npm install
  29. npm run build
  30. npm run smoke # full OAuth + MCP + git flow against a temp vault
  31. npm run eval:ci # metric self-test + eval on the fixture corpus
  32. ```
  33. Needs Node 20+ and `git`. To run the server itself, see [Deploy](#deploy).
  34. ## Architecture
  35. ```
  36. Claude (phone/web, via Anthropic cloud) Telegram bot (optional)
  37. │ https │ long-poll (outbound)
  38. ▼ ▼
  39. Cloudflare edge assistant listener (systemd,
  40. │ tunnel (outbound-only) chat + capture, sandboxed)
  41. ┌─ server ──────────────────────────────────────────────┼───────────────┐
  42. │ cloudflared ──► vault-mcp (MCP :3000, OAuth 2.1) ◄───┘ │
  43. │ │ isolated docker network, loopback publish │
  44. │ vault/ (markdown, git) ⇄ vault.git (bare, hooks) │
  45. │ │ ▲ │
  46. │ nightly: encrypted bundle + restic ──► offsite storage │
  47. └─────────────────────┼──────────────────────────┼──────────────────────┘
  48. │ Tailscale Serve │ git over Tailscale SSH
  49. ▼ ▼
  50. Claude Code (laptop) Obsidian on ~/vault (laptop)
  51. ```
  52. Every piece, schedule and runbook is in
  53. [`docs/how-it-works.md`](docs/how-it-works.md). The decisions behind it are in
  54. [`docs/decisions/`](docs/decisions/).
  55. ## What Claude gets
  56. | Tool | Does |
  57. | ----------------------- | ------------------------------------------------------------ |
  58. | `vault_search_notes` | regex/text search across the vault (ripgrep) |
  59. | `vault_semantic_search` | meaning-based search — concepts, paraphrase, cross-language; hybrid RRF with the keyword leg |
  60. | `vault_read_note` | read one note |
  61. | `vault_write_note` | create/append/overwrite a note + git auto-commit |
  62. | `vault_list_notes` | browse folders and notes |
  63. | `vault_recent_notes` | most recently modified notes |
  64. Every write is committed to git as author `vault-mcp`, so `git log` is an
  65. audit trail and `git diff` is your curation gate.
  66. ## Deploy
  67. Prereqs: a server with Docker, a domain on Cloudflare. About 15 minutes.
  68. 1. **Copy this folder to the server** (e.g. `/opt/vault-mcp`) and make the
  69. vault its own repo:
  70. ```bash
  71. cd /opt/vault-mcp
  72. cp -r vault-template vault
  73. cd vault && git init && git add . && git commit -m "vault: founding"
  74. ```
  75. 2. **Create the tunnel.** Cloudflare dashboard → Zero Trust → Networks →
  76. Tunnels → Create tunnel (Cloudflared). Copy the token. Add a public
  77. hostname: `vault.example.com` → service `http://vault-mcp:3000`.
  78. 3. **Configure environment:**
  79. ```bash
  80. cp .env.example .env
  81. # set VAULT_MCP_PUBLIC_URL=https://vault.example.com
  82. # set VAULT_MCP_PASSWORD to something strong: openssl rand -base64 24
  83. # paste CLOUDFLARE_TUNNEL_TOKEN
  84. ```
  85. 4. **Launch:**
  86. ```bash
  87. docker compose up -d --build
  88. curl -s https://vault.example.com/healthz # → {"ok":true,...}
  89. ```
  90. 5. **Connect Claude.** Settings → Connectors → Add custom connector → URL
  91. `https://vault.example.com/mcp` → Add → Connect. You land on the
  92. passphrase page; enter `VAULT_MCP_PASSWORD` once. Claude handles tokens
  93. and refresh from there.
  94. 6. **Laptop workflow (optional):** keep a bare repo next to the working
  95. tree, clone it over Tailscale SSH, open the folder in Obsidian, commit
  96. and push. Sync is event-driven — a `post-receive` hook updates the served
  97. tree on push, a `post-commit` hook propagates server-side writes back,
  98. and an hourly cron reconcile is the healing net.
  99. Semantic search needs the EmbeddingGemma model files pre-seeded on the data
  100. volume (runtime downloads are disabled on purpose) — see `ops/README.md`. A
  101. hosted OpenAI `text-embedding-3-large` backend ships dark as the escape
  102. hatch (`VAULT_MCP_EMBEDDER=openai` + key); switching either way is an env
  103. flip, the index rebuilds itself.
  104. ## Security model
  105. - **No inbound ports.** cloudflared makes outbound connections only; the MCP
  106. port is never exposed on the host. The compose network is isolated — keep
  107. it away from any other stack on the box.
  108. - **OAuth 2.1, single user.** PKCE S256 mandatory, Dynamic Client
  109. Registration, `client_id` bound to every code and refresh token. Claude
  110. connectors do not support static bearer tokens, which is why this server
  111. carries its own tiny authorization server.
  112. - **Rotating refresh tokens with reuse detection.** Every refresh
  113. invalidates the old pair. A rotated token that comes back later revokes
  114. every token descended from that login.
  115. - **Hashed tokens at rest.** Only SHA-256 hashes are stored; a leaked data
  116. volume leaks no live credentials. The state file is written atomically,
  117. mode 0600.
  118. - **Login throttling that cannot be dodged with a header.** Failed
  119. passphrase attempts are limited per client IP and globally. The client IP
  120. comes from a fixed trusted-proxy hop count, not from whatever
  121. `X-Forwarded-For` the caller sends. The trade-off: 30 wrong guesses lock
  122. new logins for 15 minutes; existing tokens keep working.
  123. - **Bounded open registration.** DCR has to be open for Claude, so it is
  124. capped: https or loopback redirects only, size and rate limits, an
  125. optional host allow-list. The consent page shows where the code will be
  126. sent, because the client name is whatever the registrant typed.
  127. - **Path safety.** Every path is resolved and confined to the vault; the
  128. smoke test asserts traversal is rejected.
  129. - **No secrets in the vault.** The server serves whatever is in the vault,
  130. so never write credentials into notes.
  131. Rotate access by changing `VAULT_MCP_PASSWORD` and deleting the
  132. `vault-mcp-data` volume (`docker compose down -v` keeps the vault, drops
  133. issued tokens), then reconnecting in Claude.
  134. ## Eval
  135. `server/scripts/eval.mjs` runs a labelled question set through the keyword,
  136. semantic and hybrid legs and reports hit@1/3/5, MRR@10, nDCG@10, recall@10,
  137. latency, and how well the top score separates answerable from unanswerable
  138. questions. The repo ships a synthetic 48-note fixture vault with 71
  139. questions in seven categories (keyword, paraphrase, cross-language,
  140. deep-section, distractor, exact-term, no-answer), so anyone can run it.
  141. The eval set used against the real vault is private, because the questions
  142. describe the notes. Point the runner at your own with
  143. `--vault <dir> --questions <file>`.
  144. Results on the fixture corpus with the production model (EmbeddingGemma):
  145. | Mode | hit@1 before → after | hit@5 before → after | nDCG@10 before → after |
  146. | -------- | -------------------- | -------------------- | ---------------------- |
  147. | keyword | 0.60 → 0.67 | 0.76 → 0.79 | 0.69 → 0.73 |
  148. | semantic | 0.83 (unchanged) | 1.00 (unchanged) | 0.92 (unchanged) |
  149. | hybrid | 0.68 → 0.89 | 0.87 → 1.00 | 0.80 → 0.94 |
  150. The first real-model run showed hybrid, the default, scoring below semantic
  151. alone: rank fusion let a weak keyword match outrank a note only the
  152. embeddings had found. The keyword leg now matches whole words, keeps
  153. identifiers such as `v1.4.2` or `--read-data-subset` whole, and scores with
  154. BM25; its rank only counts when a note contains the query's terms. Hybrid
  155. is now ahead of semantic, and the lead comes from exact identifiers: error
  156. codes, ports, config keys. The response also carries a confidence value
  157. that drops to zero when the query names an identifier no note contains.
  158. Both reports are committed, so the change is diffable. The lead over
  159. semantic is a handful of questions on a small synthetic corpus, and
  160. [`docs/eval.md`](docs/eval.md) says exactly how far to trust it and what
  161. is still weak.
  162. ## Layout
  163. - `server/` — the MCP server (TypeScript, strict). `src/oauth.ts` is the
  164. authorization server, `src/tools.ts` the six tools, `src/vault.ts` the
  165. filesystem + git layer, `src/semantic/` the embedder, chunker, index store
  166. and hybrid search.
  167. - `server/scripts/smoke.mjs` — the end-to-end test suite.
  168. - `server/eval/` — fixture vault, questions, baseline report.
  169. - `ops/` — backup, reindex, liveness and alert scripts, with runbooks.
  170. - `jobs/` — optional host jobs: a morning briefing and a Telegram listener.
  171. - `vault-template/` — starter vault and its conventions.
  172. - `docs/` — how it works, decision records, the eval, capture conventions.
  173. ## License
  174. MIT — see [`LICENSE`](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.