MCP ワイフキュー

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

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

特徴

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 モデルを定義します。

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

クライアントは、 generate_text MCP ツール ( main.pyで定義) にリクエストを送信します。
ツールはリクエスト (プロンプト) を Redis キュー ( task_queue.pyによって処理) にエンキューします。
worker.pyプロセスがキューからジョブを取得します。
ワーカーはcall_predict_response関数 ( utils.pyから) を実行します。
call_predict_response 、Gemini API と対話するpredict_response関数 ( respond.py内) を呼び出します。
生成されたテキスト (またはエラーメッセージ) はpredict_responseによって返され、RQ によってジョブ結果として保存されます。
クライアントは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

インストール

リポジトリをクローンします。
git clone <YOUR_REPOSITORY_URL> cd mcp-waifu-queue
仮想環境を作成してアクティブ化します ( 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
依存関係をインストールします (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

構成

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

サービスの実行

**Redis が実行中であることを確認してください。**ローカルにインストールした場合は、Redis サーバープロセスを起動する必要がある場合があります（例： redis-serverコマンド、またはサービスマネージャー経由）。
**RQ ワーカーを起動します。**ターミナルを開き、仮想環境をアクティブ化 ( source .venv/bin/activateまたは同様のコマンド) して、次を実行します。
python -m mcp_waifu_queue.worker
このコマンドはワーカープロセスを起動し、 .envファイルで定義された Redis キューのジョブをリッスンします。このターミナルは実行したままにしておいてください。
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 ... ) が実行中であり、正しいホスト/ポートに接続していることを確認します。

貢献

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

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

ライセンス

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

MCP Waifu Queue

Integrations