VaultForge

The Problem with Every Other Obsidian MCP

I checked them all — mcp-obsidian, mcpvault, obsidian-mcp-server, obsidian-mcp-tools, obsidian-mcp-plugin. They read files. They write files. Some search. That's it.

None of them can create a visual diagram. None of them rank search results by relevance. None of them can tell an agent "here are the 12 themes in this vault and which files belong to which."

VaultForge does all three.

Fewer Tokens. Same Intelligence.

The other Obsidian MCPs weren't designed for AI agents — they were designed for humans who happen to use AI. Every tool returns raw, verbose data that burns through context windows. VaultForge is AI-infrastructure: every response is shaped to minimize token consumption while maximizing semantic density.

Tokens = API cost, context window space, and latency. Fewer tokens means faster, cheaper, smarter agents.

Three Things No Other MCP Can Do

🎨 Canvas Tools

The agent thinks in graphs. The tool thinks in pixels.

AI agents create, read, modify, and re-layout JSON Canvas files without touching a single coordinate. The agent describes a semantic graph. VaultForge calculates all geometry using dagre — the same Sugiyama layout engine behind Mermaid and React Flow.

canvas_create — describe nodes and edges, get a fully laid-out .canvas file:

Agent sends:                              Obsidian renders:
                                          
  nodes:                                  ┌───────────┐
    - API Gateway                         │    API    │───┐
    - Auth Service                        │  Gateway  │   │
    - Database                            └───────────┘   │
    - Cache                               ┌───────────┐   │   ┌───────────┐
  edges:                                  │   Auth    │───┼──▶│ Database  │
    - API Gateway → Auth Service          │  Service  │   │   └───────────┘
    - API Gateway → Cache                 └───────────┘   │
    - Auth Service → Database                             │   ┌───────────┐
    - Cache → Database                                    └──▶│   Cache   │
  layout: { direction: "LR" }                                 └───────────┘

canvas_read — semantic graph, not raw JSON:

Instead of:  {"id":"231bf38f","x":-635,"y":-420,"width":250,"height":70,...}
Agent gets:  { label: "AXON", connections: ["Strategy", "AWS", "Resistance"] }

A typical canvas with 15 nodes returns ~200 tokens as a semantic graph vs ~2,000+ tokens as raw JSON Canvas. The agent gets the same information at 10% of the cost.

canvas_patch — modify with relative positioning:

add_nodes: [{ label: "New Module", near: "API Gateway", position: "below" }]
remove_nodes: ["Deprecated Service"]  →  cascade-removes all connected edges

canvas_relayout — fix a messy canvas with one call. Preview before committing.

🔍 Smart Search

Not grep. Elasticsearch-grade.

Orama BM25-ranked search with typo tolerance, stemming (26 languages), and field boosting. No ML, no API keys, no internet.

smart_search("stripe webhook")

  → Stripe-Webhooks.md             score: 0.92
    "...webhook endpoint configuration for handling Stripe events..."
  
  → Refactor-Prompts.md            score: 0.61
    "...refactor the Stripe integration to use webhook signatures..."

vs search_content("stripe webhook")
  → Returns EVERY file containing "stripe", unranked, no scoring

Unranked grep forces the agent to consume every result to find relevance. BM25 puts the answer at the top. Fewer results read = fewer tokens burned = faster, cheaper responses.

Field boosting: title (3×) > tags (2.5×) > headings (2×) > content (1×).

Persistent index at .vaultforge/search-index.json — survives restarts.

🧠 Vault Intelligence

Your vault has folders. Now it has a map.

Files land where the energy of the moment puts them. Themes bleed across folders — "SpecForge" ends up in Projetos/, AI/prompts/, Content/, and Empresas/. Nobody maintains a perfect taxonomy.

vault_themes — scans every file, extracts distinctive terms via TF-IDF, clusters by similarity:

{
  "themes": [
    {
      "label": "SpecForge Frontend",
      "key_terms": ["impl", "dashboard", "widget"],
      "files": 12,
      "folders": ["32-AI/prompts/specforge"],
      "coherence": 0.89
    },
    {
      "label": "Content Strategy",
      "files": 6,
      "folders": ["80-Content", "70-Empresas"],
      "cross_folder": true
    }
  ],
  "orphans": 5,
  "cross_folder_warnings": 3
}

