MCP Waifu Queue (Gemini Edition)

MCP Waifu Queue

このプロジェクトは、Redis キューを介した非同期処理に OpenRouter API を利用し、会話型 AI の「waifu」キャラクター向け MCP（Model Context Protocol）サーバーを実装します。サーバーのセットアップと管理を簡素化するため、FastMCP ライブラリを使用しています。

目次

• 機能
• アーキテクチャ
• 前提条件
• インストール
• 設定
• サービスの実行
• MCP API
• テスト
• トラブルシューティング
• コントリビューション
• ライセンス

機能

• ~/.model-openrouter のモデル、または openrouter/free を使用した OpenRouter 経由のテキスト生成。
• Redis を使用したリクエストのキューイングによる、同時リクエストの非同期処理。
• FastMCP を使用した MCP 準拠の API。
• MCP リソースによるジョブステータスの追跡。
• 環境変数（.env ファイル）による設定。
• API キーの読み込み：
  • OpenRouter：OPENROUTER_API_KEY または ~/.api-openrouter
• ホームディレクトリ内のモデル選択ファイル：
  • OpenRouter のモデル名は ~/.model-openrouter

アーキテクチャ

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

• main.py：メインのエントリーポイントです。FastMCP アプリケーションを初期化し、MCP ツールとリソースを定義します。
• respond.py：OpenRouter API を使用したテキスト生成の中核ロジックが含まれています。
• task_queue.py：Redis キューとのやり取り（python-rq を使用）を処理し、生成リクエストをキューに追加します。
• utils.py：ユーティリティ関数が含まれています。特に、ワーカーによって実行され、respond.py 内の生成ロジックを呼び出す call_predict_response が含まれています。
• worker.py：キューからジョブを処理し、call_predict_response を呼び出す Redis ワーカー（python-rq）です。
• config.py：pydantic-settings を使用して設定を管理します。
• models.py：MCP リクエストとレスポンスの検証に使用する Pydantic モデルを定義します。

リクエストの処理の流れは次のとおりです。

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

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 Generation Logic| F(respond.predict_response)
        F -->|5. Call OpenRouter API| G[OpenRouter 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 サーバー（インストール済みで、実行中であること）
• OpenRouter API キー

Redis のインストール方法については、Redis 公式サイトをご覧ください：https://redis.io/docs/getting-started/ OpenRouter API キーは、こちらから取得できます：https://openrouter.ai/

インストール

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

   git clone <YOUR_REPOSITORY_URL>
   cd mcp-waifu-queue
   

2. uv を使用して仮想環境を作成し、有効化します：

   python -m uv venv .venv
   .venv/Scripts/python.exe -m ensurepip
   .venv/Scripts/python.exe -m pip install uv
   

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

   .venv/Scripts/python.exe -m uv pip install -r requirements.txt
   .venv/Scripts/python.exe -m uv pip install -r requirements-dev.txt
   

構成

1. $HOME 内のファイルを使ったモデル名の設定：

   • OpenRouter のモデルファイル：

     echo "openrouter/free" > ~/.model-openrouter
     

2. API キー： 環境変数での設定を推奨します。設定されていない場合はファイルが使用されます。

   • OpenRouter：OPENROUTER_API_KEY または ~/.api-openrouter

   echo "YOUR_API_KEY_HERE" > ~/.api-openrouter
   

   （YOUR_API_KEY_HERE を実際のキーに置き換えてください）

3. その他の設定： .env.example ファイルを .env にコピーします。

   cp .env.example .env
   

4. .env ファイルを編集し、残りの設定値を指定します。

   • MAX_NEW_TOKENS：応答の最大トークン数（デフォルト：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
  • 説明： バックグラウンドキューを介して、テキスト生成リクエストを OpenRouter 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：ジョブの現在の状態（例：「queued」、「started」、「finished」、「failed」）。RQ では内部的に多少異なる用語が使われます（「processing」ではなく「started」、「completed」ではなく「finished」）。このリソースはこれらの状態を対応付けます。
    • result：ジョブのステータスが「completed」の場合は生成されたテキスト、それ以外の場合は null です。ジョブが失敗した場合、RQ の処理方法によっては、結果が null になるか、エラー情報が含まれることがあります。

テスト

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

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

pytest tests

注： テストの実装によっては、Redis（fakeredis）や OpenRouter API 呼び出しのモックが必要になる場合があります。

トラブルシューティング

• エラー：OpenRouter API key not available：OPENROUTER_API_KEY が設定されていること、または ~/.api-openrouter にキーが1行で（空白なしで）記載されていることを確認してください。
• ジョブが「queued」のまま停止する：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 ファイルをご覧ください。