Local Faiss MCP

🚀 Local FAISS MCP Server

Local FAISS MCP Serverは、Retrieval-Augmented Generation (RAG) アプリケーション向けにFAISSを使用してローカルベクトルデータベース機能を提供する、Model Context Protocol (MCP) サーバーです。これにより、外部依存なしで効率的な類似性検索が可能になります。

✨ 主な機能

コア機能

• ローカルベクトルストレージ：外部依存なしでFAISSを使用して効率的な類似性検索を行います。
• ドキュメント取り込み：ドキュメントを自動的にチャンク化し、埋め込みを行って保存します。
• 意味検索：文の埋め込みを使用して自然言語でドキュメントを検索します。
• 永続的なストレージ：インデックスとメタデータはディスクに保存されます。
• MCP互換性：任意のMCP互換のAIエージェントまたはクライアントと連携可能です。

v0.2.0のハイライト

• CLIツール：local-faiss コマンドで、スタンドアロンのインデックス作成と検索が可能です。
• ドキュメント形式：PDF/TXT/MDはネイティブでサポート、DOCX/HTML/EPUBはpandocを使用してサポートします。
• 再ランキング：2段階の検索と再ランキングにより、より良い結果を得ることができます。
• カスタム埋め込み：任意のHugging Face埋め込みモデルを選択できます。
• MCPプロンプト：回答抽出と要約用の組み込みプロンプトが用意されています。

🚀 クイックスタート

# インストール
pip install local-faiss-mcp

# ドキュメントのインデックス作成
local-faiss index document.pdf

# 検索
local-faiss search "What is this document about?"

または、Claude Codeで使用する場合は、MCPクライアントを設定し（MCPクライアントとの設定を参照）、以下を試してみてください。

Use the ingest_document tool with: ./path/to/document.pdf
Then use query_rag_store to search for: "How does FAISS perform similarity search?"

Claudeは、ベクトルストアから関連するドキュメントチャンクを取得し、それを使用して質問に回答します。

📦 インストール

⚡️ アップグレードする場合：pip install --upgrade local-faiss-mcp を実行してください。

PyPIからのインストール（推奨）

pip install local-faiss-mcp

オプション：拡張形式のサポート

DOCX、HTML、EPUB、および40以上の追加形式をサポートするには、pandocをインストールします。

# macOS
brew install pandoc

# Linux
sudo apt install pandoc

# または、https://pandoc.org/installing.html からダウンロード

注意：PDF、TXT、およびMDはpandocなしで動作します。

ソースからのインストール

git clone https://github.com/nonatofabio/local_faiss_mcp.git
cd local_faiss_mcp
pip install -e .

💻 使用例

サーバーの起動

インストール後、サーバーを3つの方法で起動できます。

1. インストールされたコマンドを使用する（最も簡単）：

local-faiss-mcp --index-dir /path/to/index/directory

2. Pythonモジュールとして：

python -m local_faiss_mcp --index-dir /path/to/index/directory

3. 開発/テスト用：

python local_faiss_mcp/server.py --index-dir /path/to/index/directory

コマンドライン引数：

• --index-dir：FAISSインデックスとメタデータファイルを保存するディレクトリ（デフォルト：カレントディレクトリ）
• --embed：Hugging Face埋め込みモデル名（デフォルト：all-MiniLM-L6-v2）
• --rerank：指定されたクロスエンコーダーモデルで再ランキングを有効にする（デフォルト：BAAI/bge-reranker-base）

カスタム埋め込みモデルの使用：

# より大きく、精度の高いモデルを使用
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2

# 多言語モデルを使用
local-faiss-mcp --index-dir ./.vector_store --embed paraphrase-multilingual-MiniLM-L12-v2

# 任意のHugging Face sentence-transformersモデルを使用
local-faiss-mcp --index-dir ./.vector_store --embed sentence-transformers/model-name

再ランキングを使用してより良い結果を得る：

再ランキングは、クロスエンコーダーモデルを使用してFAISSの結果を再並べ替えし、関連性を向上させます。この2段階の「検索と再ランキング」アプローチは、本番環境の検索システムで一般的です。

# デフォルトのモデル（BAAI/bge-reranker-base）で再ランキングを有効にする
local-faiss-mcp --index-dir ./.vector_store --rerank

# 特定の再ランキングモデルを使用
local-faiss-mcp --index-dir ./.vector_store --rerank cross-encoder/ms-marco-MiniLM-L-6-v2

