💡 Why this server?

TL;DR — One npx command. No running app. No plugins. No vector DB. Semantic search works out of the box.

✨ Features

🛠️ MCP Tools

All tool responses include contextual hints based on the current workflow state.

🚀 Quick Start

Prerequisites

• Node.js >= 22
• (Optional) Ollama for higher-quality embeddings

📦 Install from NPM

npm install -g @wirux/mcp-markdown-vault

Then run directly:

VAULT_PATH=/path/to/your/vault markdown-vault-mcp

🔌 MCP Client Configuration

Add to your MCP client config (e.g. Claude Desktop, Claude Code):

{
  "mcpServers": {
    "markdown-vault": {
      "command": "npx",
      "args": ["-y", "@wirux/mcp-markdown-vault"],
      "env": {
        "VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

npx -y auto-installs the package if not already present — no global install needed.

Try it in the browser: You can test this server directly at Glama Inspector — no local install required.

🐳 Docker

Pull the pre-built multi-arch image from GitHub Container Registry:

docker pull ghcr.io/wirux/mcp-markdown-vault:latest

Or use Docker Compose:

docker compose up

Edit docker-compose.yml to point at your markdown vault directory. The default compose file uses SSE transport on port 3000.

🛠️ Development (from source)

git clone https://github.com/wirux/mcp-markdown-vault.git
cd mcp-markdown-vault
npm install
npm run build
VAULT_PATH=/path/to/your/vault node dist/index.js

🌐 Transport Modes

SSE starts an HTTP server on PORT (default 3000):

• GET /sse — establishes an SSE stream (one per client)
• POST /messages?sessionId=... — receives JSON-RPC messages

MCP_TRANSPORT_TYPE=sse PORT=3000 VAULT_PATH=/path/to/vault npx @wirux/mcp-markdown-vault

Each SSE client gets its own workflow state. Shared resources (vault, vector index, embedder) are reused across all connections.

🧠 Embedding Providers

The server selects an embedding provider automatically:

No configuration needed for local embeddings — the model downloads on first use and is cached automatically.

⚙️ Configuration

Note: When using the default local vector store, a .markdown_vault_mcp directory will be created in your vault. It's recommended to add this directory to your .gitignore.

🏗️ Architecture

Clean Architecture with strict layer separation:

src/
├── domain/           🔷 Errors, interfaces (ports), value objects
├── use-cases/        🔶 Business logic (AST, chunking, search, workflow)
├── infrastructure/   🟢 Adapters (file system, Ollama, vector store)
└── presentation/     🟣 MCP tool bindings, transport layer (stdio/SSE)

See CLAUDE.md for detailed architecture docs and CHANGELOG.md for implementation history.

Self-Orienting Context Layer

When an MCP client connects, the server automatically provides vault context so connected agents can decide when to query this vault and how to use its tools — without explicit user instructions.

Making agents find your vault

In auto mode (the default), the server generates meta/overview.md automatically after startup using structural heuristics: top directories, file counts, tag frequency, and H1 headings. It also writes a one-line vault_scope field in the frontmatter, which is the host-visible description used for MCP handshake instructions, tool descriptions, and first-call priming.

In manual mode, you author meta/overview.md yourself. Set VAULT_CONTEXT_MODE=manual, edit the vault_scope frontmatter for the one-line host-visible description, and use the markdown body for richer narrative context:

{
  "mcpServers": {
    "markdown-vault": {
      "command": "npx",
      "args": ["-y", "@wirux/mcp-markdown-vault"],
      "env": {
        "VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

In both modes, meta/overview.md is the canonical source of vault description for connected agents: vault_scope in frontmatter supplies the short description, and the markdown body feeds the richer vault://overview resource.

How context is delivered

The server uses four complementary mechanisms so behavior degrades gracefully across clients with different MCP feature support:

Even if a client supports none of these (rare), the agent still discovers vault content through normal tool use.

Two files: contract vs overview

On first startup, the server creates two files in <VAULT_PATH>/meta/. In manual mode, both are created once and never overwritten — they are fully yours to edit. In auto mode, meta/overview.md is regenerated automatically after indexing completes and after every 5 meaningful file changes; its vault_scope frontmatter is refreshed at the same time. meta/contract.md is still created once and never overwritten.

meta/contract.md — Tool optimization (power users)

Tells agents how to use the vault's tools efficiently. Pre-filled with sensible defaults:

Most users don't need to edit this. Power users can customize it to match their vault's specific conventions — agents read it as part of the vault://overview resource.

Tip: Keep vault_scope short and specific — it is the one-line summary exposed to MCP hosts. Put richer, multi-line context in the body of meta/overview.md.

meta/overview.md — Vault description (read-side)

In auto mode: auto-generated after startup and refreshed after every 5 meaningful file changes. The frontmatter contains vault_scope, a generated one-line summary capped to a fixed maximum length for host-visible context. The body contains top directories, file counts, tag frequency, and recent note titles.

In manual mode: created as an editable stub. Set vault_scope in frontmatter to control the one-line host-visible description, then write whatever helps an agent understand your vault's content in the body: active projects, key topic areas, organizational philosophy.

Its frontmatter vault_scope is the primary source for handshake-visible one-line context, and its body is the primary source for the vault://overview resource that agents read on demand.

Hot reload behavior

Migration notes

On first run after upgrade, meta/contract.md and meta/overview.md are auto-created if missing. Existing files are never overwritten. No breaking changes to tool APIs.

If you have a meta/contract.md from other tooling with a different schema, review compatibility — the server-generated contract is dedicated to mcp-markdown-vault navigation hints.

🚢 CI/CD & Release

Fully automated via GitHub Actions and Semantic Release:

• Versioning follows Conventional Commits — feat: = minor, fix: = patch, feat!: / BREAKING CHANGE: = major
• Docker images are built for linux/amd64 and linux/arm64 via QEMU
• NPM package published as @wirux/mcp-markdown-vault
• Docker image available at ghcr.io/wirux/mcp-markdown-vault

🧪 Testing

568 tests across 49 files, written test-first (TDD).

npm test                                          # Run all tests
npx vitest run src/use-cases/ast-patcher.test.ts  # Single file
npm run test:watch                                # Watch mode
npm run test:coverage                             # Coverage report

Tests use real temp directories for file system operations and in-memory MCP transport for integration tests. No external services required.

🔒 Security

• 🛡️ All file paths validated through SafePath value object before any I/O
• 🚫 Blocks path traversal: ../, URL-encoded (%2e%2e), double-encoded (%252e), backslash, null bytes
• ✍️ Atomic file writes (temp file + rename) prevent partial writes
• 👤 Docker container runs as non-root user

📄 License

MIT