Obsidian MCP Server

🚀 Obsidian MCP サーバー

Obsidian MCP サーバーは、Model Context Protocol に基づく機能モジュールです。Obsidian のvault内で強力なファイルとコンテンツ管理機能を実現します。ツールリソースを呼び出すことで、複雑なテキスト処理とコンテンツ操作を実行できます。

🚀 クイックスタート

Obsidian MCP サーバーを使用するには、まずインストールと設定が必要です。以下に詳細な手順を説明します。

✨ 主な機能

ファイル管理

• ファイルの一覧表示
  vault内の指定ディレクトリまたはルートディレクトリにあるすべてのファイルを一覧表示します。

• ファイル内容の読み取り
  指定されたパスのファイル内容を返します。

• ファイルの作成/更新
  原子操作をサポートし、ファイルの書き込みプロセスを安全かつ確実に行います。

コンテンツ検索

• 簡単なテキスト検索
  指定されたファイル内でキーワードを検索し、そのコンテキストを返します。

• 複雑な検索（JsonLogic）
  カスタムの JsonLogic 式に基づいてファイルとディレクトリをフィルタリングします。

• タグ管理
  vaultまたは特定のディレクトリ内のすべてのタグ情報を取得します。

属性管理

• ファイル属性の照会
  指定されたファイルのメタデータ（タイトル、作者、タイプなど）を取得します。

• ファイル属性の更新
  カスタムフィールドの更新をサポートし、タイムスタンプフィールドを自動的に維持します。

📦 インストール

MCP サーバーのインストール

npm install obsidian-mcp-server

MCP サーバーの設定

1. package.json に以下の設定を追加します。

"mcp_server": {
  "vault_root": "./vault",  // vaultのルートディレクトリのパスを指定
  "port": 3001,             // オプション、デフォルトのポートは3001
  "log_level": "info"       // オプション、ログレベル：debug、info、warning、error
}

2. サーバーを起動します。

npm start

💻 使用例

基本的な使用法

ファイル管理

// ファイルの一覧表示
const result = await client.call("obsidian_list_files_in_dir", { dirpath: "./" });
console.log(result);

// ファイル内容の読み取り
const content = await client.call("obsidian_get_file_contents", { filepath: "notes/README.md" });
console.log(content);

コンテンツ検索

// 簡単なテキスト検索
const result = await client.call("obsidian_find_in_file", {
  filepath: "notes/index.md",
  query: "hello"
});
console.log(result);

// 複雑な検索（JsonLogic）
const result = await client.call("obsidian_complex_search", {
  query: "{ \"and\": [\n" +
         "  { \"glob\": [\"docs/*.md\", { \"var\": \"path\" } ] },\n" +
         "  { \"in\": [=\"#todo\", { \"var\": \"frontmatter.tags\" } ] }\n" +
         "] }"
});
console.log(result);

属性管理

// ファイル属性の照会
const metadata = await client.call("obsidian_get_file_metadata", { filepath: "notes/todo.md" });
console.log(metadata);

// ファイル属性の更新
const result = await client.call("obsidian_update_file_properties", {
  filepath: "notes/todo.md",
  properties: {
    priority: "high",
    due_date: "2024-03-15"
  }
});
console.log(result);

高度な使用法

自動ファイルアーカイブ

const { DateTime } = require('luxon');

async function archiveOldFiles() {
  const today = DateTime.local().toISODate();
  const files = await client.call("obsidian_list_files_in_dir", { dirpath: "./old" });
  
  for (const file of files) {
    if (file.lastModified < today) {
      await client.call("obsidian_move_file", {
        from_path: `old/${file.name}`,
        to_path: `archived/${today}/${file.name}`
      });
    }
  }
}

setInterval(archiveOldFiles, 86400000); // 毎日実行

コンテンツ自動分類

async function autoCategorize() {
  const files = await client.call("obsidian_list_files_in_dir", { dirpath: "./notes" });
  
  for (const file of files) {
    const content = await client.call("obsidian_get_file_contents", { filepath: `notes/${file.name}` });
    const category = getCategoryFromContent(content);
    
    if (category) {
      await client.call("obsidian_move_file", {
        from_path: `notes/${file.name}`,
        to_path: `${category}/${file.name}`
      });
    }
  }
}

