Obsidian Semantic MCP

🚀 Obsidian Semantic MCP Server

Obsidian用のセマンティックでAI最適化されたMCPサーバーです。20のツールを5つのインテリジェントな操作に統合し、コンテキストに基づくワークフローヒントを提供します。

🎉 素敵なニュース！ このプロジェクトで得た知見を活かして、さらに良いものを作りました！新しいObsidian MCP Pluginをチェックしてみてください。これは、Obsidian内で直接動作するネイティブプラグインで、パフォーマンスが向上し、セットアップが簡単になり、機能も強化されています。是非試してみてください！

🚀 新しいネイティブプラグインを試してみましょう！

このMCPサーバーを通じて、ObsidianとAIを統合する上での貴重な教訓を得ました。これらの知見を活かして、Obsidian MCP Plugin を作成しました。このプラグインは以下の特長を備えています。

• ネイティブ統合：Obsidian内で直接動作します（外部依存が不要です！）
• パフォーマンス向上：REST APIのオーバーヘッドなしで直接ボールトにアクセスできます
• セットアップ容易：他のObsidianプラグインと同じようにインストールできます - APIキーや外部サーバーは不要です
• 機能強化：Obsidianの内部APIと検索機能を完全に利用できます
• 信頼性向上：接続問題やタイムアウトがなくなります

👉 Obsidian MCP Pluginを入手する

🚀 クイックスタート

前提条件

• コンピューターにObsidianがインストールされていること
• ObsidianボールトにLocal REST APIプラグインがインストールされていること
• Claude Desktopアプリがインストールされていること

インストール

npm install -g obsidian-semantic-mcp

または、npxを直接使用することをおすすめします（推奨）：

npx obsidian-semantic-mcp

npmでの表示：https://www.npmjs.com/package/obsidian-semantic-mcp

手順

1. Obsidianプラグインのインストール：

   • Obsidianの設定 → コミュニティプラグインを開きます。
   • "Local REST API"を検索してインストールします。
   • Local REST APIプラグインを有効にします。
   • プラグインの設定で、APIキーをコピーします（設定に必要です）。

2. Claude Desktopの設定：

   npxコマンドはClaude Desktopの設定で自動的に使用されます。Claude Desktopの設定ファイル（macOSでは通常~/Library/Application Support/Claude/claude_desktop_config.jsonにあります）に以下を追加します。

   {
     "mcpServers": {
       "obsidian": {
         "command": "npx",
         "args": ["-y", "obsidian-semantic-mcp"],
         "env": {
           "OBSIDIAN_API_KEY": "your-api-key-here",
           "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
           "OBSIDIAN_VAULT_NAME": "your-vault-name"
         }
       }
     }
   }
   

✨ 主な機能

このサーバーは、従来のMCPツールをAI最適化されたセマンティックインターフェイスに統合し、AIエージェントがObsidianの操作を効果的に理解して使用できるようにします。

主な利点

• インターフェイスの簡素化：21以上の個別ツールの代わりに5つのセマンティック操作
• コンテキストワークフロー：インテリジェントなヒントがAIエージェントに次の論理的なアクションを案内します
• 状態追跡：トークンベースのシステムが無効な操作を防止します
• エラー回復：操作が失敗したときにスマートな回復ヒントを提供します
• ファジーマッチング：わずかな変動を処理する弾力的なテキスト編集
• フラグメント検索：大きなファイルから関連するセクションを自動的に返してトークンを節約します

セマンティック操作の理由

従来のMCPサーバーは多数の細かいツール（20以上）を公開しており、AIエージェントを圧倒し、非効率的なツール選択につながる可能性があります。私たちのセマンティックアプローチは以下のようなものです。

• 意図に基づいて20のツールを5つのセマンティック操作に統合
• 次のアクションを案内するコンテキストワークフローヒントを提供
• ペトリネットに触発されたトークンで状態を追跡して無意味な提案を防止
• 操作が失敗したときに回復ヒントを提供

5つのセマンティック操作

1. vault - ファイルとフォルダの操作

   • アクション: list, read, create, update, delete, search, fragments

2. edit - スマートなコンテンツ編集

   • アクション: window (ファジーマッチ), append, patch, at_line, from_buffer

3. view - コンテンツの表示とナビゲーション

   • アクション: window (コンテキスト付き), open_in_obsidian

