MCP with RAG Demo

RAG を使用した MCP デモ

このデモプロジェクトでは、検索拡張生成（RAG）機能を備えたモデルコンテキストプロトコル（MCP）サーバーの実装方法を紹介します。このデモでは、AI モデルがナレッジベースとやり取りし、情報を検索して、新しいドキュメントを追加できます。

機能

• ツールとリソースをサポートする MCP サーバー
• RAG の実装（メモリ内ストレージへのフォールバック機能付き）
• MCP サーバーとやり取りするクライアントの例
• SSE（HTTP）と stdio の両方の通信モードに対応
• シンプルなプロンプトテンプレート

前提条件

• Python 3.8+
• pip（Python パッケージマネージャー）

インストール

1. リポジトリをクローンします：

git clone <repository-url>
cd mcp-demo

2. 仮想環境を作成します：

python -m venv mcp-env
source mcp-env/bin/activate  # On Windows: mcp-env\Scripts\activate

3. 必要な依存関係をインストールします：

pip install -r requirements.txt

プロジェクト構成

mcp-demo/
├── server.py           # Main MCP server implementation
├── client_example.py   # Example client to interact with the server
├── requirements.txt    # Project dependencies
├── sample_data.txt     # Sample data available as a resource
├── tools/
│   ├── __init__.py     # Package initialization
│   └── rag_tools.py    # RAG tools implementation
└── README.md           # This readme file

デモの実行

ステップ 1：MCP サーバーを起動する

MCP サーバーは、次の 2 つのモードで実行できます。

オプション A：SSE（HTTP）モード

このモードでは、Server-Sent Events（SSE）を使用して、サーバーが HTTP 経由で接続を受け付けます：

python server.py --sse

デフォルトでは、サーバーは 0.0.0.0:8000 でリッスンします。ホストとポートは変更できます：

python server.py --sse --host 127.0.0.1 --port 9000

オプション B：stdio モード

このモードでは、サーバーは標準入出力を介して通信します：

python server.py --stdio

ステップ 2：クライアントの例を実行する

サーバーが起動したら、新しいターミナルウィンドウを開きます（最初のターミナルではサーバーを起動したままにします）。

SSE サーバーに接続する

# Make sure your virtual environment is activated
source mcp-env/bin/activate  # On Windows: mcp-env\Scripts\activate

# Run the client with SSE mode
python client_example.py --sse http://localhost:8000

URL に含まれていない場合、クライアントは自動的に「/sse」を追加します。

stdio 経由で接続する

# Make sure your virtual environment is activated
source mcp-env/bin/activate  # On Windows: mcp-env\Scripts\activate

# Run the client with stdio mode
python client_example.py --stdio --command python --args "server.py --stdio"

必要に応じて、コマンドと引数を変更できます。

クライアントの例で実行されること

クライアントの例では、次の主要な操作を紹介します。

1. MCP サーバーで利用可能なツール、リソース、プロンプトを一覧表示する
2. 基本的な通信を確認するためにecho ツールを呼び出す
3. メタデータとともにドキュメントをナレッジベースに追加する
4. RAG システムを使用してナレッジベースを検索する
5. サーバーからサンプルリソースを読み取る

利用可能な MCP ツール

このデモでは、次のツールを利用できます。

• echo：指定されたメッセージをそのまま返すシンプルなツール
• add：2 つの数値を加算するツール
• add_document：ナレッジベースにドキュメントを追加します
• rag_search：クエリに関連する情報をナレッジベースから検索します
• list_documents：ナレッジベース内のすべてのドキュメントを一覧表示します

利用可能な MCP リソース

• sample://data：sample_data.txt 内のサンプルデータにアクセスできます

利用可能な MCP プロンプト

• greeting：シンプルな挨拶のプロンプトテンプレート

デモのカスタマイズ

新しいツールの追加

新しいツールを追加するには、server.py ファイルを編集します：

@mcp.tool()
def your_tool_name(param1: type, param2: type) -> return_type:
    """Tool description"""
    # Tool implementation
    return result

新しいリソースの追加

新しいリソースを追加するには、server.py ファイルを編集します：

@mcp.resource("resource://pattern")
def your_resource_function() -> str:
    """Resource description"""
    # Resource implementation
    return "Resource content"