# カスタム埋め込みと再ランキングを組み合わせる
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2 --rerank BAAI/bge-reranker-base

再ランキングの仕組み：

1. FAISSが上位の候補を取得します（要求された数の10倍）。
2. クロスエンコーダーが各候補をクエリに対してスコア付けします。
3. 結果が関連性スコアで再並べ替えされます。
4. 最も関連性の高い上位k件の結果が返されます。

人気の再ランキングモデル：

• BAAI/bge-reranker-base - バランスが良い（デフォルト）
• cross-encoder/ms-marco-MiniLM-L-6-v2 - 高速で効率的
• cross-encoder/ms-marco-TinyBERT-L-2-v2 - 非常に高速で、小さいモデル

サーバーは以下のことを行います：

• インデックスディレクトリが存在しない場合は作成します。
• {index-dir}/faiss.index から既存のFAISSインデックスを読み込みます（または新しく作成します）。
• {index-dir}/metadata.json からドキュメントメタデータを読み込みます（または新しく作成します）。
• stdin/stdoutを介してMCPツール呼び出しを待機します。

利用可能なツール

サーバーは、ドキュメント管理用の2つのツールを提供します。

1. ingest_document

ベクトルストアにドキュメントを取り込みます。

パラメータ：

• document（必須）：取り込むテキスト内容またはファイルパス
• source（オプション）：ドキュメントソースの識別子（デフォルト："unknown"）

自動検出：document がファイルパスのように見える場合、自動的に解析されます。

サポートされる形式：

• ネイティブ：TXT、MD、PDF
• pandoc付き：DOCX、ODT、HTML、RTF、EPUB、および40以上の形式

例：

{
  "document": "FAISS is a library for efficient similarity search...",
  "source": "faiss_docs.txt"
}

{
  "document": "./documents/research_paper.pdf"
}

2. query_rag_store

ベクトルストアから関連するドキュメントチャンクを検索します。

パラメータ：

• query（必須）：検索クエリのテキスト
• top_k（オプション）：返す結果の数（デフォルト：3）

例：

{
  "query": "How does FAISS perform similarity search?",
  "top_k": 5
}

利用可能なプロンプト

サーバーは、検索されたドキュメントから回答を抽出し、情報を要約するためのMCPプロンプトを提供します。

1. extract-answer

検索されたドキュメントチャンクから最も関連性の高い回答を適切な引用付きで抽出します。

引数：

• query（必須）：元のユーザークエリまたは質問
• chunks（必須）：検索されたドキュメントチャンクのJSON配列（text、source、distance フィールドを含む）

ユースケース：RAGストアを検索した後、このプロンプトを使用して、ソースを引用し、関連性を説明する適切にフォーマットされた回答を取得します。

Claudeでの例のワークフロー：

1. query_rag_store ツールを使用して関連するチャンクを検索します。
2. クエリと結果を使用して extract-answer プロンプトを使用します。
3. 引用付きの包括的な回答を取得します。

2. summarize-documents

複数のドキュメントチャンクから焦点を絞った要約を作成します。

引数：

• topic（必須）：要約するトピックまたはテーマ
• chunks（必須）：要約するドキュメントチャンクのJSON配列
• max_length（オプション）：要約の最大単語数（デフォルト：200）

ユースケース：複数の検索されたドキュメントからの情報を簡潔な要約に合成します。

使用例：

Claude Codeで query_rag_store を使用してドキュメントを検索した後、以下のようにプロンプトを使用できます。

Use the extract-answer prompt with:
- query: "What is FAISS?"
- chunks: [the JSON results from query_rag_store]

これらのプロンプトは、LLMにベクトルストアのデータに基づいて構造化された、引用付きの回答を提供するように誘導します。

コマンドラインインターフェイス

local-faiss CLIは、スタンドアロンのドキュメントインデックス作成と検索機能を提供します。

インデックスコマンド

コマンドラインからドキュメントのインデックスを作成します。

# 単一ファイルのインデックス作成
local-faiss index document.pdf

# 複数ファイルのインデックス作成
local-faiss index doc1.pdf doc2.txt doc3.md

# フォルダ内のすべてのファイルのインデックス作成
local-faiss index documents/

# 再帰的にインデックス作成
local-faiss index -r documents/

# グロブパターンでインデックス作成
local-faiss index "docs/**/*.pdf"

設定：CLIは自動的に以下からMCP設定を使用します。