4. workflow - ガイド付きの提案を取得

   • アクション: suggest

5. system - システム操作

   • アクション: info, commands, fetch_web
   • 注意: fetch_webはウェブコンテンツを取得してMarkdownに変換します（urlパラメータのみ使用）

使用例

get_vault_file, get_active_file, read_file_contentなどから選ぶ代わりに、次のように簡単に使用できます。

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "daily-notes/2024-01-15.md"
  }
}

レスポンスにはインテリジェントなワークフローヒントが含まれます。

{
  "result": { /* ファイル内容 */ },
  "workflow": {
    "message": "Read file: daily-notes/2024-01-15.md",
    "suggested_next": [
      {
        "description": "Edit this file",
        "command": "edit(action='window', path='daily-notes/2024-01-15.md', ...)",
        "reason": "Make changes to content"
      },
      {
        "description": "Follow linked notes",
        "command": "vault(action='read', path='{linked_file}')",
        "reason": "Explore connected knowledge"
      }
    ]
  }
}

状態認識型提案

システムはコンテキストトークンを追跡して関連する提案を提供します。

• [[links]]が含まれるファイルを読んだ後は、それらのリンクを辿ることを提案します
• 編集が失敗した後は、バッファ回復オプションを提供します
• 検索後は、結果を絞り込むか読むことを提案します

高度な機能

コンテンツバッファリング

window編集アクションは、編集を試みる前に新しいコンテンツを自動的にバッファリングします。編集が失敗した場合や、内容を調整したい場合は、バッファから取得できます。

{
  "operation": "edit",
  "action": "from_buffer",
  "params": {
    "path": "notes/meeting.md"
  }
}

ファジーウィンドウ編集

セマンティックエディタはファジーマッチングを使用してコンテンツを検索および置換します。

{
  "operation": "edit",
  "action": "window",
  "params": {
    "path": "daily/2024-01-15.md",
    "oldText": "meting notes",  // タイポもファジーマッチされます
    "newText": "meeting notes",
    "fuzzyThreshold": 0.8
  }
}

スマートPATCH操作

特定のドキュメント構造を対象とすることができます。

{
  "operation": "edit",
  "action": "patch",
  "params": {
    "path": "projects/todo.md",
    "operation": "append",
    "targetType": "heading",
    "target": "## In Progress",
    "content": "- [ ] New task"
  }
}

大規模ドキュメントのフラグメント検索

システムはファイルを読み取る際に自動的にインテリジェントなフラグメント検索を使用し、関連性を維持しながらトークン消費を大幅に削減します。

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "large-document.md"
  }
}

ファイル全体ではなく関連するフラグメントを返します。

{
  "result": {
    "content": [
      {
        "id": "file:large-document.md:frag0",
        "content": "Most relevant section...",
        "score": 0.95,
        "lineStart": 145,
        "lineEnd": 167
      }
    ],
    "fragmentMetadata": {
      "totalFragments": 5,
      "strategy": "adaptive",
      "originalContentLength": 135662
    }
  }
}

フラグメント検索戦略：

• adaptive - TF-IDFキーワードマッチング（短いクエリのデフォルト）
• proximity - クエリ用語が近くに出現するフラグメントを検索
• semantic - ドキュメントを意味のあるセクションに分割

ボールト全体でフラグメントを明示的に検索することができます。

{
  "operation": "vault",
  "action": "fragments",
  "params": {
    "query": "project roadmap timeline",
    "maxFragments": 10,
    "strategy": "proximity"
  }
}

必要に応じてファイル全体を取得するには、次のようにします。

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "document.md",
    "returnFullFile": true
  }
}

ワークフロー例

日次ノートワークフロー

1. 今日のノートを作成 → 2. テンプレートを追加 → 3. 昨日のノートをリンク

調査ワークフロー

1. トピックを検索 → 2. 結果を読む → 3. 総合ノートを作成 → 4. ソースをリンク

リファクタリングワークフロー

1. すべての言及を検索 → 2. リンクを更新 → 3. ノートをリネーム/マージ

設定

セマンティックワークフローヒントはsrc/config/workflows.jsonで定義されており、ワークフローの好みに合わせてカスタマイズできます。

フラグメント検索設定

フラグメント検索システムは、ファイルを読み取る際に自動的にアクティブになり、トークンを節約します。この動作を制御することができます。

