Typescript MCP Server with Obsidian Integration

Obsidian 統合機能付き TypeScript MCP サーバー

Obsidian の保管庫を操作するためのコマンドラインインターフェースです。

前提条件

• Node.js 14.x 以降
• npm または yarn
• Obsidian の保管庫

セットアップ

1. リポジトリをクローンします
2. 依存関係をインストールします：

   npm install
   

3. プロジェクトのルートに、Obsidian の保管庫のパスを記載した .env ファイルを作成します：

   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. client ディレクトリに移動します：

   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 ファイルを dist ディレクトリ内の JavaScript にコンパイルします。

テストを実行する

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 の 3 つの主なコマンドを使用できます。

ノートを検索する

指定したテキストを含むノートを検索します：

# 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"}'