Obsidian Lumina

✨ 项目名称来源

Obsidian-Lumina-MCP 的名称含义：

• Obsidian: 黑曜石，代表您的笔记知识库
• Lumina: 拉丁语中的"光"或"启迪"，象征这个项目为您的笔记带来智能搜索的"光"，帮助您快速找到所需的知识
• MCP: Model Context Protocol，使 AI 助手能够访问和理解您的笔记

🎯 功能特性

• 🔍 向量语义搜索: 使用 Ollama 嵌入模型将笔记内容转换为向量，支持语义相似度搜索，不仅仅是关键词匹配
• 📁 自动文件监控: 使用 chokidar 实时监控 Obsidian 笔记文件夹，自动索引新增和修改的文件
• 📝 段落级索引: 按段落（\n\n）分割笔记内容，提供更精确的搜索结果
• 🚀 MCP 协议支持: 通过 MCP 协议提供 search_notes 工具，可与 Cline、Claude Desktop 等客户端无缝集成
• ⚡ 增量更新: 智能检测文件变化，只处理新增或修改的文件，大幅提升启动速度
• 🛡️ MCP 规范遵循: 严格遵循 MCP 规范，确保与所有兼容客户端的稳定连接

📋 前置要求

在开始之前，请确保您的系统满足以下要求：

必需软件

1. Node.js >= 18

   node --version  # 检查版本
   

   • 下载地址: https://nodejs.org/

2. Ollama

   • 下载地址: https://ollama.com/
   • 安装后确保 Ollama 服务正在运行:

     ollama serve
     

3. 嵌入模型

   • 推荐模型: bge-m3:latest 或 nomic-embed-text
   • 下载模型:

     ollama pull bge-m3:latest
     # 或
     ollama pull nomic-embed-text
     

必需信息

• Obsidian 笔记文件夹路径: 您需要知道 Obsidian vault 的绝对路径
  • Windows 示例: C:\Users\YourName\Documents\Obsidian Vault
  • macOS/Linux 示例: /Users/YourName/Documents/Obsidian Vault

🚀 快速开始

1. 安装项目

# 克隆项目
git clone <repository-url>
cd Obsidian-Lumina-MCP

# 安装依赖
npm install

2. 编译项目

npm run build

3. 配置 MCP 客户端

选择您使用的客户端，按照下方配置说明进行设置。

🔧 MCP 客户端配置

方式 1: Cline (VS Code 扩展) - 推荐

Cline 是 VS Code 的 AI 编程助手扩展，支持 MCP 协议。

配置文件位置

Windows:

%APPDATA%\Code\User\cline_mcp_settings.json

或

C:\Users\YourName\AppData\Roaming\Code\User\cline_mcp_settings.json

macOS:

~/Library/Application Support/Code/User/cline_mcp_settings.json

Linux:

~/.config/Code/User/cline_mcp_settings.json

配置内容

在 cline_mcp_settings.json 文件中添加以下配置（如果文件不存在则创建）：

{
  "mcpServers": {
    "obsidian-lumina": {
      "command": "node",
      "args": ["D:\\code_project\\Obsidian-Lumina-MCP\\dist\\index.js"],
      "env": {
        "OBSIDIAN_PATH": "C:\\Users\\YourName\\Documents\\Obsidian Vault",
        "EMBED_MODEL": "bge-m3:latest",
        "DB_PATH": "./.lancedb"
      }
    }
  }
}

重要提示:

• 将 args 中的路径替换为您的项目绝对路径
• 将 OBSIDIAN_PATH 替换为您的 Obsidian 文件夹绝对路径
• Windows 路径中的反斜杠需要转义为 \\，或使用正斜杠 /
• DB_PATH 可以使用相对路径（相对于项目目录），会自动解析为绝对路径

使用示例

配置完成后，重启 VS Code，然后在 Cline 对话中：

搜索我的笔记中关于机器学习的内容

或

帮我找一下关于 TypeScript 的笔记

方式 2: Claude Desktop

配置文件位置

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

配置内容

{
  "mcpServers": {
    "obsidian-lumina": {
      "command": "node",
      "args": ["D:\\code_project\\Obsidian-Lumina-MCP\\dist\\index.js"],
      "env": {
        "OBSIDIAN_PATH": "C:\\Users\\YourName\\Documents\\Obsidian Vault",
        "EMBED_MODEL": "bge-m3:latest",
        "DB_PATH": "./.lancedb"
      }
    }
  }
}

注意:

• 保存配置文件后，完全退出并重新启动 Claude Desktop
• 确保路径使用绝对路径

方式 3: MCP Inspector (测试工具)

MCP Inspector 是官方提供的测试工具，适合开发和调试。

