MCP Waifu Chat Server

MCP Waifu Chat サーバー

このプロジェクトは、会話型 AI キャラクター「waifu」向けの基本的な MCP（Model Context Protocol）サーバーを実装しています。プロトコルの詳細な処理には Python 用の mcp ライブラリを使用し、サーバーを簡単にセットアップするために FastMCP を使用します。

特長

• ユーザー管理（作成、存在確認、削除、件数取得）
• 会話履歴の保存（取得、設定、リセット）
• 基本的なチャット機能（OpenRouter API を使用）
• 拡張しやすいモジュール設計
• 環境変数と API キーファイルによる設定
• 永続化に SQLite データベースを使用
• 包括的なユニットテスト

要件

• Python 3.10+
• uv
• OpenRouter API キー

インストール

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

   git clone <repository_url>
   cd mcp-waifu-chat
   

2. uv をインストールします（未インストールの場合）。 curl を使用する場合：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

powershell を使用する場合：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 仮想環境を作成し、その環境内にツールをインストールします。

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

4. 依存関係をインストールします。

   .venv/Scripts/python.exe -m uv pip install -e .[test]
   

設定

サーバーでは、API キー用ファイルと、その他の設定用の環境変数（または .env ファイル）を組み合わせて使用します。

API キー：

OpenRouter（デフォルト）：

• 優先：環境変数 OPENROUTER_API_KEY
• フォールバック：1 行のキーを記載したファイル ~/.api-openrouter
• モデルの解決順序：
  1. OPENROUTER_MODEL_NAME
  2. ~/.model-openrouter
  3. openrouter/free

キーは OpenRouter から取得できます。

その他の設定（.env ファイルまたは環境変数）： その他の設定項目の例として、.env.example ファイルが用意されています。

DATABASE_FILE=dialogs.db
DEFAULT_RESPONSE="I'm sorry, I'm having trouble connecting to the AI model."
DEFAULT_GENRE="Fantasy"
FLASK_PORT=5000
OPENROUTER_MODEL_NAME=openrouter/free

• DATABASE_FILE：SQLite データベースファイルのパス（デフォルト：dialogs.db）。
• DEFAULT_RESPONSE：AI モデルが利用できない場合に送信するデフォルトの応答（デフォルト："The AI model is currently unavailable. Please try again later."）。
• DEFAULT_GENRE：デフォルトの会話ジャンル（デフォルト："Romance"）。
• FLASK_PORT：サーバーがリッスンするポート（デフォルト：5000）。
• OPENROUTER_MODEL_NAME：使用する OpenRouter モデル（デフォルト：openrouter/free）。

.env.example を .env にコピーし、必要に応じて値をカスタマイズしてください（API キーは除きます。API キーは ~/.api-openrouter から読み込まれます）。

サーバーの実行

~/.api-openrouter ファイルが正しく設定されていることを確認してください。次に、サーバーを実行するには以下を使用します。

uv run mcp-waifu-chat

これにより、FastMCP インスタンスが定義されている mcp_waifu_chat/api.py ファイルが実行され、サーバーが起動します。

テストの実行

ユニットテストを実行するには、以下を使用します。

uv run pytest

これにより、pytest を使用して tests/ ディレクトリ内のすべてのテストが実行されます。テストにはデータベーステストと API エンドポイントテストが含まれます。

API エンドポイント

サーバーは、以下の MCP 準拠エンドポイントを提供します（FastMCP による自動ルーティングを使用）。

サーバーのステータス

• /v1/server/status (GET)：サーバーのステータスを確認します。{"status": "ok"} を返します。これは標準的な MCP エンドポイントです。

ユーザー管理ツール

これらは MCP の ツール として実装されています。

• create_user (user_id: str)：新しいユーザーを作成します。
• check_user (user_id: str)：ユーザーが存在するか確認します。{"user_id": str, "exists": bool} を返します。
• delete_user (user_id: str)：ユーザーを削除します。
• user_count：現在のユーザーのデータベース内にあるユーザー数を返します。

