mcp-waifu-queue

Project Description

MCP Waifu Queue

This project implements an MCP (Model Context Protocol) server for a conversational AI "waifu" character, leveraging the OpenRouter API via a Redis queue for asynchronous processing. It utilizes the FastMCP library for simplified server setup and management.

Table of Contents

Features

Architecture

The project consists of several key components:

The flow of a request is as follows:

  1. A client sends a request to the generate_text MCP tool (defined in main.py).
  2. The tool enqueues the request (prompt) to a Redis queue (handled by task_queue.py).
  3. A worker.py process picks up the job from the queue.
  4. The worker executes the call_predict_response function (from utils.py).
  5. call_predict_response calls the predict_response function (in respond.py), which interacts with the OpenRouter API.
  6. The generated text (or an error message) is returned by predict_response and stored as the job result by RQ.
  7. The client can retrieve the job status and result using the job://{job_id} MCP resource (defined in main.py).
graph LR
    subgraph Client
        A[User/Client] -->|1. Send Prompt via MCP Tool| B(mcp-waifu-queue: main.py)
    end
    subgraph mcp-waifu-queue Server
        B -->|2. Enqueue Job (prompt)| C[Redis Queue]
        B -->|7. Return Job ID| A
        D[RQ Worker (worker.py)] --|>| C
        D -->|3. Dequeue Job & Execute| E(utils.call_predict_response)
        E -->|4. Call Generation Logic| F(respond.predict_response)
        F -->|5. Call OpenRouter API| G[OpenRouter API]
        G -->|6. Return Response| F
        F --> E
        E -->|Update Job Result in Redis| C
        A -->|8. Check Status via MCP Resource| B
        B -->|9. Fetch Job Status/Result| C
        B -->|10. Return Status/Result| A
    end

Prerequisites

You can find instructions for installing Redis on your system on the official Redis website: https://redis.io/docs/getting-started/ You can obtain an OpenRouter API key from: https://openrouter.ai/

Installation

  1. Clone the repository:

    bash git clone <YOUR_REPOSITORY_URL> cd mcp-waifu-queue

  2. Create and activate a virtual environment using uv:

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

  3. Install dependencies:

    bash .venv/Scripts/python.exe -m uv pip install -r requirements.txt .venv/Scripts/python.exe -m uv pip install -r requirements-dev.txt

Configuration

  1. Model Names via files in $HOME:
    • OpenRouter model file: echo "openrouter/free" > ~/.model-openrouter

  2. API Keys: Preferred via environment variables with file fallback:

    • OpenRouter: OPENROUTER_API_KEY or ~/.api-openrouter bash echo "YOUR_API_KEY_HERE" > ~/.api-openrouter (Replace YOUR_API_KEY_HERE with your actual key)

  3. Other Settings: Copy the .env.example file to .env:

    bash cp .env.example .env

  4. Modify the .env file to set the remaining configuration values:

    • MAX_NEW_TOKENS: Maximum number of tokens for the response (default: 2048).
    • REDIS_URL: The URL of your Redis server (default: redis://localhost:6379).
    • FLASK_ENV, FLASK_APP: Optional, related to Flask if used elsewhere, not core to the MCP server/worker operation.

Running the Service

  1. Ensure Redis is running. If you installed it locally, you might need to start the Redis server process (e.g., redis-server command, or via a service manager).

  2. Start the RQ Worker: Open a terminal, activate your virtual environment (source .venv/bin/activate or similar), and run: bash python -m mcp_waifu_queue.worker This command starts the worker process, which will listen for jobs on the Redis queue defined in your .env file. Keep this terminal running.

  3. Start the MCP Server: Open another terminal, activate the virtual environment, and run the MCP server using a tool like uvicorn (you might need to install it: pip install uvicorn or uv pip install uvicorn): bash uvicorn mcp_waifu_queue.main:app --reload --port 8000 # Example port Replace 8000 with your desired port. The --reload flag is useful for development.

    Alternatively, you can use the start-services.sh script (primarily designed for Linux/macOS environments) which attempts to start Redis (if not running) and the worker in the background: ```bash

    Ensure the script is executable: chmod +x ./scripts/start-services.sh

    ./scripts/start-services.sh

    Then start the MCP server manually as shown above.

    ```

MCP API

The server provides the following MCP-compliant endpoints:

Tools

Resources

Testing

The project includes tests. Ensure you have installed the test dependencies (pip install -e .[test] or uv pip install -e .[test]).

Run tests using pytest:

pytest tests

Note: Tests might require mocking Redis (fakeredis) and potentially the OpenRouter API calls depending on their implementation.

Troubleshooting

Contributing

  1. Fork the repository.
  2. Create a new branch for your feature or bug fix (git checkout -b feature/your-feature-name).
  3. Make your changes and commit them (git commit -am 'Add some feature').
  4. Push your branch to your forked repository (git push origin feature/your-feature-name).
  5. Create a Pull Request on the original repository.

Please adhere to the project's coding standards and linting rules (ruff).

License

This project is licensed under the MIT-0 License - see the LICENSE file for details.

Source Code

GitHub repository

https://github.com/waifuai/mcp-waifu-queue