smart-connections

Smart Connections MCP Server

Smart Connections 向けのセキュリティを最優先した MCP サーバーです。読み取り専用です。パスを検証します。監査可能です。

Smart Connections の埋め込みを Claude Code やその他の MCP クライアントに公開し、Obsidian の保管庫をセマンティック検索できるようにします。

開発の背景

Claude Code から Obsidian の保管庫をセマンティック検索する必要がありました。既存の選択肢には、次のような問題があります。

• パス検証がない - ユーザー入力がファイル操作に直接渡されます
• 書き込みアクセス - 不要な変更用ツールを公開するものがあります
• 依存関係が重い - 実質的にはベクトル演算である処理に、PyTorch/transformers が必要です

この実装の特徴：

• 依存関係を最小限に抑制 - MCP SDK + Transformers.js（テキスト検索用）
• フェイルクローズのセキュリティ - realpath によるパス検証、シンボリックリンクの検出
• 監査可能 - 実際に読める小規模な TypeScript コードベース

機能

• テキスト検索 - ノートのパスだけでなく、プレーンテキストで検索できます
• セマンティック検索 - Smart Connections の埋め込みを使用します
• ローカル推論 - Transformers.js を使用します（Smart Connections と同じモデル）
• 読み取り専用 - 書き込み操作やシェル実行はありません
• セキュア - 厳格なパス検証と、サイズに上限を設けたレスポンス
• オフライン - Obsidian を起動していなくても動作します

セキュリティモデル

項目	保証
パスの制限	すべてのファイルアクセスを保管庫のルートに照らして検証します
トラバーサル防止	../ とシンボリックリンクを利用した攻撃をブロックします
読み取り専用	書き込み操作は公開されません
レスポンスの制限	結果数（50）、コンテンツの長さ（10KB）に上限を設けます
フェイルクローズ	エラーが発生した場合はアクセスを拒否し、決して回避しません
監査ログ	セキュリティイベントをコンテキストとともに記録します

インストール

前提条件

• Node.js 18+
• Smart Connections プラグインをインストールした Obsidian
• 埋め込みの作成（Obsidian で保管庫を開き、Smart Connections にインデックスを作成させます）

セットアップ

git clone https://github.com/gogogadgetbytes/smart-connections-mcp
cd smart-connections-mcp
npm install
npm run build

Claude Code の設定

Claude Code の設定に追加します。

claude mcp add smart-connections \
  -e VAULT_PATH="/path/to/your/obsidian/vault" \
  -- node /path/to/smart-connections-mcp/dist/index.js

または、~/.claude.json に手動で追加します。

{
  "mcpServers": {
    "smart-connections": {
      "command": "node",
      "args": ["/path/to/smart-connections-mcp/dist/index.js"],
      "env": {
        "VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

サーバーを読み込むには、Claude Code を再起動してください。

使い方

設定が完了すると、Claude Code で次のツールを使用できます。

テキストで検索

"Search my vault for notes about backup strategies"
→ Uses search_by_text tool

類似ノートを検索

"Find notes similar to Topics/Claude_Code.md"
→ Uses search_similar tool

ノートの内容を取得

"Show me the content of Topics/Obsidian.md"
→ Uses get_note tool

インデックス済みのノートを一覧表示

"What notes are indexed in my vault?"
→ Uses list_indexed tool

ツール

ツール	説明
search_by_text	フリーフォームのテキストで検索します（埋め込みをローカルで計算します）
search_similar	指定したノートとセマンティックに類似するノートを検索します
search_by_embedding	生の埋め込みベクトルを使って検索します
get_note	特定のノートの内容を取得します（パスを検証します）
get_model_info	埋め込みモデルの設定を取得します
list_indexed	インデックス済みのノートをすべて一覧表示します

設定

変数	必須	説明
VAULT_PATH	はい	Obsidian の保管庫への絶対パス

制限事項

• 保管庫は1つ - MCP サーバーのインスタンスごとに保管庫を1つ設定します
• Smart Connections のインデックスを使用 - ノートの埋め込みはプラグインから取得し、テキストクエリの埋め込みはローカルで計算します
• 書き込みアクセスなし - 仕様です。編集には Obsidian を使用してください
• 初回実行時にモデルをダウンロード - 約50MBのモデルを ~/.cache/huggingface/ にキャッシュします

開発

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

コントリビューション

CONTRIBUTING.md をご覧ください。セキュリティに重点を置いた PR を歓迎します。

セキュリティ

セキュリティ上の脆弱性を報告する場合は、[email protected] までメールでご連絡ください。セキュリティ上の懸念について、公開の issue は作成しないでください。

ライセンス

MIT - LICENSE をご覧ください

クレジット

• Brian Petro による Smart Connections
• Anthropic による Model Context Protocol