Vault Graph MCP

保险库图形MCP服务器

 ](package.json) 

🧠 基于人工智能的黑曜石金库知识图导航

用于黑曜石保险库图形导航和排名的MCP（模型上下文协议）服务器。为AI代理提供对知识图的结构化访问。

为什么选择Vault Graph MCP？

对于人工智能代理和个人知识管理：

• 🤖 为AI代理提供上下文感知访问 在不暴露原始文件内容的情况下，将黑曜石保险库
• 🔗 发现您不知道存在的连接 通过2跳关系分析
• 🎯 智能推荐 基于图结构，而不仅仅是关键字匹配
• 📊 确定知识中心 了解哪些概念是你思考的核心
• 🧭 语义导航 使用标签重叠和共享邻居关系
• ⚡ 快速缓存 -毫秒级查询，即使在大型金库（1000多张纸币）上也是如此

使用案例：

• 问Claude“在Kubernetes的这篇笔记之后，我接下来应该读什么？”
• 即使没有直接链接，也可以查找主题相关的笔记
• 在您的保险库中发现核心概念和知识集群
• 基于图拓扑获得AI支持的笔记推荐
• 通过自然语言查询探索您的知识图谱

特性

• 图形导航：遍历笔记之间的链接
• 排名推荐：根据共享邻居、程度和标签重叠获取相关笔记建议
• 中心发现：在您的保险库中查找核心概念
• 2-Hop相关：发现通过中间链接连接的笔记
• 搜索：按标题或标签查找笔记
• Loki兼容日志：结构化JSON日志可观察性

安装

npm install
npm run build

用法

1.通过.mcp.json（克劳德代码项目）

创建一个 .mcp.json 项目根目录中的文件。Claude Code在目录中启动时会自动加载此文件。

如果你的工作目录是黑曜石保险库，没有 VAULT_PATH 需要--服务器会从MCP根自动检测到它：

{
  "mcpServers": {
    "vault-graph": {
      "command": "node",
      "args": ["/path/to/vault-graph-mcp/dist/index.js"]
    }
  }
}

如果你的保险库在别处，set VAULT_PATH 明确地：

