@blacksmithers/vaultforge 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solutions Forge LTDA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,464 @@
+<p align="center">
+  <img src="assets/vaultforge-logo.svg" alt="VaultForge" width="420" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@blacksmithers/vaultforge"><img src="https://img.shields.io/npm/v/@blacksmithers/vaultforge.svg" alt="npm version" /></a>
+  <a href="https://github.com/blacksmithers/vaultforge/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="node version" /></a>
+  <a href="https://github.com/blacksmithers/vaultforge/actions"><img src="https://github.com/blacksmithers/vaultforge/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+</p>
+
+<h3 align="center">The most capable MCP server for Obsidian.</h3>
+
+<p align="center">
+  <strong>27 tools</strong> · Canvas with auto-layout · BM25 smart search · Vault intelligence<br/>
+  No Obsidian plugin required · Works on macOS, Linux, Windows
+</p>
+
+<p align="center">
+  <a href="#canvas-tools">Canvas</a> ·
+  <a href="#smart-search">Search</a> ·
+  <a href="#vault-intelligence">Intelligence</a> ·
+  <a href="#all-tools">All 27 Tools</a> ·
+  <a href="#quick-start">Quick Start</a>
+</p>
+
+---
+
+## 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.
+
+| Feature | VaultForge | mcp-obsidian | mcpvault | obsidian-mcp-server |
+|---------|:-:|:-:|:-:|:-:|
+| Read / Write / Delete notes | ✅ | ✅ | ✅ | ✅ |
+| Full-text search | ✅ | ✅ | ✅ | ✅ |
+| Edit in-place | ✅ | ❌ | ✅ | ❌ |
+| Batch operations | ✅ | ❌ | ❌ | ❌ |
+| Daily notes | ✅ | ❌ | ❌ | ✅ |
+| Vault stats | ✅ | ❌ | ✅ | ❌ |
+| **Canvas — create with auto-layout** | ✅ | ❌ | ❌ | ❌ |
+| **Canvas — semantic read** | ✅ | ❌ | ❌ | ❌ |
+| **Canvas — patch (add/remove/update)** | ✅ | ❌ | ❌ | ❌ |
+| **Canvas — re-layout (dagre)** | ✅ | ❌ | ❌ | ❌ |
+| **BM25 smart search (Orama)** | ✅ | ❌ | ❌ | ❌ |
+| **Vault theme mapping (TF-IDF)** | ✅ | ❌ | ❌ | ❌ |
+| **Vault reorganization engine** | ✅ | ❌ | ❌ | ❌ |
+| **Regex find-and-replace (grep-sub)** | ✅ | ❌ | ❌ | ❌ |
+| **Batch rename / move with link updates** | ✅ | ❌ | ❌ | ❌ |
+| **Backlink analysis** | ✅ | ❌ | ❌ | ❌ |
+| **Frontmatter as structured data** | ✅ | ❌ | ❌ | ❌ |
+| **Directory management (delete, prune)** | ✅ | ❌ | ❌ | ❌ |
+| No Obsidian plugin required | ✅ | ❌ | ✅ | ❌ |
+
+---
+
+## 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.
+
+| Operation | Traditional MCP | VaultForge | Savings |
+|---|---|---|---|
+| Read a canvas | Raw JSON — coordinates, hex IDs, pixel dimensions | Semantic graph: labels + connections only | ~70-80% fewer tokens |
+| Search vault | Unranked grep dump — agent reads 50 results to find 3 | BM25-ranked top results with relevance scores | ~90% fewer tokens |
+| Understand vault structure | Agent reads files one by one (N calls × M tokens each) | One `vault_themes()` call returns clustered map | ~95% fewer tokens |
+
+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](https://jsoncanvas.org/) files without touching a single coordinate. The agent describes a semantic graph. VaultForge calculates all geometry using [dagre](https://github.com/dagrejs/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](https://github.com/oramasearch/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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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)
+| Tool | What it does |
+|------|-------------|
+| `read_note` | Read content + metadata. Fuzzy path resolution. |
+| `write_note` | Create or overwrite. |
+| `edit_note` | In-place find and replace. Exact match, must be unique. |
+| `edit_regex` | Regex find-and-replace. Single file or grep-sub across vault. Capture groups, dry run. |
+| `append_note` | Append to existing, or create if missing. |
+| `delete_note` | Move to `.trash` (safe) or permanent. Optional `cleanup_empty_parents` removes empty parent dirs. |
+
+### Search & Discovery (8)
+| Tool | What it does |
+|------|-------------|
+| `smart_search` | **BM25-ranked.** Typo tolerance, field boosting, snippets. |
+| `search_reindex` | Force re-index after bulk operations. |
+| `search_vault` | Fast filename/path search from in-memory index. |
+| `search_content` | Full-text grep. For exact/literal matches. |
+| `list_dir` | Directory listing with created/modified timestamps. Sort by name, date, or size. |
+| `recent_notes` | Recently modified files. Instant from index. |
+| `daily_note` | Today's daily note (or any date). |
+| `vault_status` | File counts, types, index health. |
+
+### Files (3)
+| Tool | What it does |
+|------|-------------|
+| `batch_rename` | Rename/move files. Explicit pairs or regex patterns. Auto-updates wikilinks. Dry run default. |
+| `delete_folder` | Delete empty or non-empty directories. Moves to `.trash` by default. Safety guards for `.obsidian`, `.git`, `.trash`. |
+| `prune_empty_dirs` | Find and remove all empty directories. Dry run default. Bottom-up pruning handles cascading empty dirs. |
+
+### Links (2)
+| Tool | What it does |
+|------|-------------|
+| `update_links` | Update all wikilinks across vault after moving/renaming a file. Dry run default. |
+| `backlinks` | Find all files that link to a given file. Line numbers, context, embed detection. |
+
+### Metadata (1)
+| Tool | What it does |
+|------|-------------|
+| `frontmatter` | Read/write/merge YAML frontmatter as structured data. No string parsing needed. |
+
+### Canvas (4)
+| Tool | What it does |
+|------|-------------|
+| `canvas_create` | Semantic graph → auto-laid-out `.canvas` via dagre. |
+| `canvas_read` | Canvas → semantic graph (labels + connections, not coordinates). |
+| `canvas_patch` | Add/remove/update with relative positioning + fuzzy matching. |
+| `canvas_relayout` | Re-layout existing canvas. Preview before committing. |
+
+### Intelligence (2)
+| Tool | What it does |
+|------|-------------|
+| `vault_themes` | TF-IDF theme extraction + clustering. Vault atlas with cross-folder warnings. |
+| `vault_suggest` | Reorganization engine: consolidate, create MOCs, archive stale, triage orphans. |
+
+### Batch (1)
+| Tool | What it does |
+|------|-------------|
+| `batch` | Execute multiple operations — read, write, edit, regex, rename, frontmatter, delete. Delete ops support `cleanup_empty_parents`. |
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) v22+
+- A folder with Markdown files (Obsidian vault or any structure)
+
+**Obsidian app is not required.** VaultForge operates directly on the filesystem. If Obsidian is open, it picks up changes in real time.
+
+### Install
+
+```bash
+npm install -g @blacksmithers/vaultforge
+```
+
+### Configure
+
+**Claude Desktop** — edit `claude_desktop_config.json`:
+
+| OS | Config file location |
+|----|---------------------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+> **Tip (Windows):** press `Win+R`, paste `%APPDATA%\Claude`, hit Enter. The folder opens directly.
+
+macOS / Linux:
+```json
+{
+  "mcpServers": {
+    "vaultforge": {
+      "command": "vaultforge",
+      "args": ["/Users/you/Documents/MyVault"]
+    }
+  }
+}
+```
+
+Windows:
+```json
+{
+  "mcpServers": {
+    "vaultforge": {
+      "command": "vaultforge",
+      "args": ["C:\\Users\\you\\Documents\\MyVault"]
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add vaultforge -- vaultforge /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:
+
+| Package | Purpose | Size |
+|---------|---------|------|
+| [`@dagrejs/dagre`](https://github.com/dagrejs/dagre) | Sugiyama graph layout | ~15KB |
+| [`@orama/orama`](https://github.com/oramasearch/orama) | BM25 search engine | ~2KB core |
+
+### 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](https://blacksmithers.dev) — The movement
+- 🐦 [@gabgforge](https://x.com/gabgforge) — Engineer · Founder · Blacksmither
+- 💬 [GitHub Discussions](https://github.com/orgs/blacksmithers/discussions) — Ideas, feedback, show & tell
+
+### License
+
+[MIT](LICENSE) — [Solutions Forge LTDA](https://solutionsforge.tech)
+
+---
+
+<p align="center">
+  <strong>Stop automating spreadsheets. Start forging.</strong>
+</p>

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}