Vault Sources MCP

保管库来源mcp

 ](package.json) 

“这张纸条是从哪里来的？” --人工智能生成的黑曜石金库的来源分类账。

一 主控程序 跟踪服务器 哪些输入 （成绩单、文章、摘录） 其中注意到 在你的黑曜石金库里——永远不要碰金库本身。

______________________________________________________________________

问题

您可以使用AI代理从YouTube成绩单、书籍摘录、文章和粘贴的文本中填充黑曜石库。随着时间的推移，金库逐渐发展成为一个丰富的知识库，但 *起源* 这些知识消失了：

• 聊天记录丢失。复制粘贴源已被遗忘。
• 你不能回答 “这张纸条是从哪里来的？”
• 没有办法审计、核对或清理人工智能生成的内容。
• 当事情看起来不对劲时，你无法追溯到源头。

解决方案

vault-sources-mcp 是一个 来源分类账 它就在你的保险库旁边。它使任何与MCP兼容的AI代理都能够：

• 存储原始输入 （成绩单、文章等）使用SHA-256重复数据删除
• 将输入链接到笔记 通过frontmatter中的稳定UUID v7标识符
• 查询来源 双向——注释的来源，注释的来源
• 诊断问题 --查找孤立的输入、过时的笔记、缺失的链接
• 审核一切 通过不可变的、仅可追加的事件日志

所有数据都存在于一个SQLite文件中。服务器从不读取或写入您的保管库。

______________________________________________________________________

运作原理

┌──────────────┐                              ┌──────────────────────┐
│   AI Agent   │◄── MCP (15 tools) ──────────►│  vault-sources-mcp   │
│              │                               │                      │
│  Reads/edits │                               │  Stores inputs,      │
│  markdown    │                               │  tracks links,       │
│  files       │                               │  logs events         │
└──────┬───────┘                               └──────────┬───────────┘
       │                                                  │
       ▼                                                  ▼
┌──────────────┐                               ┌──────────────────────┐
│  Obsidian    │                               │  SQLite database     │
│  Vault       │                               │  (single file)       │
└──────────────┘                               └──────────────────────┘

代理处理所有vault交互。MCP服务器处理所有来源数据。他们通过15种结构化工具进行沟通。

______________________________________________________________________

安装

git clone https://github.com/your-username/vault-sources-mcp.git
cd vault-sources-mcp
npm install
npm run build

______________________________________________________________________

用法

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

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

如果你的工作目录是黑曜石保险库，不需要环境变量——服务器会自动从MCP根目录检测vault，并将数据库存储为 .vault-sources.sqlite 里面：

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

如果你的保险库在别处，设置显式路径：

{
  "mcpServers": {
    "vault-sources": {
      "command": "node",
      "args": ["/path/to/vault-sources-mcp/dist/src/index.js"],
      "env": {
        "VAULT_SOURCES_DB_PATH": "/path/to/vault-sources.sqlite"
      }
    }
  }
}

2.通过Claude CLI

claude mcp add --transport stdio \
  --env VAULT_SOURCES_DB_PATH=/path/to/vault-sources.sqlite \
  vault-sources -- node /path/to/vault-sources-mcp/dist/src/index.js

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

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

添加到您的Claude Desktop配置中：

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

{
  "mcpServers": {
    "vault-sources": {
      "command": "node",
      "args": ["/path/to/vault-sources-mcp/dist/src/index.js"],
      "env": {
        "VAULT_SOURCES_DB_PATH": "/path/to/vault-sources.sqlite"
      }
    }
  }
}

4.使用Gemini CLI

增添 ~/.gemini/settings.json:

{
  "mcpServers": {
    "vault-sources": {
      "command": "node",
      "args": ["/path/to/vault-sources-mcp/dist/src/index.js"],
      "env": {
        "VAULT_SOURCES_DB_PATH": "/path/to/vault-sources.sqlite"
      }
    }
  }
}

5.使用Codex CLI（OpenAI）

增添 ~/.codex/config.toml:

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

[mcp_servers.vault-sources.env]
VAULT_SOURCES_DB_PATH = "/path/to/vault-sources.sqlite"

注： MCP是一个开放标准。任何兼容MCP的客户端都可以通过stdio传输使用此服务器。

______________________________________________________________________

配置

数据库路径解析

