MCP Server with FAISS for RAG

RAG 用 FAISS 搭載 MCP サーバー

このプロジェクトは、AI エージェントがベクトルデータベースにクエリを送信し、検索拡張生成（RAG）に適した関連ドキュメントを取得できる、Machine Conversation Protocol（MCP）サーバーの概念実証実装を提供します。

特長

• MCP エンドポイントを備えた FastAPI サーバー
• FAISS ベクトルデータベースとの統合
• ドキュメントのチャンク化と埋め込み
• GitHub の Move ファイルの抽出と処理
• RAG ワークフロー全体を実現する LLM との統合
• シンプルなクライアントの例
• サンプルドキュメント

インストール

pipx を使用する（推奨）

pipx は、Python アプリケーションを分離された環境にインストールして実行するためのツールです。

1. pipx がまだインストールされていない場合は、まずインストールします。

# On macOS
brew install pipx
pipx ensurepath

# On Ubuntu/Debian
sudo apt update
sudo apt install python3-pip python3-venv
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# On Windows with pip
pip install pipx
pipx ensurepath

2. プロジェクトディレクトリから MCP サーバーのパッケージを直接インストールします。

# Navigate to the directory containing the mcp_server folder
cd /path/to/mcp-server-project

# Install in editable mode
pipx install -e .

3. （任意）環境変数を設定します。
   • .env.example を .env にコピーします。
   • レート制限を緩和するには、GitHub トークンを追加します：GITHUB_TOKEN=your_token_here
   • RAG との統合には、OpenAI またはその他の LLM API キーを追加します：OPENAI_API_KEY=your_key_here

手動インストール

pipx を使用しない場合は、次の手順を実行します。

1. リポジトリをクローンします。
2. 依存関係をインストールします。

cd mcp_server
pip install -r requirements.txt

pipx を使用する

pipx でインストールすると、次のコマンドを使用できます。

GitHub から Move ファイルをダウンロードする

# Download Move files with default settings
mcp-download --query "use sui" --output-dir docs/move_files

# Download with more options
mcp-download --query "module sui::coin" --max-results 50 --new-index --verbose

GitHub の検索とインデックス作成を改善する（推奨）

# Search GitHub and index files with default settings
mcp-search-index --keywords "sui move"

# Search multiple keywords and customize options
mcp-search-index --keywords "sui move,move framework" --max-repos 30 --output-results --verbose

# Save search results and use a custom index location
mcp-search-index --keywords "sui coin,sui::transfer" --index-file custom/path/index.bin --output-results

mcp-search-index コマンドでは、GitHub リポジトリの検索機能が強化されています。

• まずリポジトリを検索し、その後 Move ファイルを再帰的に抽出します。
• 複数の検索キーワード（カンマ区切り）に対応しています。
• 「use sui」参照を含む Move ファイルをインテリジェントに絞り込みます。
• ダウンロード後は、必ずベクトルデータベースを再構築します。

Move ファイルをインデックス化する

# Index files in the default location
mcp-index

# Index with custom options
mcp-index --docs-dir path/to/files --index-file path/to/index.bin --verbose

ベクトルデータベースにクエリを送信する

# Basic query
mcp-query "What is a module in Sui Move?"

# Advanced query with options
mcp-query "How do I define a struct in Sui Move?" -k 3 -f

LLM との統合で RAG を使用する

# Basic RAG query (will use simulated LLM if no API key is provided)
mcp-rag "What is a module in Sui Move?"

# Using with a specific LLM API
mcp-rag "How do I define a struct in Sui Move?" --api-key your_api_key --top-k 3

# Output as JSON for further processing
mcp-rag "What are the benefits of sui::coin?" --output-json > rag_response.json

サーバーを実行する

# Start the server with default settings
mcp-server

# Start with custom settings
mcp-server --host 127.0.0.1 --port 8080 --index-file custom/path/index.bin

手動での使用（pipx なし）

サーバーを起動する

cd mcp_server
python main.py

サーバーは http://localhost:8000 で起動します。

GitHub から Move ファイルをダウンロードする

GitHub から Move ファイルをダウンロードして、ベクトルデータベースに登録するには、次のコマンドを実行します。

# Download Move files with default query "use sui"
./run.sh --download-move

