waifuai/mcp-waifu-chat

MCP Waifu Chat Server

This project implements a basic MCP (Model Context Protocol) server for a conversational AI "waifu" character. It uses the mcp library for Python to handle the protocol details and FastMCP for easy server setup.

Features

• User management (create, check existence, delete, count)
• Dialog history storage (get, set, reset)
• Basic chat functionality (using Google GenAI SDK Client)
• Modular design for easy extension
• Configuration via environment variables and API key file
• SQLite database for persistence
• Comprehensive unit tests

Requirements

• Python 3.10+
• uv
• An OpenRouter API Key or a Google Gemini API Key

Installation

1. Clone the repository:

   git clone <repository_url>
   cd mcp-waifu-chat
   

2. Install uv (if not installed) With curl:

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

Or with powershell:

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

3. Create the virtual environment and ensure tooling inside:

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

4. Install dependencies:

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

Configuration

The server uses a combination of a file for the API key and environment variables (or a .env file) for other configurations.

API Keys: You can use either OpenRouter (default) or Gemini.

OpenRouter (default):

• Preferred via environment variable: OPENROUTER_API_KEY
• Fallback: single-line key file ~/.api-openrouter
• Model resolution precedence:
  1. OPENROUTER_MODEL_NAME
  2. ~/.model-openrouter
  3. openrouter/horizon-beta

Gemini:

• Preferred via environment variables: GEMINI_API_KEY or GOOGLE_API_KEY
• Fallback: single-line key file ~/.api-gemini
• Model resolution precedence:
  1. GEMINI_MODEL_NAME
  2. ~/.model-gemini
  3. gemini-2.5-pro

You can obtain a key from Google AI Studio.

Other Configuration (.env file or environment variables): An example .env.example file is provided for other settings:

DATABASE_FILE=dialogs.db
DEFAULT_RESPONSE="I'm sorry, I'm having trouble connecting to the AI model."
DEFAULT_GENRE="Fantasy"
FLASK_PORT=5000
GEMINI_MODEL_NAME=gemini-2.5-pro

• DATABASE_FILE: Path to the SQLite database file (default: dialogs.db).
• DEFAULT_RESPONSE: The default response to send when the AI model is unavailable (default: "The AI model is currently unavailable. Please try again later.").
• DEFAULT_GENRE: The default conversation genre (default: "Romance").
• FLASK_PORT: The port the server will listen on (default: 5000).
• GEMINI_MODEL_NAME: The specific Gemini model to use (default: gemini-2.5-pro).

Copy .env.example to .env and customize the values as needed (except for the API key, which is read from ~/.api-gemini).

Running the Server

Ensure your ~/.api-gemini file is set up correctly. Then, to run the server, use:

uv run mcp-waifu-chat

This runs the mcp_waifu_chat/api.py file (since that's where the FastMCP instance is defined) and starts up the server.

Running Tests

To run the unit tests:

uv run pytest

This will execute all tests in the tests/ directory using pytest. The tests include database tests and API endpoint tests. Note: API tests currently do not cover the live Gemini interaction and may need adaptation for mocking.

API Endpoints

The server provides the following MCP-compliant endpoints (using FastMCP's automatic routing):

Server Status

• /v1/server/status (GET): Checks the server status. Returns {"status": "ok"}. This is a standard MCP endpoint.

User Management Tools

These are implemented as MCP tools.

• create_user (user_id: str): Creates a new user.
• check_user (user_id: str): Checks if a user exists. Returns {"user_id": str, "exists": bool}.
• delete_user (user_id: str): Deletes a user.
• user_count: returns the number of users in the database for the current user.

Dialog Management Tools

• reset_dialog (user_id: str)

Resources

• /v1/user/dialog/json/{user_id}: Dynamic resource to return dialogs as JSON.
• /v1/user/dialog/str/{user_id}: Dynamic resource to return dialogs as a string

Chat Tool

• chat (message: str, user_id: str): Sends a chat message and gets a response generated by the selected provider (OpenRouter by default or Google GenAI).

LLM Integration (Providers: OpenRouter default, Gemini supported)

The dispatcher in selects a provider and generates responses.

Default provider: openrouter

Provider selection:

• Config field default_provider (env: DEFAULT_PROVIDER) chooses "openrouter" or "gemini" (defaults to "openrouter").

Model resolution precedence:

• OpenRouter model name: OPENROUTER_MODEL_NAME env; else ~/.model-openrouter; else openrouter/horizon-beta.
• Gemini model name: GEMINI_MODEL_NAME env; else ~/.model-gemini; else gemini-2.5-pro.

Credentials:

• OpenRouter: OPENROUTER_API_KEY env; else ~/.api-openrouter.
• Gemini: GEMINI_API_KEY env; else GOOGLE_API_KEY env; else ~/.api-gemini.

Call patterns:

• OpenRouter: HTTPS POST to https://openrouter.ai/api/v1/chat/completions with a single user message.
• Gemini: client.models.generate_content(model=..., contents=...) via .

Both paths include defensive parsing and error handling, returning config.default_response when unavailable.

Deploying to Production

For a production deployment, you should:

1. Use a production-ready WSGI/ASGI server: Gunicorn is recommended and included in the pyproject.toml. Example command:

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

   This runs the app object (our FastMCP instance) from mcp_waifu_chat/api.py using 4 Uvicorn workers managed by Gunicorn, listening on port 8000. Adjust the number of workers and the port as needed.

2. Use a robust database: Consider PostgreSQL or MySQL instead of SQLite for higher concurrency and scalability.

3. Implement proper logging: Configure logging to write to files, a centralized logging service, or a monitoring system.

4. Secure your server: Use HTTPS, implement authentication/authorization, and follow security best practices for web applications.

5. Consider a reverse proxy: Use a reverse proxy like Nginx or Apache to handle TLS termination, load balancing, and static file serving.

6. Containerize Use Docker to simplify deployment.

Project Structure Explanation

• mcp_waifu_chat/ (Main Package):
  • __init__.py: Makes the directory a Python package.
  • api.py: The core FastMCP application, tool/resource definitions, and request handling logic.
  • config.py: Handles loading and validating configuration settings.
  • db.py: All database interaction logic (creating tables, querying, updating).
  • models.py: Pydantic models for request/response data validation and serialization.
  • utils.py: Helper functions, like dialog_to_json and json_to_dialog.
  • ai.py: This module is responsible for interacting with the Google Gemini AI model.
• tests/ (Test Suite):
  • conftest.py: pytest configuration, including fixtures for the test database and test client.
  • test_db.py: Unit tests for the db.py module.
  • test_api.py: Unit tests for the API endpoints in api.py.
• run.py:: Simple file to run the server (Note: uv run mcp-waifu-chat is preferred).

This structure promotes modularity, testability, and maintainability. Each module has a specific responsibility, making it easier to understand, modify, and extend the codebase.