Project Vault MCP

Give your agents a project memory you can read, edit, and keep in Git.

Quick start · Connect your agent · Tools · Safe updates · Security · Privacy · Contributing

Project Vault MCP turns ordinary Markdown into a connected knowledge layer for a software project. Retrieve relevant project knowledge on demand to reduce unnecessary token usage, keep context focused, and make better use of your agent's context window. Agents can find architectural context, follow decisions, check references, and create or update notes through the Model Context Protocol.

Your notes stay on your filesystem. Use Obsidian, VS Code, another editor, or plain Git. There is no proprietary vault format, hosted knowledge service, embedding bill, or application-framework dependency.

What you gain

• ⭐ Reduce unnecessary token usage. Retrieve relevant note sections so agents can avoid repeatedly loading entire documentation sets or asking you to paste the same background.

• ⭐ Keep reasoning focused. Bring relevant architecture, conventions, and recorded decisions into the conversation to help reduce distraction from unrelated context and repeated guesswork.

• ⭐ Make better use of limited context windows. Keep project knowledge in durable Markdown and retrieve it when needed, leaving more room in the conversation for the current task.

• ⭐ Spend less time re-explaining your project. Keep architecture, conventions, and decisions in reusable notes that MCP-compatible agents can retrieve across sessions.

• ⭐ Find answers you can trace. Search relevant note sections with file IDs, line numbers, and revision metadata so you can inspect the source behind an answer.

• ⭐ Understand how decisions connect. Follow Markdown links, Obsidian wikilinks, and backlinks; find broken references and ambiguous note names.

• ⭐ Keep knowledge up to date while you work. Create and update notes through MCP, preview changes first, and use revision checks to reject updates based on an older version.

• ⭐ Notice when implementation references change. Compare optional recorded source-file hashes to flag changed files for review.

• ⭐ Keep control of your knowledge. Store editable Markdown locally, manage it in Git, and limit agent access with configured roots, privacy labels, and explicit write permissions.

• ⭐ Use it with your existing project and editor. Adopt an existing documentation folder or start with architecture, module, decision, and runbook templates; use Obsidian, VS Code, or another editor.

• ⭐ Avoid extra search infrastructure. Retrieve project knowledge without an embedding service, a vector database, or a hosted knowledge platform.

Token savings depend on the client, retrieval choices, and workload. Focused retrieval does not increase a model's context limit or guarantee correct reasoning.

Local-first, with a clear boundary: this server makes no model calls and sends no telemetry. Your MCP client can still send retrieved notes to its model provider. Only connect a project you intend that client to access.

Related MCP server: notes-mcp

Without MCP vs. With MCP

A local experiment on October 26, 2026 compared five independent questions over this project's nine accessible documentation notes. These are counted context tokens, not API billing or model-quality results.

The search + read strategy used 36.5% fewer counted tokens than loading all notes in this experiment. Search alone used fewer tokens but omitted some checked details. Neither comparison establishes equivalent answer quality.

• Snapshot: source revision 842e635, using its checked-in project-vault.json and accessible notes. The README itself was outside the configured notes roots.

• Tokenizer: tiktoken 0.14.0, encoding o200k_base. No model or API calls were made.

• Counting: the baseline includes each question and all notes with their note IDs. MCP totals include the question, all six advertised tool definitions (1,148 tokens per question), call arguments, and complete SDK response JSON, including both text and structured content when present. The search + read strategy always reads the highest-ranked note, without using expected-answer labels to select it.

• Excluded: shared system prompts, provider-specific tool framing, cached-input effects, model output, reasoning tokens, and billing. Individual hosts and tokenizers can produce different counts.

The five fixed questions and their counted tokens were:

The expected note appeared in the top three results for 5/5 questions. Search excerpts contained all predefined evidence terms for 2/5 questions; reading the highest-ranked note increased that to 4/5. The remaining check requested the literal parameter expected_revision, while the retrieved configuration note describes the revision requirement without that literal name; that check remains unresolved. File matches and term presence do not establish answer correctness.

This is one small corpus and a comparison against loading every note. Supplying only a known relevant note took 244–1,609 tokens per question here, so the experiment does not establish an advantage over manual context selection or other retrieval systems. The percentages are not guaranteed savings for other projects, measured reasoning improvements, or an increase in context-window capacity.

Quick start

Requires Node.js 22.12 or later and Git. This initial release is distributed through GitHub; there is no claim of an npm registry release.

git clone https://github.com/OzgurH/project-vault-mcp.git
cd project-vault-mcp
npm ci
npm run build

Preview a knowledge layer in a project directory:

node dist/src/cli.js init --root ../my-project

Create the missing starter files when the preview looks right:

node dist/src/cli.js init --root ../my-project --apply
node dist/src/cli.js check --root ../my-project

The initializer preserves existing files. If a configuration already exists, it leaves that configured project alone.

my-project/
├── project-vault.json
└── docs/
    ├── index.md
    ├── architecture/overview.md
    ├── modules/index.md
    ├── decisions/index.md
    └── runbooks/index.md

