使用说明

黑曜石MCP服务器🧠

一个基于Ruby的模型上下文协议（MCP）服务器，用于与黑曜石保险库交互。内置于快速mcp，此服务器允许AI模型搜索、读取和分析您的常青笔记。

特性

搜索笔记：按内容、标题或标签查找笔记
阅读个人笔记：获取完整的笔记内容，包括封面和链接
列出所有注释：浏览所有带有元数据的笔记
基于标签的过滤：按特定标签查找笔记
保险库统计信息：获取有关您保险库的全面统计数据
标签云：分析标签使用模式

安装

克隆此存储库：

git clone <repository-url>
cd obsidian-mcp-server

安装依赖项：
```
bundle install
```

设置vault路径（可选）：

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"

用法

启动服务器

./obsidian_server.rb

服务器将根据以下情况使用这些方法自动发现您的保管库 OBSIDIAN_VAULT_PATH 环境变量。

可用工具

1.搜索注释

通过标题、标签或内容中的查询文本搜索笔记。

2.阅读注释

按文件名或标题阅读特定笔记的全部内容。

3.列表注释

使用基本元数据获取vault中所有注释的列表。

4.按标签查找

查找包含具有灵活匹配选项的特定标签的注释。

可用资源

1.保险库统计

访问有关保管库的全面统计信息：

注释和单词总数
每个音符的平均字数
唯一标签计数
内部和外部链接计数

2.标签云

获取整个保管库的标签使用统计数据和计数。

配置

设置环境变量以自定义服务器：

OBSIDIAN_VAULT_PATH：通往黑曜石金库的路径

建筑

该项目遵循一个干净、模块化的架构，该架构建立在快速mcp Ruby框架：

├── obsidian_server.rb         # Main executable server entry point
├── Gemfile                    # Dependencies (fast-mcp ~> 1.5, rspec, rubocop)
├── mise.toml                  # Development environment configuration
├── CHANGELOG.md               # Project changelog and version history
├── lib/                       # Main application code
│   ├── obsidian_mcp.rb        # Main module and server factory
│   └── obsidian_mcp/
│       ├── config.rb          # Environment-based configuration
│       ├── logger.rb          # Semantic logging configuration
│       ├── models/            # Domain models
│       │   ├── vault.rb       # Vault discovery and file operations
│       │   └── note.rb        # Note parsing and metadata extraction
│       ├── services/          # Business logic services
│       │   ├── search_service.rb  # Content and metadata search
│       │   └── stats_service.rb   # Vault statistics calculation
│       ├── base/              # Abstract base classes
│       │   ├── tool.rb        # MCP tool interface
│       │   └── resource.rb    # MCP resource interface
│       ├── tools/             # MCP tool implementations
│       │   ├── search_notes.rb    # Full-text search across notes
│       │   ├── read_note.rb       # Single note content retrieval
│       │   ├── list_notes.rb      # Vault-wide note listing
│       │   └── find_by_tags.rb    # Tag-based filtering
│       └── resources/         # MCP resource implementations
│           ├── vault_statistics.rb # Comprehensive vault metrics
│           └── tag_cloud.rb       # Tag usage analytics
└── spec/                      # Comprehensive test suite
    ├── spec_helper.rb         # RSpec configuration and setup
    ├── support/               # Test helpers and shared contexts
    │   └── test_vault_setup.rb # Comprehensive test vault fixture
    ├── models/                # Model unit tests
    │   └── vault_spec.rb      # Vault model testing
    └── integration/           # Integration tests
        └── tools/             # Tool-specific integration tests
            └── list_notes_spec.rb # Complete ListNotes tool test

关键组件

生产代码

服务器条目 (obsidian_server.rb)：初始化和启动MCP服务器的可执行脚本
配置 (config.rb)：管理vault发现和环境变量
模型：用frontmatter解析表示保管库和单个笔记的域对象
服务：搜索操作和统计分析的业务逻辑
工具：提供交互功能的MCP工具实现
资源：提供只读数据访问的MCP资源实现

测试基础设施

测试套件 (spec/)：基于RSpec的全面测试，包含270多个断言
测试保险库设置 (spec/support/test_vault_setup.rb)：使用以下工具创建逼真的测试场景：
- 11种不同的音符类型（简单、标记、仅前体、空、格式错误等）
- 子目录处理(projects/project-alpha.md)
- Unicode和特殊字符支持
- 一致性测试的可预测时间戳
- 临时保险库清理
集成测试：对MCP工具进行全面的端到端测试，并覆盖边缘案例
共享上下文：可重复使用的测试夹具 :vault_setup 标签

