Local FAISS MCP Server

ローカル FAISS MCP サーバー

Retrieval-Augmented Generation（RAG）アプリケーション向けに、FAISS を使用したローカルベクトルデータベース機能を提供する Model Context Protocol（MCP）サーバーです。

特長

主な機能

• ローカルベクトルストレージ：外部依存関係なしで効率的な類似度検索を行うために FAISS を使用します
• ドキュメントの取り込み：ドキュメントを自動的にチャンク分割し、ストレージ用の埋め込みを生成します
• セマンティック検索：文埋め込みを使用し、自然言語でドキュメントを検索できます
• 永続ストレージ：インデックスとメタデータをディスクに保存します
• MCP 互換：MCP 対応の AI エージェントまたはクライアントであれば、どれでも利用できます

v0.2.0 の主な特長

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

クイックスタート

# Install
pip install local-faiss-mcp

# Index documents
local-faiss index document.pdf

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

または、Claude Code と一緒に使う場合は、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

# Or download from: 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）

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

# Use a larger, more accurate model
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2

# Use a multilingual model
local-faiss-mcp --index-dir ./.vector_store --embed paraphrase-multilingual-MiniLM-L12-v2

# Use any Hugging Face sentence-transformers model
local-faiss-mcp --index-dir ./.vector_store --embed sentence-transformers/model-name

より良い結果を得るための再ランキングの使用：

再ランキングでは、クロスエンコーダーモデルを使用して FAISS の結果を並べ替え、関連性を高めます。この 2 段階の「検索して再ランキングする」方法は、実運用の検索システムで一般的です。

# Enable re-ranking with default model (BAAI/bge-reranker-base)
local-faiss-mcp --index-dir ./.vector_store --rerank

# Use a specific re-ranking model
local-faiss-mcp --index-dir ./.vector_store --rerank cross-encoder/ms-marco-MiniLM-L-6-v2

# Combine custom embedding and re-ranking
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（必須）：text、source、distance フィールドを含む JSON 配列形式の取得済みドキュメントチャンク

用途: 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 は、ドキュメントのインデックス作成と検索を単独で行う機能を提供します。

Index コマンド

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

# Index single file
local-faiss index document.pdf

# Index multiple files
local-faiss index doc1.pdf doc2.txt doc3.md

# Index all files in folder
local-faiss index documents/

# Index recursively
local-faiss index -r documents/

# Index with glob pattern
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）

Search コマンド

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

# Basic search
local-faiss search "What is FAISS?"

# Get more results
local-faiss search -k 5 "similarity search algorithms"

結果には次の情報が表示されます。

• ソースファイルのパス
• FAISS の距離スコア
• 再ランキングのスコア（MCP 設定で有効な場合）
• テキストのプレビュー（先頭 300 文字）

CLI の機能

• ✅ 増分インデックス作成：既存のインデックスに追加し、上書きしません
• ✅ 進捗の表示：各ファイルのインデックス作成の進捗を表示します
• ✅ 設定の共有：MCP サーバーと同じ設定を使用します
• ✅ 自動検出：glob パターンと再帰的なフォルダーに対応しています
• ✅ 形式への対応：PDF、TXT、MD をネイティブに処理し、pandoc を使えば DOCX などにも対応します

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 に保存されます

埋め込みモデルの選択

モデルによってトレードオフが異なります。

モデル	次元数	速度	品質	用途
all-MiniLM-L6-v2	384	高速	良好	デフォルト。性能のバランスが取れています
all-mpnet-base-v2	768	中速	より高品質	より高品質な埋め込み
paraphrase-multilingual-MiniLM-L12-v2	384	高速	良好	多言語サポート
all-MiniLM-L12-v2	384	中速	より高品質	同じサイズでより高品質

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

開発

単体テスト

MCP のインフラストラクチャを使わずに、FAISS ベクトルストアの機能をテストします。

source venv/bin/activate
python test_standalone.py

このテストでは、次の処理を行います。

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

ユニットテスト

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

pytest tests/ -v

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

# Test embedding model functionality
pytest tests/test_embedding_models.py -v

# Run standalone integration test
python tests/test_standalone.py

テストスイートには、次のテストが含まれます。

• test_embedding_models.py：カスタム埋め込みモデル、次元数の検出、互換性に関する包括的なテスト
• test_standalone.py：MCP のインフラストラクチャを使わないエンドツーエンドの統合テスト

ライセンス

MIT