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

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

目次

• 特徴

• 建築

• 前提条件

• インストール

• 構成

• サービスの実行

• MCP API

• テスト

• トラブルシューティング

• 貢献

• ライセンス

Related MCP server: local-agent-context

特徴

• 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で定義) を使用してジョブのステータスと結果を取得できます。

graph LR
    subgraph Client
        A[User/Client] -->|1. Send Prompt via MCP Tool| B(mcp-waifu-queue: main.py)
    end
    subgraph mcp-waifu-queue Server
        B -->|2. Enqueue Job (prompt)| C[Redis Queue]
        B -->|7. Return Job ID| A
        D[RQ Worker (worker.py)] --|>| C
        D -->|3. Dequeue Job & Execute| E(utils.call_predict_response)
        E -->|4. Call Gemini Logic| F(respond.predict_response)
        F -->|5. Call Gemini API| G[Google Gemini API]
        G -->|6. Return Response| F
        F --> E
        E -->|Update Job Result in Redis| C
        A -->|8. Check Status via MCP Resource| B
        B -->|9. Fetch Job Status/Result| C
        B -->|10. Return Status/Result| A
    end

前提条件

• 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を使用してテストを実行します。

pytest tests

**注意:**テストでは、実装に応じて、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ファイルを参照してください。