安装

npm install -g @modelcontextprotocol/inspector

启动

mcp-inspector

配置

在 Inspector 界面中：

• Command: node
• Args: [项目绝对路径]/dist/index.js
• Environment Variables:

  OBSIDIAN_PATH=[您的 Obsidian 路径]
  EMBED_MODEL=bge-m3:latest
  DB_PATH=./.lancedb
  

详细步骤请参考 MCP_TEST_GUIDE.md。

🛠️ 技术栈

核心技术

• TypeScript: 类型安全的 JavaScript，提供更好的开发体验和代码质量
• Node.js ESM: 使用 ES Modules，支持现代 JavaScript 特性

向量搜索技术

• Ollama: 本地大语言模型和嵌入模型服务
  • 支持多种嵌入模型（如 bge-m3, nomic-embed-text）
  • 本地运行，数据隐私安全
• LanceDB: 高性能向量数据库
  • 支持快速向量相似度搜索
  • 数据持久化存储
  • 自动处理向量维度

文件监控

• chokidar: 跨平台文件系统监控库
  • 实时监控文件变化
  • 支持 Windows、macOS、Linux
  • 高效的事件驱动架构

MCP 协议

• @modelcontextprotocol/sdk: 官方 MCP SDK
  • 标准化的工具注册和调用
  • STDIO 传输支持
  • 类型安全的接口定义

数据验证

• zod: TypeScript 优先的模式验证库
  • 工具参数验证
  • 类型安全的 schema 定义

💡 实现思路

架构设计

┌─────────────────┐
│  MCP Client     │  (Cline / Claude Desktop)
│  (Cline/Claude) │
└────────┬────────┘
         │ MCP Protocol (JSON-RPC over STDIO)
         │
┌────────▼─────────────────────────────────┐
│  Obsidian Lumina MCP Server             │
│  ┌─────────────────────────────────────┐ │
│  │  MCP Server (StdioServerTransport)  │ │
│  │  - 注册 search_notes 工具           │ │
│  │  - 处理工具调用                      │ │
│  └──────────────┬──────────────────────┘ │
│                 │                        │
│  ┌──────────────▼──────────────────────┐ │
│  │  VectorService                     │ │
│  │  - 向量生成 (Ollama)                │ │
│  │  - 向量存储 (LanceDB)               │ │
│  │  - 向量搜索                         │ │
│  └──────────────┬──────────────────────┘ │
│                 │                        │
│  ┌──────────────▼──────────────────────┐ │
│  │  FileWatcher                       │ │
│  │  - 文件监控 (chokidar)              │ │
│  │  - 增量更新                         │ │
│  │  - 自动索引                         │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘
         │
         │
┌────────▼────────┐    ┌──────────────┐
│  Ollama Service │    │  LanceDB     │
│  (Embeddings)   │    │  (Vector DB) │
└─────────────────┘    └──────────────┘

工作流程

1. 初始化阶段

   • 连接 LanceDB 数据库
   • 检测向量维度（通过测试 embedding）
   • 创建或打开数据表

2. 启动优化

   • 立即启动 MCP Server: 先启动 MCP Server 并响应客户端连接
   • 后台全量扫描: 在后台异步执行全量扫描，不阻塞服务器启动
   • 增量更新: 检查文件修改时间，跳过未修改的文件

3. 文件处理流程

   文件变化检测
       ↓
   检查文件修改时间
       ↓
   已存在且未修改? → 跳过
       ↓
   文件不存在或已修改
       ↓
   读取文件内容
       ↓
   按段落分割 (\n\n)
       ↓
   生成向量 (Ollama)
       ↓
   存储到数据库 (LanceDB)
   

4. 搜索流程

   用户查询
       ↓
   转换为向量 (Ollama)
       ↓
   向量相似度搜索 (LanceDB)
       ↓
   返回最相关的 5 条结果
   

关键优化

1. 增量更新机制

   • 通过比较文件修改时间判断是否需要重新处理
   • 大幅减少不必要的 embedding 计算
   • 提升启动速度和运行效率

2. 异步启动

   • MCP Server 立即启动，不等待全量扫描
   • 解决客户端连接超时问题
   • 全量扫描在后台异步进行

3. 路径自动解析

   • 自动将相对路径解析为绝对路径
   • 确保无论从哪里启动都能正常工作
   • 支持不同工作目录场景

4. MCP 规范遵循

   • 所有日志输出到 stderr，不干扰 JSON-RPC 消息
   • 标准化的错误处理
   • 类型安全的工具接口

📖 工具说明

search_notes

搜索 Obsidian 笔记的向量语义搜索工具。

参数:

• query (string, 必需): 搜索查询文本

返回:

