Obsidian Forge MCP

The most capable MCP server for Obsidian.

27 tools · Canvas with auto-layout · BM25 smart search · Vault intelligence

No Obsidian plugin required · Works on macOS, Linux, Windows

Canvas · Search · Intelligence · All 27 Tools · Install

______________________________________________________________________

其他黑曜石MCP的问题

我检查了它们——mcp黑曜石、mcpvault、黑曜岩mcp服务器、黑曜岩mcp工具、黑曜石mcp插件。他们阅读文件。他们写文件。一些搜索。就这样

他们都无法创建可视化图表。它们都没有按相关性对搜索结果进行排名。他们都不能告诉特工 *“以下是此保管库中的12个主题以及哪些文件属于哪些主题。”*

VaultForge做到了这三点。

|功能| VaultForge | mcp黑曜石| mcpvault |黑曜岩mcp服务器| |---------|:-:|:-:|:-:|:-:| |读/写/删除笔记|✅ | ✅ | ✅ | ✅ | |全文搜索|✅ | ✅ | ✅ | ✅ | |就地编辑|✅ | ❌ | ✅ | ❌ | |批量操作|✅ | ❌ | ❌ | ❌ | |每日笔记|✅ | ❌ | ❌ | ✅ | |保险库统计信息|✅ | ❌ | ✅ | ❌ | | 画布——使用自动布局创建 | ✅ | ❌ | ❌ | ❌ | | Canvas——语义阅读 | ✅ | ❌ | ❌ | ❌ | | 画布--补丁（添加/删除/更新） | ✅ | ❌ | ❌ | ❌ | | 画布--重新布局（dagre） | ✅ | ❌ | ❌ | ❌ | | BM25智能搜索（Orama） | ✅ | ❌ | ❌ | ❌ | | 保险库主题映射（TF-IDF） | ✅ | ❌ | ❌ | ❌ | | 保险库重组引擎 | ✅ | ❌ | ❌ | ❌ | | 正则表达式查找和替换（grep-sub） | ✅ | ❌ | ❌ | ❌ | | 批量重命名/移动链接更新 | ✅ | ❌ | ❌ | ❌ | | 反向链接分析 | ✅ | ❌ | ❌ | ❌ | | Frontmatter作为结构化数据 | ✅ | ❌ | ❌ | ❌ | | 目录管理（删除、修剪） | ✅ | ❌ | ❌ | ❌ | |不需要黑曜石插件|✅ | ❌ | ✅ | ❌ |

______________________________________________________________________

更少的代币。同样的情报。

其他黑曜石MCP不是为人工智能代理设计的，而是为碰巧使用人工智能的人设计的。每个工具都会返回原始、冗长的数据，这些数据会在上下文窗口中燃烧。VaultForge是 人工智能基础设施：每个响应的形状都是为了最大限度地减少令牌消耗，同时最大限度地提高语义密度。

令牌=API成本、上下文窗口空间和延迟。更少的代币意味着更快、更便宜、更智能的代理。

______________________________________________________________________

其他MCP无法做到的三件事

🎨 画布工具

代理人用图形思考。该工具以像素为单位进行思考。

canvas_create --描述节点和边，得到一个完整的布局 .canvas 文件：

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 --语义图，而不是原始JSON：

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

一个具有15个节点的典型画布返回约200个令牌作为语义图，而原始JSON画布返回约2000多个令牌。代理人以10%的成本获得相同的信息。

canvas_patch --使用相对定位进行修改：

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

canvas_relayout --只需一次调用，即可修复杂乱的画布。提交前预览。

______________________________________________________________________

🔍 智能搜索

不是grep。Elasticsearch等级。

奥拉马 BM25根据拼写容忍度、词干（26种语言）和字段增强对搜索进行了排名。没有ML，没有API密钥，没有互联网。

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

未排序的grep迫使代理使用每个结果来查找相关性。BM25将答案放在首位。读取的结果更少=销毁的令牌更少=更快、更便宜的响应。

现场增压： 标题（3×）>标签（2.5×）>标题（2×）>内容（1×）。

持久索引 在 .vaultforge/search-index.json --重新启动后幸存下来。

______________________________________________________________________

🧠 保险库智能

您的保管库中有文件夹。现在它有一张地图。

文件降落在当下的能量所在之处。主题在文件夹中渗透——“SpecForge”最终出现在 Projetos/, AI/prompts/, Content/，以及 Empresas/没有人能保持完美的分类。

vault_themes --扫描每个文件，通过TF-IDF提取独特的术语，按相似性进行聚类：

{
  "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
}

如果没有这个，代理需要 read_note 对每个文件进行单独处理，以了解vault结构——数百个工具调用，数千个令牌。一 vault_themes() call取代了所有这些。

