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

Requirements

• 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

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

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

Running the Server

Ensure your ~/.api-openrouter 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.

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

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