# Customize the search query
./run.sh --download-move --github-query "module sui::coin" --max-results 50

# Download, index, and start the server
./run.sh --download-move --index

Python スクリプトを直接使用することもできます。

python download_move_files.py --query "use sui" --output-dir docs/move_files

ドキュメントをインデックス化する

クエリを送信する前に、ドキュメントをインデックス化する必要があります。テキストファイル（.txt）、Markdown ファイル（.md）、または Move ファイル（.move）を docs ディレクトリに配置できます。

ドキュメントをインデックス化するには、次のいずれかの方法を使用します。

1. --index フラグを指定して実行スクリプトを使用します。

./run.sh --index

2. インデックススクリプトを直接使用します。

python index_move_files.py --docs-dir docs/move_files --index-file data/faiss_index.bin

ドキュメントにクエリを送信する

ローカルのクエリスクリプトを使用できます。

python local_query.py "What is RAG?"

# With more options
python local_query.py -k 3 -f "How to define a struct in Sui Move?"

LLM との統合で RAG を使用する

# Direct RAG query with an LLM
python rag_integration.py "What is a module in Sui Move?" --index-file data/faiss_index.bin

# With API key (if you have one)
OPENAI_API_KEY=your_key_here python rag_integration.py "How do coins work in Sui?"

MCP API エンドポイント

MCP API エンドポイントは /mcp/action で利用できます。これを使用して、次のようなさまざまなアクションを実行できます。

• retrieve_documents：クエリに関連するドキュメントを取得します。
• index_documents：ディレクトリ内のドキュメントをインデックス化します。

例：

curl -X POST "http://localhost:8000/mcp/action" -H "Content-Type: application/json" -d '{"action_type": "retrieve_documents", "payload": {"query": "What is RAG?", "top_k": 3}}'

RAG パイプライン全体

RAG（検索拡張生成）パイプライン全体は、次のように動作します。

1. 検索クエリ：ユーザーが質問を送信します。
2. 検索：システムがベクトルデータベースを検索し、関連ドキュメントを取得します。
3. コンテキストの構成：取得したドキュメントをプロンプトに整形します。
4. LLM による生成：取得したコンテキストとともにプロンプトを LLM に送信します。
5. 応答の強化：LLM が取得した情報に基づいて回答します。

このワークフローは rag_integration.py モジュールに完全に実装されており、コマンドラインから、または独自のアプリケーションでライブラリとして使用できます。

GitHub からの Move ファイルの抽出

このシステムは、検索クエリに基づいて GitHub から Move ファイルを抽出できます。次の 2 つの方法を実装しています。

1. GitHub API（推奨）：レート制限を緩和するには GitHub トークンが必要です。
2. Web スクレイピングへのフォールバック：API を使用する方法が失敗した場合、またはトークンが指定されていない場合に使用されます。

GitHub トークンを設定するには、.env ファイルまたは環境変数に設定します。

GITHUB_TOKEN=your_github_token_here

プロジェクト構成

mcp_server/
├── __init__.py             # Package initialization
├── main.py                # Main server file
├── mcp_api.py             # MCP API implementation
├── index_move_files.py    # File indexing utility
├── local_query.py         # Local query utility
├── download_move_files.py # GitHub Move file extractor
├── rag_integration.py     # LLM integration for RAG
├── pyproject.toml         # Package configuration
├── requirements.txt       # Dependencies
├── .env.example           # Example environment variables
├── README.md              # This file
├── data/                  # Storage for the FAISS index
├── docs/                  # Sample documents
│   └── move_files/        # Downloaded Move files
├── models/                # Model implementations
│   └── vector_store.py    # FAISS vector store implementation
└── utils/
    ├── document_processor.py  # Document processing utilities
    └── github_extractor.py    # GitHub file extraction utilities

プロジェクトの拡張

この概念実証を拡張するには、次の手順を実行します。

1. 認証機能とセキュリティ機能を追加します
2. より高度なドキュメント処理を実装します
3. より多くのドキュメント形式をサポートします
4. ほかの LLM プロバイダーと統合します
5. 監視とロギングを追加します
6. より構造化されたデータ抽出を行えるよう、Move 言語の解析を改善します

ライセンス

MIT