新しいプロンプトの追加

新しいプロンプトテンプレートを追加するには、server.py ファイルを編集します：

@mcp.prompt()
def your_prompt_name(param1: str, param2: str) -> str:
    """Prompt description"""
    return f"""
    Your prompt template text with {param1} and {param2} parameters.
    """

トラブルシューティング

クライアントの接続に関する問題

クライアントの実行時に「Connection refused」エラーが発生する場合：

1. 別のターミナルウィンドウでサーバーが実際に起動していることを確認します
2. 正しい URL を使用していることを確認します（デフォルトは http://localhost:8000 です）
3. サーバーが想定されるインターフェースでリッスンしていることを確認します（外部からの接続を受け付けるには 0.0.0.0 を指定します）
4. サーバーの URL を明示的に指定してみます：python client_example.py --sse http://localhost:8000

サーバーエンドポイントに関する問題

MCP サーバーは、/sse に SSE（Server-Sent Events）エンドポイントを公開します。クライアントで接続する場合：

• 完全な URL は http://localhost:8000/sse です
• 指定した URL に /sse が含まれていない場合、クライアントが自動的に追加します

デバッグモード

問題が発生した場合は、デバッグモードを有効にして、より詳細な出力を確認できます：

python client_example.py --sse http://localhost:8000 --debug

よくある問題

クライアント接続時のインポートエラー

クライアントのサンプルを実行したときにインポートエラーが発生する場合は、必要な依存関係がすべてインストールされていることを確認してください。

pip install mcp-sdk

パッケージが見つからない、またはバージョンが一致しない

インポートエラーやバージョンの互換性に関する問題が発生した場合は、特定のバージョンの MCP パッケージをインストールしてみてください。

pip install mcp-sdk>=1.0.0

ライセンス

このプロジェクトは実装例として提供されており、MIT License の下で利用できます。

セットアップ

1. 必要な依存関係をインストールします。

   pip install -r requirements.txt
   

2. .env ファイルを作成します。

   cp .env.example .env
   

3. .env ファイルを編集し、OpenAI API キーを追加します。

   OPENAI_API_KEY=your_api_key_here
   

   .env ファイルでは、ほかのオプションも設定できます。

   • MCP_SERVER_URL：MCP サーバーの URL（デフォルト：http://localhost:3000）
   • DEBUG：デバッグモードを有効にします（デフォルト：false）

使い方

次のコマンドでデモを実行します。

python openai_example.py

コマンドライン引数を使って、.env ファイル内の設定を上書きできます。

python openai_example.py --api-key YOUR_API_KEY --server-url http://your-server-url

環境変数

.env ファイルでは、次の環境変数を設定できます。

• OPENAI_API_KEY：OpenAI API キー（必須）
• MCP_SERVER_URL：MCP サーバーの URL（任意）
• DEBUG：デバッグモードを有効にします（任意）

コマンドライン引数

• --api-key：OpenAI API キー（.env ファイルの設定を上書きします）
• --server-url：MCP サーバーの URL（.env ファイルの設定を上書きします）
• --debug：デバッグモードを有効にします（.env ファイルの設定を上書きします）

MCP OpenAI の例

この例では、Model Control Protocol（MCP）を OpenAI の API とともに使用する方法を紹介します。

セットアップ

1. 必要な依存関係をインストールします。

   pip install -r requirements.txt
   

2. .env.example テンプレートを基に .env ファイルを作成します。

   cp .env.example .env
   

3. .env ファイルを編集し、OpenAI API キーを追加します。

   OPENAI_API_KEY=your_api_key_here
   

サンプルの実行

次のスクリプトを実行します。

python openai_example.py

オプションを直接指定することもできます。

python openai_example.py --api-key your_api_key_here --server-url http://localhost:3000 --debug

サンプルの動作

1. .env ファイルから環境変数を読み込みます
2. API キーを使って OpenAI クライアントを設定します
3. 利用可能なモデルを一覧表示します
4. 簡単なプロンプトでチャット補完を作成します

環境変数

• OPENAI_API_KEY：OpenAI API キー（必須）
• MCP_SERVER_URL：MCP サーバーの URL（任意、デフォルトは http://localhost:3000）
• DEBUG：デバッグログを有効にします（任意、デフォルトは false）