Without this, an agent needs to read_note on every file individually to understand vault structure — hundreds of tool calls, thousands of tokens. One vault_themes() call replaces all of them.

vault_suggest — actionable reorganization from the atlas:

{
  "suggestions": [
    { "type": "consolidate", "action": "Move Launch-Strategy.md → 80-Content/" },
    { "type": "create_moc", "action": "Create MOC-SpecForge-Frontend.md linking 12 files" },
    { "type": "archive", "action": "Move 8 stale files to 90-Archive/" }
  ]
}

The full workflow:

"Organize my vault"
  → vault_themes()      maps 179 files into 15 themes
  → vault_suggest()     generates 20 reorganization actions  
  → human approves      "do it, skip the archive stuff"
  → batch execution     moves files, creates MOCs
  → canvas_create()     visual theme map in Obsidian

The vault maps itself.

All Tools

Notes (6)

Search & Discovery (8)

Files (3)

Links (2)

Metadata (1)

Canvas (4)

Intelligence (2)

Batch (1)

Install

Prerequisites

• A folder with Markdown files (Obsidian vault or any structure)

• One of: Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, or any MCP-compatible client

• Node.js v22+ (not required for .mcpb one-click install)

Obsidian app is not required. VaultForge operates directly on the filesystem. If Obsidian is open, it picks up changes in real time.

Claude Desktop (one-click)

Windows — ⬇ Download vaultforge.mcpb — open the file, enter your vault path, done.

macOS:

curl -fsSL https://github.com/blacksmithers/vaultforge/releases/latest/download/vaultforge.mcpb -o /tmp/vaultforge.mcpb && open /tmp/vaultforge.mcpb

Linux:

curl -fsSL https://github.com/blacksmithers/vaultforge/releases/latest/download/vaultforge.mcpb -o /tmp/vaultforge.mcpb && xdg-open /tmp/vaultforge.mcpb

Claude Code

claude mcp add vaultforge -- npx -y @blacksmithers/vaultforge /path/to/your/vault

VS Code / Cursor / Windsurf

Add to your MCP settings JSON (.vscode/mcp.json, .cursor/mcp.json, or equivalent):

{
  "servers": {
    "vaultforge": {
      "command": "npx",
      "args": ["-y", "@blacksmithers/vaultforge", "/path/to/your/vault"]
    }
  }
}

Any MCP client

Use this universal pattern — any client that supports MCP stdio transport will work:

• Command: npx

• Args: ["-y", "@blacksmithers/vaultforge", "/path/to/your/vault"]

npm install -g @blacksmithers/vaultforge

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "vaultforge": {
      "command": "vaultforge",
      "args": ["/path/to/your/vault"]
    }
  }
}

Verify

Ask your AI assistant: "List the files in my vault" — if it responds with your vault contents, you're connected.

Under the Hood

Three Engines, One Index

@orama/orama (BM25 index — single source of truth)
  ├── smart_search      query-driven    "find files about X"
  ├── vault_themes      corpus-driven   "what themes exist?"
  └── vault_suggest     action-driven   "how should I reorganize?"

@dagrejs/dagre (Sugiyama graph layout)
  ├── canvas_create     semantic graph → positioned canvas
  ├── canvas_patch      relative edits → absolute coordinates
  └── canvas_relayout   messy canvas → optimized layout

Wikilink engine (zero dependencies)
  ├── update_links      safe moves with automatic link repair
  ├── backlinks         impact analysis before moves/deletes
  └── batch_rename      rename + link update in one operation

Dependencies

Two packages. Both MIT, TypeScript-native, zero sub-dependencies:

Architecture

