vault-mcp: Instructions file for Claude Code

vault-mcp

Authenticated remote MCP server (Cloudflare Workers) that exposes a private, GitHub-hosted Obsidian vault to claude.ai and Claude Code. Reads (list/read/search) plus two note mutations: write_note (create/overwrite) and delete_note — no rename/move. The target repo and access policy are configured through secrets; path-scope overrides default in src/config.ts, so wrangler.jsonc ships generic (no vars).

Invariants — keep these intact when changing code

• Notes-only, no rename/move. The mutations are write_note (create/overwrite a markdown note) and delete_note (remove one). Never add a rename/move tool — the GitHub API has no atomic move and it would silently break Obsidian wikilinks. Never let a mutation touch non-note files — writeNote and deleteNote in vault.ts must keep enforcing the .md/.markdown extension check.
• Policy lives in vault.ts, never in a backend. Storage backends (src/storage/) implement VaultStorage and only move bytes. All guards run in VaultClient before a path reaches a backend, so a new backend cannot weaken them. Add backends by implementing the interface and wiring it in vaultClientFromEnv.
• Writes and deletes obey the same path policy as reads. write_note and delete_note must run every guard read_note does — ../absolute rejection and VAULT_ALLOWED_PREFIXES / VAULT_DENIED_PREFIXES — so a mutation can never reach .git/, .obsidian/, or agent dirs. Preserve this when touching write/delete logic.
• The login allowlist gates the whole toolset. An identity absent from the configured provider's allowlist (VAULT_ALLOWED_GITHUB_LOGINS for AUTH_PROVIDER=github, VAULT_ALLOWED_GOOGLE_EMAILS for google, VAULT_ALLOWED_OIDC_EMAILS for oidc) must get zero tools, not a reduced set — see guard.ts. Login providers live in src/auth/providers/; the flow in auth/handler.ts is provider-agnostic. Google and the generic oidc provider share createOidcProvider; an email identity must be verified (email_verified: true) before it can match. The only exception is the explicit OIDC_ALLOW_UNVERIFIED_EMAIL=true opt-in for IdPs that never send the claim — an explicit email_verified: false is rejected regardless. Keep the OIDC discovery document's issuer check in providers/oidc/discovery.ts: without it a hostile host could supply foreign endpoints.
• VAULT_GITHUB_TOKEN stays single-repo scoped. It needs Contents: Read and Write (Write covers both write_note and delete_note), but only on the vault repo. Never widen it beyond that one repo or swap in a broader token.
• Path safety. vault.ts enforces VAULT_ALLOWED_PREFIXES / VAULT_DENIED_PREFIXES (defaults in src/config.ts; DEFAULT_DENIED_PREFIXES must keep hiding .git/, .obsidian/, and agent dirs) and rejects .. traversal and absolute paths in read_note, write_note, and delete_note. Preserve this when touching read/write/delete logic.