Already have notes? Add a configuration pointing at them; no conversion is required. See configuration.

Download project-vault-mcp-0.2.0.tgz from the GitHub release, then:

npm install --global ./project-vault-mcp-0.2.0.tgz
project-vault --help
project-vault init --root ../my-project --apply

The release package includes compiled JavaScript. You do not need TypeScript to run it. Use a pinned release asset rather than an unverified package with a similar registry name.

Connect your agent

Print a client configuration using your actual Node and CLI paths:

node dist/src/cli.js client-config --root /absolute/path/to/my-project

For clients that accept an mcpServers configuration:

{
  "mcpServers": {
    "project-vault": {
      "command": "node",
      "args": [
        "/absolute/path/to/project-vault-mcp/dist/src/cli.js",
        "serve",
        "--root",
        "/absolute/path/to/my-project"
      ]
    }
  }
}

Use absolute paths, especially when a desktop app starts the server from another directory. On Windows, JSON backslashes must be escaped; forward-slash paths such as D:/Projects/my-project also work.

For Codex, the equivalent server entry is:

[mcp_servers.project_vault]
command = "node"
args = ["/absolute/path/to/project-vault-mcp/dist/src/cli.js", "serve", "--root", "/absolute/path/to/my-project"]

These are configuration examples. Automated acceptance uses the official MCP SDK client; individual desktop-client versions are not all certified. Each client starts its own server process and each process serves one configured project.

MCP tools

Note IDs are explicit: docs/architecture/overview.md means root ID docs and the relative file architecture/overview.md. It is not an unrestricted filesystem path.

Useful prompts for your agent:

“Find the architecture notes for authentication and show the decisions and source references.”

“Read the current module note, then preview an update describing this refactor.”

“Create an ADR for this decision and link it from the architecture overview.”

Creating and updating notes

Reading is the default. To expose mutation tools, enable both gates:

1. Set "allowWrites": true in the project's configuration.

2. Start serve with --allow-write in the MCP client's argument list.

Tools preview changes unless the caller supplies "apply": true.

{
  "note_id": "docs/decisions/0001-cache-strategy.md",
  "content": "---\ntype: adr\nstatus: proposed\n---\n# Cache strategy\n\n## Context\n\nDescribe the problem.\n\n## Decision\n\nDescribe the choice and tradeoffs.\n",
  "apply": true
}

For an update, first call read_note, then pass its diskRevision as expected_revision. A stale revision returns a conflict. The server does not silently retry an update against newer content.

Updates preserve the existing UTF-8 BOM and newline style. Cooperating server processes serialize writes; existing files are replaced atomically. Creation refuses an existing target. There are no delete, move, arbitrary shell, or source-code editing tools.

Editor concurrency has limits. Obsidian and other editors do not participate in the server's locks. Revision checks detect changes observed before the final write check; they cannot prevent an editor from saving an old buffer later, or eliminate every filesystem race. Keep important notes in version control. See the security model.

A maintainable knowledge workflow

1. Retrieve the relevant architecture and decision notes before a change.

2. Implement using your normal coding workflow.

3. Preview note updates and include the reasoning, boundaries, and source references.

4. Apply updates with current revisions, then review the diff.

5. Check links and declared source hashes before committing code and notes together.

node dist/src/cli.js check --root ../my-project --json

The checker reports structural/evidence problems. It cannot prove that a design is correct, code is deployed, or runtime behavior matches a historical note.

How it fits together

flowchart LR
    A[Your MCP client] <-->|stdio| B[Project Vault MCP]
    B --> C[Path policy + write gates]
    C <--> D[Markdown notes]
    D <--> E[Obsidian / editor / Git]
    B --> F[Search + links + context]
    F --> D
    B --> G[Optional source-hash checks]
    G --> H[Explicitly allowed source files]

No HTTP port. No required Obsidian plugin. No database to migrate. No embedding service to configure.

Documentation

• Architecture and boundaries

• Configuration and limits

• Example knowledge layer

• Security model and disclosure

• OWASP 2025 and zero-trust control map

• Privacy, GDPR and KVKK responsibilities

• Threat model

• Security operations and retention

• Contributing and development

• Design decisions

Development

npm ci
npm run check
npm pack

Behavioral tests cover filesystem boundaries, revisions, Markdown parsing, search, links, CLI behavior, and MCP integration. CI runs on Windows, Linux, and macOS with Node 22 and 24. A green workflow is the evidence for that specific revision, not a guarantee for every filesystem or MCP host.

Roadmap

• Optional code-intelligence adapters.

• Semantic retrieval as an opt-in addition to deterministic search.

• More architecture templates and language-neutral maintenance recipes.

• npm registry distribution.

The initial scope intentionally keeps code analysis, remote access, and model inference outside the server. See the design for the full boundary.

License

MIT. Built with the official MCP TypeScript SDK.

Independent project. Not affiliated with Obsidian, Anthropic, OpenAI, or any MCP client vendor.