使用说明
黑曜石MCP服务器插件
项目概述
这是一个黑曜石插件，用作MCP（模型上下文协议）服务器，使Claude Desktop和其他AI助手能够直接与黑曜石库交互。它提供了MCP协议（由Claude Desktop使用）和Obsidian API之间的桥梁。
作者 老师贝斯 / Sensei Bass 许可证： 麻省理工学院 版本： 1.0.0
建筑
高级设计
Claude Desktop (stdio)
↓
stdio-bridge.js (converts stdio ↔ HTTP)
↓
MCP Server (HTTP on localhost:3000)
↓
Obsidian API (vault access)
为什么选择HTTP而不是stdio？
黑曜石在Electron中运行，而Electron没有直接的stdio访问权限。此插件在本地运行HTTP服务器（localhost:3000），并使用stdio网桥(stdio-bridge.js)在以下两者之间转换：
- Claude Desktop基于stdio的MCP协议
- 此插件基于HTTP的实现
这种架构是 安全意识：HTTP服务器只监听本地主机，阻止外部网络访问。
核心组件
1.MCP服务器(src/mcp-server.ts)
主服务器类：
- 在端口3000上运行HTTP服务器（仅限本地主机）
- 在JSON-RPC 2.0上实现MCP协议
- 处理三种核心MCP方法：
initialize-协议握手tools/list-返回可用工具tools/call-执行工具
关键实施细节：
- 使用Electron的内置
http模块（非节点） - 为本地主机启用CORS
- 所有请求都是POST（CORS飞行前的选项）
- 通知（以开头的方法
notifications/)已确认但未处理
2.可用工具
该插件为vault交互提供了四种工具：
search_notes
地点： src/tools/search-notes.ts
目的： 按查询文本搜索vault笔记
参数：
query（必填）：搜索文本（搜索标题和内容）folder（可选）：按文件夹路径筛选tag（可选）：按标签筛选（不带#）limit（可选）：最大结果（默认值：10）
退货： 带有片段的匹配笔记的JSON数组
get_note
地点： src/tools/get-note.ts
目的： 阅读特定笔记的完整内容和元数据
参数：
path（必需）：要注释的Vault路径
退货： 注意内容、元数据、封面、标签、链接
重要提示： 使用 search_notes 首先找到正确的路径，然后使用 get_note 阅读完整内容。
get_related_notes
地点： src/tools/get-related-notes.ts
目的： 查找与特定笔记相关的笔记
参数：
path（必需）：要注释的Vault路径
退货：
- 传出链接（注意此注释链接到）
- 传入链接/反向链接（链接到此注释的注释）
注： 仅返回路径-使用 get_note 阅读相关笔记的全部内容。
append_to_note
地点： src/tools/append-to-note.ts
目的： 将内容附加到现有注释的末尾
参数：
path（必需）：要注释的Vault路径content（必填）：要附加的Markdown内容
退货： 成功消息
使用案例： 添加新信息、记录、扩展笔记而不替换内容
3.插件入口点(main.ts)
主要的黑曜石插件类：
- 加载/卸载插件
- 启动/停止MCP服务器
- 与Obsidian的插件系统集成
4.斯迪奥大桥(stdio-bridge.js)
独立的Node.js脚本：
- 从stdin（从Claude Desktop）读取JSON-RPC
- 转发到HTTP服务器（此插件）
- 将HTTP响应发送回stdout
- 处理初始化和工具调用
开发指南
构建命令
npm install # Install dependencies
npm run dev # Watch mode (rebuilds on changes)
npm run build # Production build
项目结构
.
├── src/
│ ├── mcp-server.ts # Main MCP server implementation
│ ├── types.ts # TypeScript types
│ └── tools/
│ ├── search-notes.ts # Search functionality
│ ├── get-note.ts # Note reading
│ ├── get-related-notes.ts # Link traversal
│ └── append-to-note.ts # Note appending
├── main.ts # Obsidian plugin entry point
├── stdio-bridge.js # Claude Desktop bridge
├── manifest.json # Plugin manifest
└── package.json # Dependencies
关键依赖关系
obsidian-黑眼圈API类型esbuild-构建工具typescript-语言- 内置Node.js
http模块（通过电子）
测试
node test-connection.js # Test HTTP server directly
node test-mcp.js # Test MCP protocol
协议细节
MCP（模型上下文协议）
此插件在JSON-RPC 2.0上实现了MCP 2024-11-05协议版本。
支持的方法：
initialize-握手，回报能力tools/list-返回带有JSON模式的工具定义tools/call-执行带有参数的工具
工具响应格式：
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "Tool result as string"
}
]
}
}
错误处理
标准JSON-RPC错误代码：
-32601-未找到方法-32603-内部错误/工具执行失败
配置
Claude桌面设置
窗户：
{
"mcpServers": {
"obsidian-vault": {
"command": "node",
"args": [
"C:\\Path\\To\\Vault\\.obsidian\\plugins\\mcp-server\\stdio-bridge.js"
]
}
}
}
macOS/Linux：
{
"mcpServers": {
"obsidian-vault": {
"command": "node",
"args": [
"/path/to/vault/.obsidian/plugins/mcp-server/stdio-bridge.js"
]
}
}
}
常见模式
搜索笔记
- 使用
search_notes带有查询 - 可选择按文件夹或标签过滤
- 获取具有路径的匹配笔记列表
阅读笔记内容
- 使用
search_notes查找笔记路径 - 使用
get_note具有读取完整内容的确切路径
探索相关笔记
- 使用
get_related_notes查找链接笔记 - 使用
get_note在每个相关路径上读取内容 - 递归探索构建知识图谱
添加到备注
- 使用
search_notes或get_note验证钞票是否存在 - 使用
append_to_note在末尾添加内容
安全注意事项
- HTTP服务器仅侦听
localhost(127.0.0.1) - 无外部网络访问
- 无需身份验证（假设本地环境可信）
- CORS仅对本地主机启用
故障排除
服务器无法启动
- 检查端口3000是否已在使用中
- 检查黑曜石开发人员控制台（Ctrl+Shift+I）
Claude Desktop无法连接
- 验证Obsidian是否正在运行
- 验证插件是否在黑曜石设置中启用
- 检查路径
claude_desktop_config.json是正确的 - 完全重新启动克劳德桌面
工具调用失败
- 检查Obsidian控制台是否有错误消息
- 验证注释路径是否正确（区分大小写）
- 阅读前确保笔记存在
未来增强思路
基于 findings.md，要添加的潜在功能：
- 基础查询执行 -执行Dataview查询，返回结果
- 插件集成 -列出已安装的插件，访问其数据
- 笔记创建 -创建新笔记（目前仅追加）
- 注释修改 -编辑现有内容（而不仅仅是追加）
- 文件操作 -移动、重命名、删除笔记
- 图形分析 -高级链接图查询
- Canvas集成 -读取/修改画布文件