保险库发现逻辑

服务器会自动按以下优先级顺序发现保管库：

OBSIDIAN_VAULT_PATH 环境变量
/vault （容器体积）

数据流

初始化：服务器发现vault路径并验证可访问性
工具请求：MCP客户端发送工具调用（搜索、读取、列表、过滤）
处理：服务使用数据访问模型处理业务逻辑
资源请求：MCP客户端请求统计资源
回应：带有注释内容和元数据的格式化JSON响应

测试策略

该项目采用了一种全面的测试方法：

集成测试：测试从输入到输出的完整MCP工具工作流程
逼真的装置：具有不同钞票类型和边缘盒的测试保险库
性能测试：确保亚秒级响应时间
错误处理：测试对格式错误的数据和丢失路径的优雅处理
Unicode支持：验证国际字符和表情符号的正确处理
一致性测试：验证多个呼叫中的相同结果

MCP检验员测试

您可以使用官方MCP检查器测试服务器：

npx @modelcontextprotocol/inspector ./obsidian_server.rb

与Claude Desktop集成

添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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构建和运行 （推荐）：

# Build and start the server
docker-compose up --build

# Run in detached mode
docker-compose up -d --build

# Stop the server
docker-compose down

直接使用Docker构建和运行:

# Build the image
docker build -t obsidian-mcp-server .

# Run the container with your vault mounted
docker run -it --rm \
  -v "/path/to/your/obsidian/vault:/vault:ro" \
  -e OBSIDIAN_VAULT_PATH=/vault \
  obsidian-mcp-server

配置选项

设置环境变量以自定义Docker部署：

# Set your vault path (host machine)
export OBSIDIAN_VAULT_PATH="/Users/you/Documents/MyVault"

# Start with custom configuration
docker-compose up

Docker开发

对于开发工作，请使用包含测试依赖关系的开发容器：

# Start development container
docker-compose up obsidian-mcp-server-dev

# Or run interactively
docker-compose run --rm obsidian-mcp-server-dev /bin/sh

# Inside the container, you can run tests
bundle exec rspec

# Or start the server
./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保管库挂载为只读卷：

主机路径：您的黑曜石金库实际位置
容器路径: /vault （通过映射 OBSIDIAN_VAULT_PATH=/vault)
访问：只读(:ro)防止意外修改

Docker故障排除

权限问题：确保您的vault目录可读
路径问题：装载卷时使用绝对路径
构建问题：使用清除Docker缓存 docker system prune
集装箱日志：检查 docker-compose logs obsidian-mcp-server

发展

需求

Ruby 3.4+
打包工具
布置（建议开发）

开发设置

安装依赖项：

mise run bundle
# or
bundle install

运行开发服务器：

mise run dev
# or
./obsidian_server.rb

运行测试：

bundle exec rspec

开发任务

该项目使用布置对于任务自动化：

# Install dependencies
mise run bundle

# Start development server
mise run dev

# Fix code style issues automatically
mise run rubocop-fix

# Update RuboCop todo list (after fixing violations)
mise run rubocop-todo-update

# Build production Docker image
mise run docker:build

# Build development Docker image
mise run docker:build:dev

代码的风格

此项目使用以下方式强制执行代码样式 RuboCop 随着 rubocop rspec:

自动修复：运行 mise run rubocop-fix 自动纠正违规行为
待办事项列表方法：在中跟踪现有违规行为 .rubocop_todo.yml
CI执行：新的违规行为将无法通过GitHub操作检查
不断改善：通过从待办事项列表中删除条目逐步修复违规行为

残疾警察

Metrics/MethodLength：允许在适当的情况下使用更长的方法
RSpec/MultipleExpectations：允许在集成测试中进行多个断言

测试

包含270多个断言的全面测试套件：

# Run all tests
bundle exec rspec

# Run with coverage
bundle exec rspec --format documentation

# Run specific test files
bundle exec rspec spec/integration/

CI/CD

GitHub自动操作：

在Ruby 3.4上运行完整的测试套件
使用RuboCop强制执行代码样式
运行集成测试
为违规行为提供在线公关反馈

贡献

复刻仓库
创建功能分支(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)
打开拉取请求

代码审查清单

[]本地测试通过(bundle exec rspec)
[]没有违反RuboCop的行为(bundle exec rubocop)
[]新功能包括测试
[]必要时更新文档
[]CI检查在GitHub上通过

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

内置于快速mcp
测试笔记来自张/笔记
灵感来自模型上下文协议规格