vault-graph-mcp

MCP server that exposes a markdown vault as a traversable knowledge graph via NetworkX. Runs on Windows, macOS, Linux — zero compilation, just uv or pip.

What it does

• Walks your vault, parses [[wikilinks]] AND [text](path.md) links

• Builds a directed NetworkX graph with typed edges (wikilink, mdlink, backlink, implicit)

• Implicit edges: Uses sentence-transformers embeddings to find semantically similar notes that were NEVER explicitly linked — the author's blind spots become visible

• Exposes 9 MCP tools for AI agents:

Related MCP server: mcp-vault-reader

Quick Start (Windows)

1. Install uv (if you don't have it)

winget install --id=astral-sh.uv

2. Clone the repo

git clone https://github.com/ReneRichartz/vault-graph-mcp.git
cd vault-graph-mcp

3. Install

pip install -e .

Or with uv (recommended):

uv pip install -e .

4. VS Code MCP Configuration

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "vault-graph": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "C:\\Users\\rene\\vault-graph-mcp",
        "vault-graph-mcp"
      ],
      "env": {
        "VAULT_GRAPH_PATH": "C:\\Users\\rene\\mein-fscm-vault",
        "VAULT_IMPLICIT_THRESHOLD": "0.35"
      }
    }
  }
}

Alternatively, if installed via pip:

{
  "servers": {
    "vault-graph": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "vault_graph_mcp.server"],
      "env": {
        "VAULT_GRAPH_PATH": "C:\\Users\\rene\\mein-fscm-vault",
        "VAULT_IMPLICIT_THRESHOLD": "0.35"
      }
    }
  }
}

VS Code will auto-detect the server and offer to start it.

5. Use in VS Code Agent Chat

Switch to Agent Mode (Ctrl+Shift+I, then select "Agent") and ask:

"Search my vault for sales order entities and show me their dependencies."

"What notes link to the Pricing Engine?"

"Find the shortest path between Customer Master and Inventory Reservation."

"What notes are similar to my microbiome article — even if I never linked them?"

Environment Variables

Architecture

vault-graph-mcp/
├── pyproject.toml
└── src/vault_graph_mcp/
    ├── __init__.py
    ├── parser.py     # Link extraction: [[wikilinks]] + [text](path.md)
    ├── graph.py      # NetworkX builder (4 phases, incl. implicit)
    ├── implicit.py   # Semantic similarity via sentence-transformers
    └── server.py     # MCP server (9 tools)

Link Resolution

The resolver matches link targets to graph nodes in this order:

1. Exact match on node ID (relative path)

2. Case-insensitive match on node ID

3. Last component match (filename without extension)

4. Title match (from title: frontmatter or H1 heading)

5. Normalized match (dashes → spaces: sales-order-header ≈ "sales order header")

6. Substring match (target appears anywhere in node ID)

This means your Microsoft Learn-style [text](path.md) links resolve correctly without any conversion to wikilinks.

Implicit Edges

Phase 4 of the graph builder uses sentence-transformers/all-MiniLM-L6-v2 to embed every note and compute pairwise cosine similarity. Pairs above VAULT_IMPLICIT_THRESHOLD become bidirectional implicit edges with a weight attribute.

Example: In a vault with no links between "Schottland Mobile Home Parks" and "Golfplatz-Vergleich", the embedder finds them at sim=0.41 because both discuss Scottish locations — a connection the author never wrote down.

Tune the threshold:

• 0.30 — loose, finds more connections (good for exploration)

• 0.35 — default, balanced precision/recall

• 0.50 — strict, only strong thematic overlap

• 0 — disable implicit edges entirely