黑曜石知识管理MCP服务器
本地MCP（模型上下文协议）服务器，提供对黑曜石保管库的无状态I/O访问。此服务器使LLM能够读取、分析和管理黑曜石标记文件、YAML frontmatter和维基链接。
主要特点
- 无状态I/O层：纯数据访问和原子操作-无语义分析
- 35+MCP工具：跨5个类别的全面保险库管理
- 前台管理：解析、更新和验证YAML元数据
- 维基链接操作：提取、分析和操作
[[wikilinks]] - 图的运算：构建链接图，查找反向链接，识别孤立笔记
- 全文检索：跨vault的文字和正则表达式模式匹配
- 安全：路径验证可防止目录遍历攻击
安装
npm install
npm run build配置
创建一个 .env 文件基于 .env.example:
VAULT_PATH=./Test Vault
LOG_LEVEL=info
MAX_CONCURRENT_OPS=10或者在运行时设置环境变量：
VAULT_PATH="./Test Vault" node dist/index.js用法
运行服务器
服务器使用stdio传输进行MCP通信：
VAULT_PATH="./Test Vault" node dist/index.jsClaude桌面集成
添加到您的Claude Desktop MCP配置中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"obsidian-knowledge": {
"command": "node",
"args": ["/absolute/path/to/obsidian-knowledge-mcp/dist/index.js"],
"env": {
"VAULT_PATH": "/absolute/path/to/your/vault"
}
}
}
}可用工具（第1阶段-导航）
1.列表_注释
列出所有带有可选过滤功能的笔记。
参数:
folder（可选）：按文件夹路径筛选tags（可选）：标签数组（注意必须包含所有标签）dateRange（可选）：{ start, end }ISO格式offset（可选）：跳过N个笔记进行分页limit（可选）：返回最多N张钞票
示例:
{
"folder": "Studies/MATH 31AH",
"tags": ["MATH31AH"],
"limit": 10
}退货：数组 NoteMetadata 带有路径、标题、创建日期、标签、修改日期、大小。
2.read_note
阅读带有完整元数据的注释。
参数:
path（必填）：保险库相对路径（例如。，"Studies/MATH 31AH/Vectors.md")
退货:
content：完整的降价内容frontmatter：解析的YAML（如果缺失/格式错误，则为null）frontmatterError：如果YAML格式不正确，则分析错误消息outgoingLinks：带有目标、别名、标题、行、列的维基链接数组headings：带级别、文本、行、id的标题数组stats：行数、字符数、修改的时间戳
3.read_notes_batch
在一次通话中阅读多个笔记。
参数:
paths（必需）：vault相对路径数组
退货：数组 ReadNoteResult （与read_note相同）
4.搜索_注释
在vault中进行全文搜索。
参数:
pattern（必填）：搜索字符串或正则表达式isRegex（可选）：将模式视为正则表达式（默认值：false）folder（可选）：将搜索限制到文件夹limit（可选）：每条注释的最大出现次数（默认值：10）
退货：数组 SearchResult 使用路径、匹配计数和出现次数（使用行、列、上下文）。
5.get_vault_structure
使用笔记计数获取文件夹层次结构。
参数：无
退货: FolderNode 带有路径、名称、笔记计数和子项的树。
建筑
┌─────────────────────────────────────────┐
│ MCP Server (index.ts) │
│ - Tool registration │
│ - Request routing │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Tool Handlers (tools/*.ts) │
│ - navigation.ts - list, read, search │
│ - notes.ts - create, update, move │
│ - frontmatter.ts - get, update, bulk │
│ - links.ts - get links, backlinks │
│ - stats.ts - tags, titles │
└─────────────────────────────────────────┘
↓
┌──────────────────┬──────────────────────┐
│ Vault (vault.ts)│ Parser (parser.ts) │
│ - Path security │ - Frontmatter parse │
│ - File I/O │ - Wikilink extract │
│ - Validation │ - Heading extract │
└──────────────────┴──────────────────────┘错误处理
服务器返回结构化错误和可操作的建议：
{
"success": false,
"error": {
"code": "FILE_NOT_FOUND",
"message": "File not found: nonexistent.md",
"context": { "path": "nonexistent.md" },
"actionable": "Use list_notes or get_note_titles to find available notes"
}
}错误代码:
PATH_OUTSIDE_VAULT：路径包含..或逃离保险库FILE_NOT_FOUND：文件不存在FILE_LOCKED：文件正被其他进程使用INVALID_FRONTMATTER：YAML解析错误INVALID_PATH：路径包含非法字符
发展
建筑
npm run build # Compile TypeScript
npm run dev # Watch mode测试
npm test # Run all tests
npm run test:unit # Unit tests only
npm run test:integration # Integration tests with Test Vault掉毛
npm run lint路线图
第一阶段：基础和导航（已完成）
- \[x\] MCP服务器初始化
- \[x\] 具有路径安全性的保险库访问
- \[x\] Frontmatter和wikilink解析
- \[x\] 5个导航工具（列表、阅读、搜索、结构）
第二阶段：票据管理（计划中）
- \[\]create_note-使用内容+frontmatter创建
- \[\]update_note-替换或修补部分
- \[\]move_note-重新定位+更新反向链接
- \[\]delete_note-删除+清除悬空引用
第三阶段：前线人员行动（计划中）
- \[\]get_frontmatter-解析元数据
- \[\]update_front-修改字段
- \[\]bulk_update_front-跨多个笔记更新
- \[\]audit_front-根据架构进行验证
第4阶段：链路操作（计划中）
- \[\]get_links-传出的维基链接
- \[\]get_backlinks-传入链接
- \[\]get_all_links-完整的链接图
- \[\]插入链接-添加维基链接
- \[\]get_orphan_notes-没有链接的笔记
- \[\]get_headings-标题结构
- \[\]find_text_occurrences-模式匹配
第五阶段：统计与波兰语（计划中）
- \[\]get_tag_list-所有有计数的标签
- \[\]get_note_titles-所有标题+别名
- \[\]综合文件
- \[\]集成测试
- \[\]性能优化
设计原则
- 无状态：无缓存，每个调用都是独立的
- 安全：路径验证可防止逃逸
- 元数据：包括行号和位置，以便进行精确编辑
- 优雅降级：格式错误的frontmatter返回错误标志
- 坚实的原则：vault、解析器和工具层的清晰分离
许可证
麻省理工学院
贡献
欢迎投稿！该项目遵循SOLID原则，并在I/O层（服务器）和智能层（LLM）之间保持严格的分离。