• デフォルトの動作：ファイルを読み取るときに最大5つの関連するフラグメントを返します
• ファイル全体のアクセス：returnFullFile: trueパラメータを使用して完全なコンテンツを取得します
• 戦略選択：システムはクエリの長さに基づいて自動的に選択するか、指定することができます
  • adaptive キーワードマッチング（短いクエリのデフォルト）
  • proximity クエリ用語が近くに出現するフラグメントを検索
  • semantic ドキュメントを意味のあるセクションに分割

エラー回復

操作が失敗したとき、セマンティックインターフェイスはインテリジェントな回復ヒントを提供します。

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File not found: daily/2024-01-15.md",
    "recovery_hints": [
      {
        "description": "Create this file",
        "command": "vault(action='create', path='daily/2024-01-15.md')"
      },
      {
        "description": "Search for similar files",
        "command": "vault(action='search', query='2024-01-15')"
      }
    ]
  }
}

環境変数

サーバーは、存在する場合は.envファイルから環境変数を自動的に読み込みます。変数は以下の優先順位で設定できます。

1. 既存の環境変数（最も高い優先度）
2. 現在の作業ディレクトリの.envファイル
3. サーバーディレクトリの.envファイル

必要な変数：

• OBSIDIAN_API_KEY - Local REST APIプラグインからのAPIキー

オプションの変数：

• OBSIDIAN_API_URL - API URL（デフォルト: https://localhost:27124）
  • HTTP（ポート27123）とHTTPS（ポート27124）の両方をサポート
  • HTTPSは自己署名証明書を使用し、自動的に受け入れられます
• OBSIDIAN_VAULT_NAME - コンテキスト用のボールト名

.envファイルの例：

OBSIDIAN_API_KEY=your-api-key-here
OBSIDIAN_API_URL=http://127.0.0.1:27123
OBSIDIAN_VAULT_NAME=MyVault

PATCH操作

PATCH操作（patch_active_fileとpatch_vault_file）は、高度なコンテンツ操作を可能にします。

• ターゲットタイプ：

  • heading："Heading 1::Subheading"のようなパスを使用して特定の見出しの下のコンテンツをターゲットにします
  • block：特定のブロック参照をターゲットにします
  • frontmatter：フロントマターフィールドをターゲットにします

• 操作：

  • append：ターゲットの後にコンテンツを追加します
  • prepend：ターゲットの前にコンテンツを追加します
  • replace：ターゲットのコンテンツを置き換えます

例：特定の見出しの下にコンテンツを追加する

{
  "operation": "append",
  "targetType": "heading",
  "target": "Daily Notes::Today",
  "content": "- New task added"
}

開発

# クローンしてインストール
git clone https://github.com/aaronsb/obsidian-semantic-mcp.git
cd obsidian-semantic-mcp
npm install

# 開発モード
npm run dev

# テスト
npm test              # すべてのテストを実行
npm run test:coverage # カバレッジレポート付き

# ビルド
npm run build         # サーバーをビルド
npm run build:full    # テスト + ビルド

# 起動
npm start             # サーバーを起動

アーキテクチャ

セマンティックシステムは以下の部分で構成されています。

• Semantic Router (src/semantic/router.ts) - 操作をハンドラーにルーティングします
• State Tokens (src/semantic/state-tokens.ts) - コンテキスト状態を追跡します
• Workflow Config (src/config/workflows.json) - ヒントと提案を定義します
• Core Utilities (src/utils/) - ファイル読み取りやファジーマッチングなどの共有機能

テスト

プロジェクトには、セマンティックシステムの包括的なJestテストが含まれています。

npm test                    # すべてのテストを実行
npm test semantic-router    # ルーティングロジックをテスト
npm test semantic-tools     # 統合をテスト

既知の問題

• 検索機能：Obsidian Local REST APIプラグインのAPI制限により、大規模なボールトでの検索操作が時折タイムアウトすることがあります。

コントリビューション

コントリビューションは大歓迎です！興味のある分野は以下の通りです。

• workflows.jsonに追加のワークフローパターンを追加する
• 新しいセマンティック操作を追加する
• 状態追跡を強化する
• Obsidianプラグインとの統合を改善する

📄 ライセンス

MITライセンスの下で提供されています。