AI导哈

Obsidian集成CLI工具

一个用于与Obsidian知识库交互的命令行工具，提供搜索、列表和读取笔记的功能。

  • by johnbreau
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 johnbreau/mcp-server

使用说明

带有黑曜石集成的打字MCP服务器

用于与黑曜石保险库交互的命令行界面。

先决条件

  • Node.js 14.x或更高版本
  • npm或纱线
  • 黑曜石拱顶

设置

  1. 克隆存储库
  2. 安装依赖项：
    npm install
  3. 创建一个 .env 项目根目录中具有Obsidian vault路径的文件：
    OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault

发展

启动和停止服务

启动所有服务

要同时启动后端、前端和健康数据服务器：

# From the project root directory
npm run dev

这将开始：

  • 后端服务器（默认值：http://localhost:3000)
  • 前端开发服务器（默认：http://localhost:5173)
  • 健康数据服务器（默认值：http://localhost:8000)

停止所有服务

要停止所有正在运行的服务，请执行以下操作：

# From the project root directory
npm run stop

手动服务管理

后端服务器

# Start backend server
cd server
npm run dev

前端开发服务器

  1. 导航到客户端目录：

    cd client

  2. 安装依赖项（如果尚未安装）：

    npm install

  3. 启动开发服务器：

    npm run dev

该应用程序将在 http://localhost:5173 默认情况下。

苹果健康数据服务器

该应用程序包括一个服务器，用于提供Apple Health数据。按照以下步骤进行设置：

  1. 确保您已安装Python 3.8+
  2. 安装所需的Python包：
    pip install -r requirements.txt
  3. 启动服务器：
    python server/main.py

服务器将于启动 http://localhost:8000 默认情况下。

API终点

  • GET / -列出appleHealthData目录中的所有文件和目录
  • GET /file/{path} -获取文件内容或列出目录内容
  • GET /docs -交互式API文档（Swagger UI）
  • GET /redoc -API替代文件（ReDoc）

有关更多详细信息，请参阅 APPLE_HEALTH_SERVER.md.

可用脚本

这个项目包括几个npm脚本来帮助开发和测试：

启动服务器应用程序

npm start

使用启动应用程序 ts-node。服务器将在 http://localhost:3000 默认情况下（或环境变量中指定的端口）。

自动重载开发模式

npm run dev

使用以下命令以开发模式启动应用程序 nodemon，当您对中的任何TypeScript文件进行更改时，它会自动重新启动服务器 src 目录。

构建项目

npm run build

将TypeScript文件编译为JavaScript dist 目录。

运行测试

npm test

运行测试套件（当前未配置任何测试）。

运行CLI工具

# Run the CLI tool directly
npm run cli [command]

# Examples:
npm run cli list
npm run cli search "query"
npm run cli read "path/to/note.md"

环境变量

应用程序使用以下环境变量：

  • OBSIDIAN_VAULT_PATH：黑曜石保险库路径（必填）
  • PORT：服务器的端口号（默认值：3000）

创建一个 .env 在项目根目录下的文件中设置这些变量：

OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault
PORT=3000

项目结构

  • src/ -源代码
    • tools/ -MCP工具实现
      • obsidian.ts -黑曜石保险库集成
    • index.ts -主要应用入口点
    • router.ts -API路由定义
    • types.ts -TypeScript类型定义
  • dist/ -编译的JavaScript（运行时创建 npm run build)
  • test-obsidian.ts -黑曜石工具测试脚本
  • src/cli.ts -命令行界面

CLI使用情况

入门指南

设置环境后，您可以使用CLI工具与Obsidian vault进行交互。该工具提供三个主要命令： search, list，以及 read.

搜索笔记

搜索包含特定文本的笔记：

# Basic search
npm run cli search "search query"

# Limit the number of results (default: 5)
npm run cli search "search query" -- --limit 10

# Example: Search for notes about "project management"
npm run cli search "project management"

输出示例：

Searching for "project management" (max 5 results)...

1. Project Management Best Practices
  Path: 01_Projects/Project Management Best Practices.md
  Modified: 5/25/2025, 2:30:45 PM
  Size: 12 KB
  Project management is the practice of...

2. Team Meeting Notes
  Path: 02_Meetings/Team Meeting Notes.md
  Modified: 5/26/2025, 10:15:22 AM
  Size: 8 KB
  Discussed project management tools and...

在目录中列出注释

列出特定目录中的所有笔记：

# List notes in the root directory
npm run cli list

# List notes in a specific directory
npm run cli list "00_Slipbox"

# Limit the number of results (default: 10)
npm run cli list "00_Slipbox" -- --limit 5

# Example: List all notes in the "Projects" directory
npm run cli list "01_Projects"

输出示例：

Listing notes in "01_Projects" (max 10 results)...

Directory: 01_Projects
Total files: 15

1. Project Alpha
  Path: 01_Projects/Project Alpha.md
  Modified: 5/20/2025, 3:45:12 PM
  Size: 5 KB

2. Project Beta
  Path: 01_Projects/Project Beta.md
  Modified: 5/22/2025, 9:15:33 AM
  Size: 3 KB

阅读特定注释

查看特定注释的内容：

# Read a note by its path relative to your vault root
npm run cli read "00_Slipbox/MyNote.md"

# Example: Read a note from a subdirectory
npm run cli read "01_Projects/Project Alpha/Meeting Notes.md"

输出示例：

Reading note: 00_Slipbox/MyNote.md

My Note Title
Path: 00_Slipbox/MyNote.md
Modified: 5/26/2025, 11:00:00 AM
Size: 2 KB

--- CONTENT ---

# My Note

This is the content of my note...

- List item 1
- List item 2
- List item 3

--- END OF CONTENT ---

全局安装（可选）

为了便于访问，您可以全局安装CLI：

# From the project directory
npm link

# Now you can use it from anywhere
obsidian-cli list
obsidian-cli search "query"
obsidian-cli read "path/to/note.md"

API终点

如果您更喜欢直接使用HTTP API：

搜索笔记

curl -X POST http://localhost:3000/api/tools/obsidian/search \
  -H "Content-Type: application/json" \
  -d '{"query": "project", "limit": 5}'

在目录中列出笔记

curl -X POST http://localhost:3000/api/tools/obsidian/list \
  -H "Content-Type: application/json" \
  -d '{"directory": "00_Slipbox", "limit": 10}'

阅读特定注释

curl -X POST http://localhost:3000/api/tools/obsidian/read \
  -H "Content-Type: application/json" \
  -d '{"filePath": "00_Slipbox/SomeNote.md"}'

相关 MCP