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

    ```bash
    git clone <repository_url>
    cd mcp-waifu-chat
    ```

2. Install uv (if not installed)
  With curl:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```
  Or with powershell:
  ```powershell
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```

3.  Create the virtual environment and ensure tooling inside:

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

4.  Install dependencies:

    ```bash
    .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](https://openrouter.ai/).

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

```bash
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:

```bash
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`](mcp_waifu_chat/ai.py:1) 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:

    ```bash
    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.