src/
├── tools/
│   ├── notes/                  read, write, edit, edit_regex, append, delete
│   │   └── edit-regex.ts             regex find-and-replace
│   ├── files/                  rename, move, directory management
│   │   ├── batch-rename.ts           rename/move with link updates
│   │   ├── delete-folder.ts          delete directories with safety guards
│   │   └── prune-empty-dirs.ts       find and remove empty directories
│   ├── links/                  wikilink management
│   │   ├── link-utils.ts             shared wikilink regex engine
│   │   ├── update-links.ts           fix links after moves
│   │   └── backlinks.ts              impact analysis
│   ├── metadata/               frontmatter operations
│   │   └── frontmatter.ts            read/write/merge YAML frontmatter
│   ├── search/                 search_vault, search_content, list_dir, recent, daily, status
│   │   ├── smart-search.ts           BM25 search via Orama
│   │   ├── search-reindex.ts         full/incremental re-index
│   │   ├── orama-engine.ts           Orama wrapper + persistence
│   │   └── markdown-parser.ts        strip md, extract frontmatter/headings
│   ├── intelligence/           vault analysis + reorganization
│   │   ├── vault-themes.ts           TF-IDF extraction + clustering
│   │   └── vault-suggest.ts          suggestions + batch execution
│   ├── canvas/                 JSON Canvas (jsoncanvas.org spec v1.0)
│   │   ├── canvas-create.ts
│   │   ├── canvas-read.ts
│   │   ├── canvas-patch.ts
│   │   ├── canvas-relayout.ts
│   │   ├── layout-engine.ts          dagre wrapper + edge side calc
│   │   ├── canvas-utils.ts           ID gen, text height, fuzzy match
│   │   └── types.ts
│   └── batch/                  multi-operation execution

Roadmap

What's coming next. Ordered by priority — community input shapes the sequence.

v0.6.0 — Vault Graph & Tags

• vault_graph — Export the vault's link graph as a JSON adjacency list. Nodes = files, edges = wikilinks. Enables agents to reason about knowledge structure, find clusters, detect orphans, and identify bridge notes. Output compatible with D3, Cytoscape, or canvas_create for visual rendering.

• tag_search — Search by YAML frontmatter tags, separate from content search. Filter by tag combinations (tag:draft AND tag:specforge). Returns files with matching tags plus their frontmatter metadata.

• diff_note — Compare two notes (or two versions of the same note) and return a structured diff. Useful for agents reviewing changes, merging edits, or auditing vault history.

v0.7.0 — Template Engine & Smart Create

• template_create — Create notes from templates with variable substitution ({{date}}, {{title}}, {{tags}}). Supports custom template folders. The agent describes intent, the tool handles boilerplate.

• smart_create — AI-aware note creation. Analyzes vault themes and suggests optimal location, tags, and links for new notes. "Write about X" → creates the note in the right folder with relevant backlinks.

v0.8.0 — Performance at Scale

• Large vault optimization (10k+ files) — incremental indexing, lazy loading, memory-mapped file access

• Parallel batch operations where order independence allows

• Index compression for faster startup on large vaults

• Benchmark suite with reproducible performance targets

v1.0.0 — Stability & Ecosystem

• Comprehensive test suite with >90% coverage

• Stable API — no breaking changes without major version bump

• Plugin ecosystem hooks — allow community extensions

• Published to MCP registry

• Obsidian community plugin (optional companion for enhanced integration)

Community-Driven

Open an issue tagged roadmap to propose features. The most-requested items move up the queue. This is an open forge — the community shapes the steel.

The Forge is Open

VaultForge is the first open-source tool from the Blacksmithers — a community of builders who forge tools that build things.

We don't wrap APIs and call it innovation. We build real engines — BM25 search, graph layout, TF-IDF clustering — because the tools AI agents use should be as rigorous as the agents themselves.

If that resonates, you're already one of us.

Contributing

Open an issue first to discuss changes. PRs welcome — especially for:

• Semantic similarity search (embedding-based, complementing BM25)

• Canvas layout algorithms beyond Sugiyama (force-directed, circular)

• Performance improvements for large vaults (10k+ files)

• Windows-specific edge cases and path handling

• New language stemmers for smart search

Community

• 🔨 blacksmithers.dev — The movement

• 🐦 @gabgforge — Engineer · Founder · Blacksmither

• 💬 GitHub Discussions — Ideas, feedback, show & tell

License

MIT — Solutions Forge LTDA