数据库路径按以下顺序解析：

1. CLI参数 — node dist/src/index.js /path/to/db.sqlite
2. VAULT_SOURCES_DB_PATH 环境变量
3. VAULT_PATH 环境变量--数据库存储为 $VAULT_PATH/.vault-sources.sqlite
4. MCP客户端根 --如果客户端支持 根，服务器使用第一个 file:// root并将数据库存储为 .vault-sources.sqlite 在里面
5. 后备方案 — ./data/vault-sources.sqlite

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

环境变量

______________________________________________________________________

MCP工具

数据库管理

输入管理

笔记管理

来源链接

对账与诊断

______________________________________________________________________

典型工作流程

以下是与MCP连接的代理在实践中的对话：

1.  User provides a YouTube transcript
2.  Agent calls  store_input           → persists the transcript, gets input_id
3.  Agent calls  generate_note_id      → gets a UUIDv7 for the new note
4.  Agent writes the markdown file with the ID in frontmatter
5.  Agent calls  register_note         → registers the note in the provenance DB
6.  Agent calls  add_link              → links the transcript to the note

稍后，用户询问 *“我的堆肥基础笔记是从哪里来的？”*:

7.  Agent calls  get_sources_for_note  → returns the linked transcript metadata
8.  Agent calls  get_input             → retrieves the full original text

对于定期vault健康检查：

9.  Agent calls  find_stale_notes      → which notes haven't been seen recently?
10. Agent calls  find_orphaned_inputs  → which inputs were never used?
11. Agent calls  get_event_log         → full audit trail of every action

______________________________________________________________________

设计原则

______________________________________________________________________

项目结构

vault-sources-mcp/
├── src/
│   ├── index.ts                    # MCP server entry point (stdio transport)
│   ├── types.ts                    # Core types: Input, Note, Link, Event
│   ├── errors.ts                   # Custom error classes
│   ├── db/
│   │   ├── database.ts             # SQLite manager (WAL mode, FK enforcement)
│   │   └── repositories/
│   │       ├── input-repository.ts # Store, deduplicate, redact inputs
│   │       ├── note-repository.ts  # Register, find stale/unlinked notes
│   │       ├── link-repository.ts  # Provenance links, orphan detection
│   │       └── event-repository.ts # Append-only audit log
│   └── tools/
│       ├── db-tools.ts             # db_status, db_init
│       ├── id-tools.ts             # generate_note_id
│       ├── input-tools.ts          # store, get, list, redact
│       ├── note-tools.ts           # register, get, mark deleted
│       ├── link-tools.ts           # add, remove, query both directions
│       └── reconciliation-tools.ts # Diagnostics & event log queries
├── skills/                            # Claude Code skill templates
│   ├── vault-init/SKILL.md            # Database initialization workflow
│   ├── store-source/SKILL.md          # Store input sources
│   ├── new-note/SKILL.md              # Create note with provenance
│   ├── check-provenance/SKILL.md      # Trace note origins
│   └── vault-health/SKILL.md          # Diagnostic health checks
├── test/
│   ├── db/                         # Unit tests (40 tests)
│   ├── integration.test.ts         # End-to-end workflow test (4 tests)
│   └── dummy-vault/                # Sample Obsidian vault (gardening notes)
└── dist/                           # Compiled output

______________________________________________________________________

技能模板

该项目包括即用型 Claude代码技能 模板在 skills/ 目录。将它们复制到项目的 .claude/skills/ 为您的AI代理提供结构化的工作流程，用于追踪来源。

安装

# Copy all skills into your project
cp -r /path/to/vault-sources-mcp/skills/* .claude/skills/

或者根据需要复制个人技能。

可用技能

定制

每种技能都是独立的 SKILL.md 使用YAML frontmatter文件。你可以：

• 编辑 description 当Claude自动调用该技能时进行微调
• 集 disable-model-invocation: true 将技能限制为手工 /command 仅使用
• 添加支持文件 技能目录中的（模板、示例）
• 调整元数据字段 （例如。 source_type, title)以匹配您的工作流程

看 Claude代码技能文档 以获取完整的配置参考。

______________________________________________________________________

发展

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm test             # Run all tests
npm run dev          # Watch mode (recompile on change)
npm run clean        # Remove compiled output

______________________________________________________________________

许可证

麻省理工学院