1. ./.mcp.json（ローカル/プロジェクト固有）
2. ~/.claude/.mcp.json（Claude Code設定）
3. ~/.mcp.json（フォールバック）

設定が存在しない場合は、デフォルト設定（./.vector_store）で ./.mcp.json を作成します。

サポートされる形式：

• ネイティブ：TXT、MD、PDF（常に利用可能）
• pandoc付き：DOCX、ODT、HTML、RTF、EPUBなど
  • インストール：brew install pandoc（macOS）または apt install pandoc（Linux）

検索コマンド

インデックスされたドキュメントを検索します。

# 基本的な検索
local-faiss search "What is FAISS?"

# より多くの結果を取得
local-faiss search -k 5 "similarity search algorithms"

結果には以下が表示されます：

• ソースファイルパス
• FAISS距離スコア
• 再ランキングスコア（MCP設定で有効にされている場合）
• テキストプレビュー（最初の300文字）

CLIの特徴

• ✅ 増分インデックス作成：既存のインデックスに追加し、上書きしません。
• ✅ 進捗出力：各ファイルのインデックス作成進捗を表示します。
• ✅ 共有設定：MCPサーバーと同じ設定を使用します。
• ✅ 自動検出：グロブパターンと再帰的なフォルダをサポートします。
• ✅ 形式サポート：PDF、TXT、MDをネイティブで処理し、DOCX+はpandocで処理します。

MCPクライアントとの設定

Claude Code

このサーバーをClaude CodeのMCP設定（.mcp.json）に追加します。

ユーザー全体の設定（~/.claude/.mcp.json）：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp"
    }
  }
}

カスタムインデックスディレクトリを使用する場合：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "/home/user/vector_indexes/my_project"
      ]
    }
  }
}

カスタム埋め込みモデルを使用する場合：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--embed",
        "all-mpnet-base-v2"
      ]
    }
  }
}

再ランキングを有効にする場合：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--rerank"
      ]
    }
  }
}

埋め込みと再ランキングを含む完全な設定：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--embed",
        "all-mpnet-base-v2",
        "--rerank",
        "BAAI/bge-reranker-base"
      ]
    }
  }
}

プロジェクト固有の設定（プロジェクト内の ./.mcp.json）：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store"
      ]
    }
  }
}

代替案：Pythonモジュールを使用する場合（コマンドがPATHにない場合）：

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "python",
      "args": ["-m", "local_faiss_mcp", "--index-dir", "./.vector_store"]
    }
  }
}

Claude Desktop

このサーバーをClaude Desktopの設定に追加します。

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": ["--index-dir", "/path/to/index/directory"]
    }
  }
}

🔧 技術詳細

• 埋め込みモデル：--embed フラグで構成可能（デフォルト：384次元の all-MiniLM-L6-v2）
  • 任意のHugging Face sentence-transformersモデルをサポート
  • 埋め込み次元を自動検出
  • モデルの選択はインデックスとともに保存される
• インデックスタイプ：正確なL2距離検索用のFAISS IndexFlatL2
• チャンキング：ドキュメントは約500語のチャンクに分割され、50語のオーバーラップがあります。
• ストレージ：インデックスは faiss.index として保存され、メタデータは metadata.json として保存されます。

埋め込みモデルの選択

異なるモデルは異なるトレードオフを提供します。

重要：特定のモデルでインデックスを作成した後は、以降の実行で同じモデルを使用する必要があります。サーバーは次元の不一致を検出し、警告を表示します。

開発

スタンドアロンテスト

MCPインフラストラクチャなしでFAISSベクトルストア機能をテストします。

source venv/bin/activate
python test_standalone.py

このテストでは：

• ベクトルストアを初期化します。
• サンプルドキュメントを取り込みます。
• 意味検索クエリを実行します。
• 永続性と再読み込みをテストします。
• テストファイルをクリーンアップします。

単体テスト

完全なテストスイートを実行します。

pytest tests/ -v

特定のテストファイルを実行します。

# 埋め込みモデル機能をテスト
pytest tests/test_embedding_models.py -v

# スタンドアロンの統合テストを実行
python tests/test_standalone.py

テストスイートには以下が含まれます：

• test_embedding_models.py：カスタム埋め込みモデル、次元検出、および互換性の包括的なテスト
• test_standalone.py：MCPインフラストラクチャなしのエンドツーエンドの統合テスト

📄 ライセンス

MIT