vault_建议 --从图集中进行可操作的重组：

{
  "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/" }
  ]
}

完整的工作流程：

"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

保险库会自动绘制地图。

______________________________________________________________________

所有工具

注释（6）

搜索与发现（8）

文件（3）

链接（2）

元数据（1）

帆布（4）

情报（2）

批次（1）

______________________________________________________________________

安装

先决条件

• 一个包含Markdown文件的文件夹（黑曜石保险库或任何结构）
• v22+（不需要 .mcpb 一键安装）

黑曜石应用程序不是必需的。 VaultForge直接在文件系统上运行。如果黑曜石是开放的，它会实时捕捉变化。

克劳德桌面（一键）

视窗 — ⬇ 下载vaultforge.mcpb --打开文件，输入vault路径，完成。

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 mcp add vaultforge -- npx -y @blacksmithers/vaultforge /path/to/your/vault

VS代码/光标/风帆

添加到MCP设置JSON(.vscode/mcp.json, .cursor/mcp.json或同等）：

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

任何MCP客户端

使用这种通用模式——任何支持MCP stdio传输的客户端都可以工作：

• 命令： npx
• Args： ["-y", "@blacksmithers/vaultforge", "/path/to/your/vault"]

Global install + manual Claude Desktop config

npm install -g @blacksmithers/vaultforge

编辑 claude_desktop_config.json:

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

验证

问你的AI助手： *“列出我保管库中的文件”* --如果它以您的vault内容作为响应，则表示您已连接。

______________________________________________________________________

幕后

三个引擎，一个索引

@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

依赖项

两个包裹。麻省理工学院，原生TypeScript，零子依赖：

建筑

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

______________________________________________________________________

路线图

接下来会发生什么。按优先级排序——社区的意见决定了顺序。

v0.6.0--保险库图形和标签

• vault_graph --将vault的链接图导出为JSON邻接列表。节点=文件，边=维基链接。使代理能够推理知识结构、查找集群、检测孤儿和识别桥接笔记。输出与D3、Cytoscape或canvas_create兼容，用于视觉渲染。
• tag_search --通过YAML frontmatter标签进行搜索，与内容搜索分开。按标签组合筛选(tag:draft AND tag:specforge).返回具有匹配标签的文件及其frontmatter元数据。
• diff_note --比较两个注释（或同一注释的两个版本）并返回结构化差异。这对代理检查更改、合并编辑或审核vault历史非常有用。

v0.7.0——模板引擎和智能创建

• template_create --使用变量替换从模板创建注释({{date}}, {{title}}, {{tags}}).支持自定义模板文件夹。代理描述意图，工具处理样板。
• smart_create --AI感知笔记创建。分析vault主题，并为新笔记建议最佳位置、标签和链接。“写X”→ 在右侧文件夹中创建带有相关反向链接的笔记。

v0.8.0--规模性能

• 大型vault优化（10k+文件）——增量索引、延迟加载、内存映射文件访问
• 允许订单独立性的并行批处理操作
• 索引压缩可加快大型Vault的启动速度
• 具有可重复性能目标的基准套件

v1.0.0——稳定性和生态系统

• 覆盖率超过90%的全面测试套件
• 稳定的API-在没有重大版本冲突的情况下没有突破性的变化
• 插件生态系统挂钩——允许社区扩展
• 发布到MCP注册表
• 黑曜石社区插件（增强集成的可选伴侣）

社区驱动

打开一个标记为的问题 roadmap 提出特征。请求最多的项目会向上移动队列。这是一个开放的锻造厂——社区塑造钢铁。

______________________________________________________________________

锻造厂是开放的

VaultForge是第一个开源工具 铁匠 --一个由制造工具的建设者组成的社区。

我们不会包装API并称之为创新。我们构建真正的引擎——BM25搜索、图布局、TF-IDF聚类——因为AI代理使用的工具应该和代理本身一样严格。

如果这引起了共鸣，那么你已经是我们中的一员了。

贡献

先打开一个问题来讨论更改。欢迎公关，尤其是：

• 语义相似性搜索（基于嵌入，补充BM25）
• 杉山以外的画布布局算法（力定向、圆形）
• 大型保管库（10k+文件）的性能改进
• Windows特定的边缘情况和路径处理
• 用于智能搜索的新语言词干分析器

社区

• 🔨 铁匠.dev --运动
• 🐦 @gabgforge --工程师·创始人·铁匠
• 💬 --想法、反馈、展示和讲述

许可证

麻省理工学院 — 解决方案锻造LTDA

______________________________________________________________________

Stop automating spreadsheets. Start forging.