The Obsidian MCP Wrapper was the cleaner, more reusable version of the vault retrieval work that came out of my Peoples First AI infrastructure. The extracted version is available at UwUGreed/obsidian-mcp-wrapper.
The problem was straightforward: Claude needed access to useful operational notes, but direct access to a live Obsidian vault is too broad. A model should not be able to wander the filesystem, read everything by default, or write into important notes without a human gate.
So I built a two-layer system.
The Runtime Shape
The project is split into two processes:
pf-mcp, a lightweight STDIO MCP shim that runs on a workstation.pf-index, a LAN retrieval service that owns indexing, authentication, signed handles, and write auditing.
That split keeps the workstation piece small and pushes the sensitive work into one controlled service. The shim validates tool arguments before sending requests over the network. The index service decides what can be read, what can be expanded, and how writes are routed.
Progressive Disclosure
The central design idea is progressive disclosure.
The model should not receive whole notes by default. It should search first, get compact snippets and signed handles, then expand only the sections it actually needs.
That solves two problems at once:
- The model's context window stays under control.
- The system can audit exactly what section was handed over.
Handles include the vault id, path, line range, file hash, content hash, and index epoch. They are signed with HMAC, so tampering with the payload breaks verification.
Immutable Index Epochs
The indexer builds immutable snapshots under .pf_index/builds/<epoch>/. Each epoch includes a manifest, SQLite FTS5 search index, and content snapshots for indexed Markdown files.
When a handle is expanded later, the service resolves it against the retained snapshot from that epoch instead of reading the changed live file.
That matters because retrieval should be reproducible. If the model cites a section from a search result, that handle should mean the same thing later, at least while the epoch is retained.
Write Gates
The write path is deliberately conservative.
Autonomous AI notes are routed to a capture inbox by default. Direct writes into client, provider, carrier, or operational files require explicit human direction. Writes are append-only, locked, audited, and bounded by note length limits.
That design came from the real risk of AI memory systems. A model can be useful at capturing context, but it should not be allowed to quietly rewrite the business record just because it sounded confident.
What I Like About This Build
This is one of the strongest projects from the internship because it turned a messy internal need into a reusable architecture.
It combines:
- MCP tool design.
- Local-first retrieval.
- Filesystem path validation.
- Signed context handles.
- SQLite FTS5 indexing.
- Audit-oriented writes.
- Operational deployment docs.
It is not just a wrapper around a folder of Markdown files. It is a safer pattern for letting AI retrieve and contribute to a knowledge base without treating the model like an unrestricted user.