使用说明

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是 人工智能基础设施：每个响应的形状都是为了最大限度地减少令牌消耗，同时最大限度地提高语义密度。

操作	传统MCP	VaultForge	节省
读取画布	原始JSON——坐标、十六进制ID、像素尺寸	语义图：仅标签+连接	令牌减少约70-80%
搜索库	未排名的grep转储——代理读取50个结果，找到3个	BM25排名靠前的结果，相关性得分	~90%的令牌减少
了解保管库结构	代理逐一读取文件（N次调用×每次M个令牌）	一个 `vault_themes()` 调用返回聚集映射	令牌减少约95%

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

其他MCP无法做到的三件事

🎨 画布工具

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

AI代理创建、读取、修改和重新布局 JSON画布文件，而无需触摸单个坐标。代理描述语义图。VaultForge使用以下公式计算所有几何图形达格 --Mermaid和React Flow背后的杉山布局引擎。

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）

工具	它做什么
`read_note`	读取内容+元数据。模糊路径分辨率。
`write_note`	创建或覆盖。
`edit_note`	就地查找并更换。完全匹配，必须是唯一的。
`edit_regex`	正则表达式查找并替换。跨vault的单个文件或grep子文件。捕捉群体，进行模拟训练。
`append_note`	附加到现有的，如果缺少，则创建。
`delete_note`	移动到 `.trash` （安全）或永久。可选的 `cleanup_empty_parents` 删除空父目录。

搜索与发现（8）

工具	它做什么
`smart_search`	BM25排名。拼写错误容忍度，字段增强，片段。
`search_reindex`	批量操作后强制重新索引。
`search_vault`	从内存索引中快速搜索文件名/路径。
`search_content`	全文grep。用于精确/字面匹配。
`list_dir`	带有创建/修改时间戳的目录列表。按名称、日期或大小排序。
`recent_notes`	最近修改的文件。立即从索引。
`daily_note`	今天的日记（或任何日期）。
`vault_status`	文件计数、类型、索引运行状况。

文件（3）

工具	它做什么
`batch_rename`	重命名/移动文件。显式配对或正则表达式模式。自动更新维基链接。干运行默认值。
`delete_folder`	删除空目录或非空目录。移动到 `.trash` 默认情况下。安全防护装置 `.obsidian`, `.git`, `.trash`.
`prune_empty_dirs`	查找并删除所有空目录。干运行默认值。自下而上的修剪处理级联的空dirs。

链接（2）

工具	它做什么
`update_links`	移动/重命名文件后，更新vault中的所有维基链接。干运行默认值。
`backlinks`	查找链接到给定文件的所有文件。行号、上下文、嵌入检测。

元数据（1）

工具	它做什么
`frontmatter`	将YAML frontmatter作为结构化数据进行读/写/合并。不需要字符串解析。

帆布（4）

工具	它做什么
`canvas_create`	语义图→ 汽车布局 `.canvas` 经过几天。
`canvas_read`	帆布→ 语义图（标签+连接，而不是坐标）。
`canvas_patch`	添加/删除/更新相对定位+模糊匹配。
`canvas_relayout`	重新布局现有画布。提交前预览。

情报（2）

工具	它做什么
`vault_themes`	TF-IDF主题提取+聚类。带有跨文件夹警告的Vault图集。
`vault_suggest`	重组引擎：整合、创建MOC、存档过时、分流孤儿。

批次（1）

工具	它做什么
`batch`	执行多个操作——读、写、编辑、正则表达式、重命名、frontmatter、删除。删除操作支持 `cleanup_empty_parents`.

安装

先决条件

一个包含Markdown文件的文件夹（黑曜石保险库或任何结构）
什么之中的一个：克劳德桌面版, 克劳德代码, VS Code, 光标, 帆板运动，或任何与MCP兼容的客户端
Node.js 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:

操作系统	配置文件位置
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
窗户	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/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，零子依赖：

包装	用途	尺寸
`@dagrejs/dagre`	杉山图形布局	~15KB
`@orama/orama`	BM25搜索引擎	~2KB核心

建筑

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 --工程师·创始人·铁匠
💬 GitHub讨论 --想法、反馈、展示和讲述

许可证

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

Stop automating spreadsheets. Start forging.