MCP Waifu Queue

MCP ワイフキュー（ジェミニ版）

このプロジェクトは、会話型AI「waifu」キャラクター用のMCP（Model Context Protocol）サーバーを実装します。Redisキューを介してGoogle Gemini APIを活用し、非同期処理を実現します。FastMCP FastMCPを使用することで、サーバーのセットアップと管理を簡素化します。

目次

• 特徴
• 建築
• 前提条件
• インストール
• 構成
• サービスの実行
• MCP API
• テスト
• トラブルシューティング
• 貢献
• ライセンス

特徴

• Google Gemini API ( gemini-2.5-pro-preview-03-25 ) を使用したテキスト生成。
• 同時リクエストを非同期的に処理するために Redis を使用したリクエスト キューイング。
• FastMCPを使用した MCP 準拠 API。
• MCP リソースによるジョブ ステータスの追跡。
• 環境変数 ( .envファイル) による構成と~/.api-geminiからの API キーの読み込み。

建築

このプロジェクトは、いくつかの主要なコンポーネントで構成されています。

• main.py : FastMCPアプリケーションを初期化し、MCP ツール/リソースを定義するメイン エントリ ポイント。
• respond.py : google-generativeaiライブラリを使用して Gemini API と対話するためのコアテキスト生成ロジックが含まれています。
• task_queue.py : Redis キューとのやり取りを処理し ( python-rqを使用)、生成リクエストをキューに登録します。
• utils.py : ユーティリティ関数、具体的には、 respond.py内の Gemini ロジックを呼び出すためにワーカーによって実行されるcall_predict_responseが含まれています。
• worker.py : call_predict_responseを呼び出して、キューからのジョブを処理する Redis ワーカー ( python-rq )。
• config.py : pydantic-settingsを使用して構成を管理します。
• models.py : MCP リクエストとレスポンスの検証用の Pydantic モデルを定義します。

リクエストのフローは次のとおりです。

1. クライアントは、 generate_text MCP ツール ( main.pyで定義) にリクエストを送信します。
2. ツールはリクエスト (プロンプト) を Redis キュー ( task_queue.pyによって処理) にエンキューします。
3. worker.pyプロセスがキューからジョブを取得します。
4. ワーカーはcall_predict_response関数 ( utils.pyから) を実行します。
5. call_predict_response 、Gemini API と対話するpredict_response関数 ( respond.py内) を呼び出します。
6. 生成されたテキスト (またはエラー メッセージ) はpredict_responseによって返され、RQ によってジョブ結果として保存されます。
7. クライアントはjob://{job_id} MCP リソース ( main.pyで定義) を使用してジョブのステータスと結果を取得できます。

前提条件

• Python 3.7以上
• pipまたはuv (Python パッケージインストーラー)
• Redis サーバー (インストール済み、実行中)
• Google Gemini APIキー

Redis をシステムにインストールする手順については、Redis の公式 Web サイトをご覧ください: https://redis.io/docs/getting-started/ Gemini API キーは、Google AI Studio から取得できます: https://aistudio.google.com/app/apikey

インストール

1. リポジトリをクローンします。
   git clone <YOUR_REPOSITORY_URL> cd mcp-waifu-queue
2. 仮想環境を作成してアクティブ化します ( venvまたはuvを使用)。venv (標準ライブラリ) を使用する:
   python -m venv .venv source .venv/bin/activate # On Linux/macOS # .venv\Scripts\activate # On Windows CMD # source .venv/Scripts/activate # On Windows Git Bash/PowerShell Core
   uvを使用する (インストールされている場合):
   # Ensure uv is installed (e.g., pip install uv) python -m uv venv .venv source .venv/bin/activate # Or equivalent activation for your shell
3. 依存関係をインストールします (venv またはuv内でpipを使用)。pipを使用する:
   pip install -e .[test] # Installs package in editable mode with test extras
   uvの使用:
   # Ensure uv is installed inside the venv if desired, or use the venv's python # .venv/Scripts/python.exe -m pip install uv # Example for Windows .venv/Scripts/python.exe -m uv pip install -e .[test] # Example for Windows # python -m uv pip install -e .[test] # If uv is in PATH after venv activation

構成

1. **APIキー:**ホームディレクトリ（ ~/.api-gemini ）に.api-geminiというファイルを作成し、Google Gemini APIキーを入力してください。ファイルに余分な空白が含まれていないことを確認してください。
   echo "YOUR_API_KEY_HERE" > ~/.api-gemini
   ( YOUR_API_KEY_HERE実際のキーに置き換えてください)
2. その他の設定: .env.exampleファイルを.envにコピーします。
   cp .env.example .env