setInterval(autoCategorize, 604800000); // 毎週実行

📚 ドキュメント

ツールインターフェイス

ファイル操作ツール

// vault内のすべてのファイルを一覧表示
obsidian_list_files_in_vault: {
}

// 指定ディレクトリ内のファイルを一覧表示
obsidian_list_files_in_dir: {
  dirpath: string; // vaultルートディレクトリからの相対パス
}

// ファイル内容を取得
obsidian_get_file_contents: {
  filepath: string; // vaultルートディレクトリからの相対パス
}

検索操作ツール

// ファイル内でテキストを検索し、コンテキストを返す
obsidian_find_in_file: {
  query: string,
  contextLength?: number  // デフォルトのコンテキスト長は10
}

// JsonLogic式を使用した複雑な検索
obsidian_complex_search: {
  query: JsonLogicQuery
  // 例：
  // タグで検索："{"in": ["#mytag", {"var": "frontmatter.tags"}]}"
  //
  // ディレクトリで検索："{"glob": ["docs/*.md", {"var": "path"}]}"
  //
  // 条件の組み合わせ："{"and": [
  //   {"glob": ["*.md", {"var": "path"}]},
  //   {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  // ]}"
}

コンテンツ修正ツール

// ファイルの末尾にコンテンツを追加
obsidian_append_content: {
  filepath: string,  // vaultルートディレクトリからの相対パス
  content: string    // 追加するコンテンツ
}

// ファイル内容を置き換える
obsidian_patch_content: {
  filepath: string,  // vaultルートディレクトリからの相対パス
  content: string    // 新しいコンテンツ
}

属性管理ツール

// ファイルのメタデータを取得
obsidian_get_file_metadata: {
  filepath: string   // vaultルートディレクトリからの相対パス
}

// ファイル属性を更新
obsidian_update_file_properties: {
  filepath: string,  // vaultルートディレクトリからの相対パス
  properties: {      // 更新する属性
    [key: string]: any
  }
}

ベストプラクティス

1. 設定管理
   vault_root とログレベルを正しく設定し、サーバーが正常に動作するようにします。
2. トランザクション制御
   ファイルの修正に関する操作では、トランザクションでラップすることをおすすめします。これにより、データの一貫性を確保できます。
3. 権限制御
   実際のニーズに応じてアクセス制御ポリシーを設定し、不正な操作を防止します。

リソース

• 公式ドキュメント
  Obsidian MCP Server ドキュメント
• サンプルコード
  GitHub サンプルリポジトリ

貢献ガイド

1. 問題のフィードバック
   問題やバグを発見した場合は、Issues に投稿してください。
2. 機能提案
   機能の拡張や最適化の提案を歓迎します。合理的な要求は真摯に検討します。
3. オープンソースへの貢献
   このプロジェクトは MIT ライセンスの下でオープンソース化されています。リポジトリを fork し、PR を送信して一緒にこのツールを改善しましょう。

よくある質問

1. 大きなファイルをどう処理するか？
   大きなファイルの場合は、ブロック単位で処理するか、ストリーミング転送を使用して効率を向上させることをおすすめします。
2. サーバーのパフォーマンスが不足している場合はどうするか？
   コードを最適化したり、メモリを増やしたり、より効率的なアルゴリズムを使用することでパフォーマンスを向上させることができます。単一のマシンで負荷を処理できない場合は、分散デプロイを検討してください。
3. データの一貫性をどう保証するか？
   ファイル操作を行う際は、トランザクションメカニズムを使用することをおすすめします。これにより、各操作が完全に成功するか、完全に失敗するかのいずれかになり、データの一貫性を維持できます。

🔧 技術詳細

Obsidian MCP サーバーは、Model Context Protocol を利用して Obsidian のvault内のファイルとコンテンツを管理します。サーバーは Node.js で構築されており、npm を通じてインストールできます。設定ファイルを通じて、vaultのルートディレクトリ、ポート、ログレベルなどを柔軟に設定できます。

📄 ライセンス

このプロジェクトは MIT ライセンスの下でオープンソース化されています。