• 最多 5 条最相关的笔记段落
• 每条结果包含:
  • content: 笔记内容片段
  • filePath: 文件路径
  • score: 相似度分数（越小越相似）

示例:

{
  "query": "如何学习 TypeScript"
}

返回示例:

[
  {
    "content": "TypeScript 是 JavaScript 的超集...",
    "filePath": "C:\\Users\\YourName\\Documents\\Obsidian Vault\\Coding\\TypeScript.md",
    "score": 0.75
  },
  ...
]

🔍 工作原理详解

1. 向量化过程

• 文本输入: 读取 Obsidian 笔记文件
• 段落分割: 按双换行符（\n\n）分割为段落
• 向量生成: 使用 Ollama 嵌入模型将每个段落转换为高维向量
• 存储: 将向量、原始文本、文件路径、修改时间存储到 LanceDB

2. 搜索过程

• 查询向量化: 将用户查询转换为向量
• 相似度计算: 在 LanceDB 中计算查询向量与所有存储向量的相似度
• 结果排序: 按相似度排序，返回最相关的结果

3. 增量更新

• 文件监控: 使用 chokidar 实时监控文件系统变化
• 时间戳比较: 比较文件修改时间与数据库中的记录
• 智能跳过: 未修改的文件跳过处理，只处理新增或修改的文件

🛡️ MCP 规范遵循

本项目严格遵循 Model Context Protocol 规范：

• ✅ STDIO 传输规范: 所有日志输出使用 console.error() 写入 stderr，确保不会干扰 JSON-RPC 消息传输
• ✅ 工具注册: 使用标准的 MCP SDK 注册工具，提供类型安全的接口
• ✅ 错误处理: 符合 MCP 错误响应格式，确保客户端能正确处理错误情况
• ✅ 快速启动: 优化启动流程，避免客户端连接超时

重要: 对于 STDIO 传输的 MCP 服务器，绝对不能向 stdout 写入任何内容（包括 console.log()），这会破坏 JSON-RPC 消息。本项目所有日志都输出到 stderr。

🐛 故障排除

连接超时问题

如果 MCP 客户端显示 "Request timed out":

1. 检查服务器是否能手动启动:

   node dist/index.js
   

   如果启动失败，查看错误信息

2. 检查 Ollama 服务:

   ollama list
   

   确保 Ollama 正在运行且模型已下载

3. 检查路径配置:

   • 确保使用绝对路径
   • 检查路径是否正确转义（Windows 使用 \\）

Ollama 连接失败

• 确保 Ollama 服务正在运行: ollama serve
• 检查模型是否已下载: ollama list
• 验证 EMBED_MODEL 环境变量是否正确

文件监控不工作

• 检查 OBSIDIAN_PATH 是否正确设置
• 确保路径是绝对路径
• 检查文件权限

向量搜索返回空结果

• 确保已完成初始全量扫描（查看日志）
• 检查 LanceDB 数据库中是否有数据
• 验证文件是否被正确索引

编译错误

• 确保已安装所有依赖: npm install
• 检查 TypeScript 版本: npm list typescript
• 清理并重新编译:

  # Windows
  rmdir /s /q dist
  npm run build
  
  # macOS/Linux
  rm -rf dist
  npm run build
  

📁 项目结构

Obsidian-Lumina-MCP/
├── src/
│   └── index.ts              # 主程序文件
├── dist/                     # 编译输出目录
├── .lancedb/                 # LanceDB 数据库目录（自动创建）
├── .env                      # 环境变量配置（需要创建）
├── .env.example              # 环境变量示例
├── scripts/                  # 测试脚本
│   ├── test-basic.ts        # 基础功能测试
│   └── test-server.ts       # 服务器功能测试
├── package.json
├── tsconfig.json
└── README.md

🧪 开发

开发模式

使用 tsx 直接运行（无需编译，支持热重载）:

npm run dev

生产模式

1. 编译 TypeScript:

   npm run build
   

2. 运行编译后的代码:

   npm start
   

测试

# 基础功能测试
npm run test:basic

# 服务器功能测试
npm run test:server

📚 相关文档

• USAGE_GUIDE.md - 详细使用指南
• MCP_TEST_GUIDE.md - MCP Inspector 测试指南
• VERIFICATION.md - 验证检查清单
• QUICK_TEST.md - 快速测试指南

📄 许可证

ISC

🤝 贡献

欢迎提交 Issue 和 Pull Request！

🙏 致谢

• Model Context Protocol - MCP 协议规范
• Ollama - 本地 LLM 和嵌入模型
• LanceDB - 向量数据库
• Cline - VS Code AI 编程助手

---

让 Lumina 为您的知识库带来智能搜索的"光"！ ✨