3. .envファイルを変更して、残りの構成値を設定します。
   • MAX_NEW_TOKENS : Gemini レスポンスのトークンの最大数 (デフォルト: 2048 )。
   • REDIS_URL : Redis サーバーの URL (デフォルト: redis://localhost:6379 )。
   • FLASK_ENV 、 FLASK_APP : オプション。他の場所で使用される場合は Flask に関連しますが、MCP サーバー/ワーカー操作の中心ではありません。

サービスの実行

1. **Redis が実行中であることを確認してください。**ローカルにインストールした場合は、Redis サーバープロセスを起動する必要がある場合があります（例： redis-serverコマンド、またはサービスマネージャー経由）。
2. **RQ ワーカーを起動します。**ターミナルを開き、仮想環境をアクティブ化 ( source .venv/bin/activateまたは同様のコマンド) して、次を実行します。
   python -m mcp_waifu_queue.worker
   このコマンドはワーカープロセスを起動し、 .envファイルで定義された Redis キューのジョブをリッスンします。このターミナルは実行したままにしておいてください。
3. MCP サーバーを起動します。 別のターミナルを開き、仮想環境をアクティブにして、 uvicornなどのツールを使用して MCP サーバーを実行します (インストールする必要がある場合があります: pip install uvicornまたはuv pip install uvicorn ):
   uvicorn mcp_waifu_queue.main:app --reload --port 8000 # Example port
   8000ご希望のポートに置き換えてください。-- --reloadフラグは開発時に便利です。あるいは、Redis (実行されていない場合) とワーカーをバックグラウンドで起動しようとするstart-services.shスクリプト (主に Linux/macOS 環境向けに設計) を使用することもできます。
   # Ensure the script is executable: chmod +x ./scripts/start-services.sh ./scripts/start-services.sh # Then start the MCP server manually as shown above.

MCP API

サーバーは、次の MCP 準拠のエンドポイントを提供します。

ツール

• generate_text
  • **説明:**バックグラウンド キューを介して Gemini API にテキスト生成要求を送信します。
  • 入力: {"prompt": "Your text prompt here"} (タイプ: GenerateTextRequest )
  • 出力: {"job_id": "rq:job:..."} (キューに入れられたジョブの一意のID)

リソース

• job://{job_id}
  • **説明:**以前に送信されたジョブのステータスと結果を取得します。
  • URI パラメータ: job_id ( generate_textツールによって返される ID)。
  • 出力: {"status": "...", "result": "..."} (タイプ: JobStatusResponse )
    • status : ジョブの現在の状態（例：「キューに追加済み」、「開始済み」、「終了済み」、「失敗」）。RQは内部的に若干異なる用語を使用します（「開始済み」と「処理中」、「終了済み」と「完了」）。リソースはこれらをマッピングします。
    • result : ジョブのステータスが「完了」の場合、Geminiから生成されたテキスト。それ以外の場合はnull 。ジョブが失敗した場合、RQの処理に応じて、結果はnullになるか、エラー情報が含まれる場合があります。

テスト

プロジェクトにはテストが含まれています。テストの依存関係がインストールされていることを確認してください（ pip install -e .[test]またはuv pip install -e .[test] ）。

pytestを使用してテストを実行します。

**注意:**テストでは、実装に応じて、Redis のモック ( fakeredis ) と、場合によっては Gemini API 呼び出しが必要になる場合があります。

トラブルシューティング

• エラー: Gemini API key not found in .../.api-gemini or GEMINI_API_KEY environment variable 。ホームディレクトリに~/.api-geminiファイルを作成し、有効なGemini APIキーを入力してください。または、 GEMINI_API_KEY環境変数がフォールバックとして設定されていることを確認してください。
• Gemini API 呼び出し中にエラーが発生しました（例: AuthenticationError、PermissionDenied） : ~/.api-gemini （またはフォールバック環境変数）内の API キーが正しく有効であることを再度ご確認ください。該当する場合は、Google Cloud プロジェクトで API が有効になっていることを確認してください。
• ジョブが「キュー」で停止している場合：RQワーカー（ python -m mcp_waifu_queue.worker ）が別のターミナルで実行され、 .envで指定された同じRedisインスタンスに接続されていることを確認してください。ワーカーログにエラーがないか確認してください。
• ConnectionRefusedError (Redis) : Redis サーバーが実行中であり、 .envで指定されたREDIS_URLでアクセスできることを確認してください。
• MCP サーバー接続の問題: MCP サーバー ( uvicorn ... ) が実行中であり、正しいホスト/ポートに接続していることを確認します。

貢献

1. リポジトリをフォークします。
2. 機能またはバグ修正用の新しいブランチを作成します ( git checkout -b feature/your-feature-name )。
3. 変更を加えてコミットします ( git commit -am 'Add some feature' )。
4. ブランチをフォークしたリポジトリにプッシュします ( git push origin feature/your-feature-name )。
5. 元のリポジトリに新しいプル リクエストを作成します。

プロジェクトのコーディング標準とリンティングルール ( ruff ) を遵守してください。

ライセンス

このプロジェクトは MIT-0 ライセンスの下でライセンスされています - 詳細についてはLICENSEファイルを参照してください。