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 OpenRouter API)
Modular design for easy extension
Configuration via environment variables and API key file
SQLite database for persistence
Comprehensive unit tests

Python 3.10+
uv
An OpenRouter 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

   

  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 Key:

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/free

You can obtain a key from OpenRouter.

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
OPENROUTER_MODEL_NAME=openrouter/free

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).
OPENROUTER_MODEL_NAME: The specific OpenRouter model to use (default: openrouter/free).

uv run mcp-waifu-chat

uv run pytest

/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)

chat (message: str, user_id: str): Sends a chat message and gets a response generated by OpenRouter.

LLM Integration (OpenRouter)

The dispatcher in mcp_waifu_chat/ai.py selects the provider and generates responses.

Provider: openrouter

Model resolution precedence:
- OpenRouter model name: OPENROUTER_MODEL_NAME env; else ~/.model-openrouter; else openrouter/free.

Credentials:
- OpenRouter: OPENROUTER_API_KEY env; else ~/.api-openrouter.

Call pattern:
- OpenRouter: HTTPS POST to https://openrouter.ai/api/v1/chat/completions with a single user message.

The path includes 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 OpenRouter API.
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).