黑曜石-MCP服务器
项目介绍
Obsidian MCP Server 🧠
[
](https://github.com/iho ka/obsidian-mcp-server/actions/workflows/dependabot/dependabot-updates)
一个基于Ruby的模型上下文协议（MCP）服务器，用于与Obsidian保险库交互。该服务器使用fast-mcp构建，允许AI模型搜索、读取和分析您的永续笔记。
功能
- 搜索笔记：通过内容、标题或标签查找笔记
- 阅读单个笔记：获取完整笔记内容，包括元数据和链接
- 列出所有笔记：浏览带有元数据的所有笔记
- 基于标签过滤：通过特定标签查找笔记
- 保险库统计：获取关于您保险库的综合统计数据
- 标签云：分析标签使用模式
安装
-
克隆此仓库：
git clone <repository-url> cd obsidian-mcp-server -
安装依赖项：
bundle install -
设置您的保险库路径（可选）：
export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
使用方法
启动服务器
./obsidian_server.rb
服务器将根据OBSIDIAN_VAULT_PATH环境变量自动发现您的保险库。
可用工具
1. 搜索笔记
通过查询文本在标题、标签或内容中搜索笔记。
2. 阅读笔记
通过文件名或标题读取特定笔记的完整内容。
3. 列出笔记
获取保险库中所有笔记的基本元数据列表。
4. 根据标签查找
查找包含特定标签的笔记，具有灵活的匹配选项。
可用资源
1. 保险库统计
访问关于您保险库的综合统计数据：
- 总笔记数和总字数
- 每篇笔记平均字数
- 唯一标签数量
- 内部和外部链接数量
2. 标签云
获取保险库中的标签使用统计和计数。
配置
设置环境变量以自定义服务器：
OBSIDIAN_VAULT_PATH：指向您的Obsidian保险库的路径
架构
该项目遵循基于fast-mcp Ruby框架的干净模块化架构：
├── obsidian_server.rb # 主执行服务器入口点
├── Gemfile # 依赖项（fast-mcp ~> 1.5, rspec, rubocop）
├── mise.toml # 开发环境配置
├── CHANGELOG.md # 项目变更日志和版本历史
├── lib/ # 主应用程序代码
│ ├── obsidian_mcp.rb # 主模块和服务器工厂
│ └── obsidian_mcp/
│ ├── config.rb # 基于环境的配置
│ ├── logger.rb # 语义日志配置
│ ├── models/ # 领域模型
│ │ ├── vault.rb # 保险库发现和文件操作
│ │ └── note.rb # 笔记解析和元数据提取
│ ├── services/ # 业务逻辑服务
│ │ ├── search_service.rb # 内容和元数据搜索
│ │ └── stats_service.rb # 保险库统计计算
│ ├── base/ # 抽象基类
│ │ ├── tool.rb # MCP工具接口
│ │ └── resource.rb # MCP资源接口
│ ├── tools/ # MCP工具实现
│ │ ├── search_notes.rb # 跨笔记全文搜索
│ │ ├── read_note.rb # 单笔记内容检索
│ │ ├── list_notes.rb # 保险库范围内的笔记列表
│ │ └── find_by_tags.rb # 基于标签的过滤
│ └── resources/ # MCP资源实现
│ ├── vault_statistics.rb # 综合保险库指标
│ └── tag_cloud.rb # 标签使用分析
└── spec/ # 综合测试套件
├── spec_helper.rb # RSpec配置和设置
├── support/ # 测试助手和共享上下文
│ └── test_vault_setup.rb # 综合测试保险库固定装置
├── models/ # 模型单元测试
│ └── vault_spec.rb # 保险库模型测试
└── integration/ # 集成测试
└── tools/ # 工具特定的集成测试
└── list_notes_spec.rb # 完整的ListNotes工具测试
关键组件
生产代码
- 服务器入口 (
obsidian_server.rb)：初始化并启动MCP服务器的可执行脚本 - 配置 (
config.rb)：管理保险库发现和环境变量 - 模型：表示保险库和单个笔记的领域对象，具有元数据解析
- 服务：搜索操作和统计分析的业务逻辑
- 工具：提供交互能力的MCP工具实现
- 资源：提供只读数据访问的MCP资源实现
测试基础设施
- 测试套件 (
spec/)：基于RSpec的全面测试，超过270个断言 - 测试保险库设置 (
spec/support/test_vault_setup.rb)：创建现实的测试场景，包括：- 11种不同类型的笔记（简单、带标签、仅元数据、空、畸形等）
- 子目录处理（
projects/project-alpha.md） - Unicode和特殊字符支持
- 可预测的时间戳以确保一致的测试
- 临时保险库清理
- 集成测试：MCP工具的端到端测试，覆盖边缘情况
- 共享上下文：带有
:vault_setup标签的可重用测试固定装置
保险库发现逻辑
服务器按以下优先级顺序自动发现保险库：
OBSIDIAN_VAULT_PATH环境变量/vault（容器卷）
数据流
- 初始化：服务器发现保险库路径并验证可访问性
- 工具请求：MCP客户端发送工具调用（搜索、读取、列表、过滤）
- 处理：服务使用模型进行数据访问来处理业务逻辑
- 资源请求：MCP客户端请求统计资源
- 响应：格式化的JSON响应，包含笔记内容和元数据
测试策略
项目采用全面的测试方法：
- 集成测试：从输入到输出测试完整的MCP工具工作流程
- 现实的固定装置：具有多种笔记类型和边缘案例的测试保险库
- 性能测试：确保亚秒级响应时间
- 错误处理：测试对畸形数据和缺失路径的优雅处理
- Unicode支持：验证国际字符和表情符号的正确处理
- 一致性测试：验证多次调用的一致结果
使用MCP Inspector进行测试
您可以使用官方的MCP inspector测试服务器：
npx @modelcontextprotocol/inspector ./obsidian_server.rb
与Claude Desktop集成
添加到您的Claude Desktop配置中：
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\\Claude\\claude_desktop_config.json
{
"mcpServers": {
"obsidian-vault": {
"command": "ruby",
"args": ["/path/to/obsidian-mcp-server/obsidian_server.rb"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
Docker支持 🐳
使用Docker运行MCP服务器，以便轻松部署和环境一致性。
使用Docker快速开始
-
使用Docker Compose构建和运行（推荐）：
# 构建并启动服务器 docker-compose up --build # 在分离模式下运行 docker-compose up -d --build # 停止服务器 docker-compose down -
直接使用Docker构建和运行：
# 构建镜像 docker build -t obsidian-mcp-server . # 运行容器，挂载您的保险库 docker run -it --rm \ -v "/path/to/your/obsidian/vault:/vault:ro" \ -e OBSIDIAN_VAULT_PATH=/vault \ obsidian-mcp-server
配置选项
设置环境变量以自定义Docker部署：
# 设置您的保险库路径（主机机器）
export OBSIDIAN_VAULT_PATH="/Users/you/Documents/MyVault"
# 使用自定义配置启动
docker-compose up
开发使用Docker
对于开发工作，请使用包含测试依赖项的开发容器：
# 启动开发容器
docker-compose up obsidian-mcp-server-dev
# 或者交互式运行
docker-compose run --rm obsidian-mcp-server-dev /bin/sh
# 在容器内，您可以运行测试
bundle exec rspec
# 或者启动服务器
./obsidian_server.rb
Docker与Claude Desktop集成
要使用Docker化的服务器与Claude Desktop集成，可以将其作为持久服务运行：
{
"mcpServers": {
"obsidian-vault": {
"command": "docker",
"disabled": true,
"args": [
"run",
"-i",
"--rm",
"-v",
"/path/to/your/vault:/vault",
"obsidian-mcp-server"
]
}
}
}
注意：首先构建Docker镜像：docker build -t obsidian-mcp-server .
Docker文件概述
Dockerfile：生产就绪镜像，最小依赖项Dockerfile.dev：开发镜像，包含测试依赖项和工具docker-compose.yml：易于编排生产和开发.dockerignore：通过排除不必要的文件优化构建上下文
保险库挂载
Docker设置将您的Obsidian保险库作为只读卷挂载，以保证安全性：
- 主机路径：您的实际Obsidian保险库位置
- 容器路径：
/vault（通过OBSIDIAN_VAULT_PATH=/vault映射） - 访问：只读（
:ro），防止意外修改
Docker故障排除
- 权限问题：确保您的保险库目录可读
- 路径问题：挂载卷时使用绝对路径
- 构建问题：使用
docker system prune清除Docker缓存 - 容器日志：检查
docker-compose logs obsidian-mcp-server
开发
要求
开发设置
- 安装依赖项：
mise run bundle
# 或
bundle install
- 运行开发服务器：
mise run dev
# 或
./obsidian_server.rb
- 运行测试：
bundle exec rspec
开发任务
项目使用mise进行任务自动化：
# 安装依赖项
mise run bundle
# 启动开发服务器
mise run dev
# 自动修复代码风格问题
mise run rubocop-fix
# 更新RuboCop待办事项列表（修复违规后）
mise run rubocop-todo-update
# 构建生产Docker镜像
mise run docker:build
# 构建开发Docker镜像
mise run docker:build:dev
代码风格
此项目使用RuboCop和rubocop-rspec强制执行代码风格：
- 自动修复：运行
mise run rubocop-fix以自动修正违规 - 待办事项列表方法：现有违规记录在
.rubocop_todo.yml中 - CI强制执行：新违规将在GitHub Actions检查中失败
- 逐步改进：通过从待办事项列表中删除条目逐渐修复违规
禁用的规则
Metrics/MethodLength：允许适当长度的方法RSpec/MultipleExpectations：允许在集成测试中有多次期望
测试
全面的测试套件，超过270个断言：
# 运行所有测试
bundle exec rspec
# 带覆盖率运行
bundle exec rspec --format documentation
# 运行特定测试文件
bundle exec rspec spec/integration/
CI/CD
GitHub Actions会自动：
- 在Ruby 3.4上运行完整的测试套件
- 使用RuboCop强制执行代码风格
- 运行集成测试
- 在GitHub上提供PR违规的内联反馈
贡献
-
分叉仓库
-
创建功能分支（
git checkout -b feature/amazing-feature） -
按照代码风格指南进行更改
-
运行测试并修复任何风格违规：
bundle exec rspec mise run rubocop-fix -
提交更改（
git commit -m 'Add some amazing feature'） -
推送到分支（
git push origin feature/amazing-feature） -
打开Pull Request
代码审查检查表
- 本地测试通过（
bundle exec rspec） - 无RuboCop违规（
bundle exec rubocop） - 新功能包含测试
- 如需更新文档
- GitHub上的CI检查通过
许可证
本项目根据MIT许可证发布 - 查看LICENSE文件了解详情。
致谢
- 使用fast-mcp构建
- 测试笔记来自keikhcheung/notes
- 受Model Context Protocol规范启发