{
  "mcpServers": {
    "vault-graph": {
      "command": "node",
      "args": ["/path/to/vault-graph-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

注： .mcp.json 目前只有Claude Code支持。Gemini CLI使用 .gemini/settings.json Codex CLI使用 .codex/config.toml 项目级配置（见下文）。

2.通过Claude CLI

使用Claude CLI直接安装：

# Build the project first
npm run build

# Add the MCP server via CLI
claude mcp add --transport stdio \
  --env VAULT_PATH=/path/to/your/obsidian/vault \
  vault-graph -- node /path/to/vault-graph-mcp/dist/index.js

# List installed servers
claude mcp list

# Remove if needed
claude mcp remove vault-graph

注： 所有选项(--transport, --env, --scope)一定要来 之前 服务器名称。这 -- 将服务器名称与命令和参数分开。

看 Claude CLI MCP文档 了解更多详情。

3.使用克劳德桌面（全球）

添加到您的Claude Desktop配置中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vault-graph": {
      "command": "node",
      "args": ["/path/to/vault-graph-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

4.使用Gemini CLI

添加到您的Gemini CLI设置 ~/.gemini/settings.json:

{
  "mcpServers": {
    "vault-graph": {
      "command": "node",
      "args": ["/path/to/vault-graph-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

或者使用CLI：

gemini mcp add vault-graph -- node /path/to/vault-graph-mcp/dist/index.js

看 Gemini CLI MCP文档 了解更多详情。

5.使用Codex CLI（OpenAI）

添加到您的Codex配置 ~/.codex/config.toml:

[mcp_servers.vault-graph]
command = "node"
args = ["/path/to/vault-graph-mcp/dist/index.js"]

[mcp_servers.vault-graph.env]
VAULT_PATH = "/path/to/your/obsidian/vault"

或者使用CLI：

codex mcp add vault-graph --env VAULT_PATH=/path/to/your/obsidian/vault \
  -- node /path/to/vault-graph-mcp/dist/index.js

看 食品法典委员会MCP文件 了解更多详情。

6.独立

VAULT_PATH=/path/to/vault npm start

7.发展

VAULT_PATH=./test/vault npm run dev

不同AI系统中的MCP支持

✅ 克劳德（人类学）

• 克劳德桌面：通过配置文件提供全面支持
• 克劳德代码：全力支持 claude mcp add 命令和 .mcp.json

✅ 双子座（谷歌）

• Gemini CLI：通过提供全面支持 settings.json 或 gemini mcp add 命令

✅ 食品法典委员会（OpenAI）

• Codex CLI：通过提供全面支持 config.toml 或 codex mcp add 命令

注： MCP是一个开放标准，因此支持范围不断扩大。查看AI平台的文档，了解最新的MCP功能。

配置

Vault路径解析

VAULT_PATH 是可选的。服务器按以下顺序解析vault路径：

1. VAULT_PATH 环境变量 --如果设置，则直接使用（向后兼容）
2. MCP客户端根 --如果客户端支持 根，服务器使用第一个 file:// 根作为vault路径

这意味着像Claude Code这样的MCP客户端将工作目录作为根目录公开，当从黑曜石保险库内部启动时，可以使用零配置。

如果两个源都没有提供vault路径，服务器将退出并显示描述性错误。

环境变量

MCP工具

graph_build_index

重建vault图形索引。

{
  "force": true  // Force rebuild even if cache is valid
}

graph_get_neighbors

获取节点的所有邻居（链接笔记）。

{
  "node": "DevOps/GitOps.md",
  "direction": "out"  // "in", "out", or "both"
}

graph_get_neighbors_ranked

根据解释的相关性对邻居进行排名。

{
  "node": "DevOps/GitOps.md",
  "direction": "out",
  "limit": 10,
  "weights": {
    "commonNeighbors": 0.55,
    "degree": 0.35,
    "tagOverlap": 0.10
  }
}

答复：

{
  "node": "DevOps/GitOps.md",
  "direction": "out",
  "results": [
    {
      "id": "DevOps/FluxCD.md",
      "title": "FluxCD",
      "score": 0.72,
      "reasons": [
        "3 shared neighbors",
        "high in-degree (5)",
        "tag overlap: devops, gitops"
      ]
    }
  ],
  "count": 5
}

graph_related

查找2跳之外的相关笔记（未直接链接）。

{
  "node": "DevOps/GitOps.md",
  "limit": 10,
  "direction": "out"
}

graph_hubs

找到最相关的笔记（中心概念）。

{
  "limit": 10,
  "mode": "in"  // "in" (most referenced), "out" (most linking), "both"
}

graph_search

按标题或标签搜索笔记。

{
  "query": "kubernetes",
  "limit": 20,
  "searchIn": ["title", "tags"]
}

graph_get_node

获取特定节点的详细信息。

{
  "node": "DevOps/GitOps.md"
}

MCP资源

vault://node/{id}

获取特定节点的信息。

vault://graph

获取完整的vault图（分页）。支持查询参数：

• page：页码（默认值：1）
• pageSize：每页结果（默认值：100）

vault://stats

获取vault统计信息：节点数、边数、顶部集线器等。

vault://metrics

获取服务器性能指标（兼容Loki）。

排名算法

排名引擎使用三个因素的加权组合：

评分公式：

score = 0.55 * commonNeighborsNorm + 0.35 * degreeNorm + 0.10 * tagJaccard

所有组件均已标准化为\[0,1\]。

日志记录

为了兼容Loki，日志以JSON格式输出：

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "level": "info",
  "component": "graph.builder",
  "event": "build_complete",
  "vault": "/path/to/vault",
  "nodeCount": 842,
  "edgeCount": 3421,
  "duration_ms": 312
}

洛基集成

通过以下方式将原木运送到洛基：

• Promtail：尾部stdout日志
• Docker日志驱动程序：配置JSON日志记录

推荐标签：

• app=vault-graph-mcp
• component={component}

演出

发展

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build
npm run build

# Lint
npm run lint

# Type check
npm run typecheck

项目结构

vault-graph-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── types.ts              # Type definitions
│   ├── config.ts             # Configuration loader
│   ├── scanner/              # Vault file scanner
│   ├── parser/               # Markdown parser
│   ├── graph/                # Graph index & cache
│   ├── ranking/              # Ranking engine
│   ├── server/               # MCP server & handlers
│   └── logger/               # Logging & metrics
├── test/
│   ├── vault/                # Test vault
│   └── *.test.ts             # Test files
└── dist/                     # Compiled output

许可证

麻省理工学院