会話管理ツール

• reset_dialog (user_id: str)

リソース

• /v1/user/dialog/json/{user_id}：会話を JSON として返す動的リソースです。
• /v1/user/dialog/str/{user_id}：会話を文字列として返す動的リソースです。

チャットツール

• chat (message: str, user_id: str)：チャットメッセージを送信し、OpenRouter が生成した応答を取得します。

LLM 統合（OpenRouter）

mcp_waifu_chat/ai.py のディスパッチャーがプロバイダーを選択し、応答を生成します。

プロバイダー：openrouter

モデル解決の優先順位：

• OpenRouter のモデル名：OPENROUTER_MODEL_NAME 環境変数。未設定の場合は ~/.model-openrouter。それもない場合は openrouter/free。

認証情報：

• OpenRouter：OPENROUTER_API_KEY 環境変数。未設定の場合は ~/.api-openrouter。

呼び出しパターン：

• OpenRouter：単一のユーザーメッセージを使って、https://openrouter.ai/api/v1/chat/completions に HTTPS POST します。

この処理では防御的な解析とエラー処理を行い、利用できない場合は config.default_response を返します。

本番環境へのデプロイ

本番環境にデプロイする場合は、次のことを行ってください。

1. 本番環境に対応した WSGI/ASGI サーバーを使用する： Gunicorn を推奨します。pyproject.toml に含まれています。コマンド例：

   gunicorn --workers 4 --bind 0.0.0.0:8000 mcp_waifu_chat.api:app -k uvicorn.workers.UvicornWorker
   

   これにより、Gunicorn が管理する 4 つの Uvicorn ワーカーを使って、mcp_waifu_chat/api.py の app オブジェクト（FastMCP インスタンス）が実行され、ポート 8000 でリッスンします。必要に応じて、ワーカー数とポートを調整してください。

2. 堅牢なデータベースを使用する： 同時実行性とスケーラビリティを高めるため、SQLite の代わりに PostgreSQL または MySQL を検討してください。

3. 適切なロギングを実装する： ログをファイル、集中型ログサービス、または監視システムに書き込むよう設定してください。

4. サーバーを保護する： HTTPS を使用し、認証と認可を実装して、Web アプリケーションのセキュリティに関するベストプラクティスに従ってください。

5. リバースプロキシを検討する： Nginx や Apache などのリバースプロキシを使用して、TLS 終端、ロードバランシング、静的ファイルの配信を処理してください。

6. コンテナ化 Docker を使用すると、デプロイを簡素化できます。

プロジェクト構成の説明

• mcp_waifu_chat/（メインパッケージ）：
  • __init__.py：ディレクトリを Python パッケージにします。
  • api.py：FastMCP アプリケーションの中核、ツールとリソースの定義、リクエスト処理ロジックです。
  • config.py：設定の読み込みと検証を行います。
  • db.py：データベースとのやり取り（テーブルの作成、クエリ、更新）をすべて処理します。
  • models.py：リクエストとレスポンスのデータ検証およびシリアライズに使用する Pydantic モデルです。
  • utils.py：dialog_to_json や json_to_dialog などのヘルパー関数です。
  • ai.py：OpenRouter API とのやり取りを担うモジュールです。
• tests/（テストスイート）：
  • conftest.py：テスト用データベースとテストクライアントのフィクスチャを含む pytest の設定です。
  • test_db.py：db.py モジュールの単体テストです。
  • test_api.py：api.py の API エンドポイントの単体テストです。
• **run.py：**サーバーを実行するためのシンプルなファイルです（注：uv run mcp-waifu-chat の使用を推奨します）。

この構成により、モジュール性、テスト容易性、保守性が高まります。各モジュールの責務が明確なため、コードベースの理解、変更、拡張が容易になります。