Typescript MCP Server with Obsidian Integration

支持 Obsidian 集成的 TypeScript MCP 服务

用于与 Obsidian 知识库交互的命令行界面。

前置条件

• Node.js 14.x 或更高版本
• npm 或 yarn
• 一个 Obsidian 知识库

设置

1. 克隆仓库
2. 安装依赖：

   npm install
   

3. 在项目根目录中创建 .env 文件，并填写 Obsidian 知识库路径：

   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 数据服务

应用包含一个用于提供 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 以开发模式启动应用；当你修改 src 目录中的任何 TypeScript 文件时，它会自动重启服务。

构建项目

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：Obsidian 知识库路径（必需）
• PORT：服务端口号（默认：3000）

在项目根目录中创建 .env 文件以设置这些变量：

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

项目结构

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

CLI 用法

开始使用

设置好环境后，你可以使用 CLI 工具与 Obsidian 知识库交互。该工具提供三个主要命令：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"}'