MCP Waifu Queue (Gemini Edition)
This project implements an MCP (Model Context Protocol) server for a conversational AI "waifu" character, leveraging the Google Gemini API via a Redis queue for asynchronous processing. It utilizes the FastMCP
library for simplified server setup and management.
Table of Contents
- Features
- Architecture
- Prerequisites
- Installation
- Configuration
- Running the Service
- MCP API
- Testing
- Troubleshooting
- Contributing
- License
Features
- Text generation using the Google Gemini API (
gemini-2.5-flash-preview-04-17
). - Request queuing using Redis for handling concurrent requests asynchronously.
- MCP-compliant API using
FastMCP
. - Job status tracking via MCP resources.
- Configuration via environment variables (
.env
file) and API key loading from~/.api-gemini
.
Architecture
The project consists of several key components:
main.py
: The main entry point, initializing theFastMCP
application and defining MCP tools/resources.respond.py
: Contains the core text generation logic using thegoogle-generativeai
library to interact with the Gemini API.task_queue.py
: Handles interactions with the Redis queue (usingpython-rq
), enqueuing generation requests.utils.py
: Contains utility functions, specificallycall_predict_response
which is executed by the worker to call the Gemini logic inrespond.py
.worker.py
: A Redis worker (python-rq
) that processes jobs from the queue, callingcall_predict_response
.config.py
: Manages configuration usingpydantic-settings
.models.py
: Defines Pydantic models for MCP request and response validation.
The flow of a request is as follows:
- A client sends a request to the
generate_text
MCP tool (defined inmain.py
). - The tool enqueues the request (prompt) to a Redis queue (handled by
task_queue.py
). - A
worker.py
process picks up the job from the queue. - The worker executes the
call_predict_response
function (fromutils.py
). call_predict_response
calls thepredict_response
function (inrespond.py
), which interacts with the Gemini API.- The generated text (or an error message) is returned by
predict_response
and stored as the job result by RQ. - The client can retrieve the job status and result using the
job://{job_id}
MCP resource (defined inmain.py
).
Prerequisites
- Python 3.7+
pip
oruv
(Python package installer)- Redis server (installed and running)
- A Google Gemini API Key
You can find instructions for installing Redis on your system on the official Redis website: https://redis.io/docs/getting-started/ You can obtain a Gemini API key from Google AI Studio: https://aistudio.google.com/app/apikey
Installation
- Clone the repository:Copy
- Create and activate a virtual environment (using
venv
oruv
):Usingvenv
(standard library):UsingCopyuv
(if installed):Copy - Install dependencies (using
pip
within the venv oruv
):Usingpip
:UsingCopyuv
:Copy
Configuration
- API Key: Create a file named
.api-gemini
in your home directory (~/.api-gemini
) and place your Google Gemini API key inside it. Ensure the file has no extra whitespace.(ReplaceCopyYOUR_API_KEY_HERE
with your actual key) - Other Settings: Copy the
.env.example
file to.env
:Copy - Modify the
.env
file to set the remaining configuration values:MAX_NEW_TOKENS
: Maximum number of tokens for the Gemini 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
- 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). - Start the RQ Worker:
Open a terminal, activate your virtual environment (
source .venv/bin/activate
or similar), and run:This command starts the worker process, which will listen for jobs on the Redis queue defined in yourCopy.env
file. Keep this terminal running. - 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
oruv pip install uvicorn
):ReplaceCopy8000
with your desired port. The--reload
flag is useful for development.Alternatively, you can use thestart-services.sh
script (primarily designed for Linux/macOS environments) which attempts to start Redis (if not running) and the worker in the background:Copy
MCP API
The server provides the following MCP-compliant endpoints:
Tools
generate_text
- Description: Sends a text generation request to the Gemini API via the background queue.
- Input:
{"prompt": "Your text prompt here"}
(Type:GenerateTextRequest
) - Output:
{"job_id": "rq:job:..."}
(A unique ID for the queued job)
Resources
job://{job_id}
- Description: Retrieves the status and result of a previously submitted job.
- URI Parameter:
job_id
(The ID returned by thegenerate_text
tool). - Output:
{"status": "...", "result": "..."}
(Type:JobStatusResponse
)status
: The current state of the job (e.g., "queued", "started", "finished", "failed"). RQ uses slightly different terms internally ("started" vs "processing", "finished" vs "completed"). The resource maps these.result
: The generated text from Gemini if the job status is "completed", otherwisenull
. If the job failed, the result might benull
or contain error information depending on RQ's handling.
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
:
Note: Tests might require mocking Redis (fakeredis
) and potentially the Gemini API calls depending on their implementation.
Troubleshooting
- Error:
Gemini API key not found in .../.api-gemini or GEMINI_API_KEY environment variable
: Ensure you have created the~/.api-gemini
file in your home directory and placed your valid Gemini API key inside it. Alternatively, ensure theGEMINI_API_KEY
environment variable is set as a fallback. - Error during Gemini API call (e.g., AuthenticationError, PermissionDenied): Double-check that the API key in
~/.api-gemini
(or the fallback environment variable) is correct and valid. Ensure the API is enabled for your Google Cloud project if applicable. - Jobs stuck in "queued": Verify that the RQ worker (
python -m mcp_waifu_queue.worker
) is running in a separate terminal and connected to the same Redis instance specified in.env
. Check the worker logs for errors. - ConnectionRefusedError (Redis): Make sure your Redis server is running and accessible at the
REDIS_URL
specified in.env
. - MCP Server Connection Issues: Ensure the MCP server (
uvicorn ...
) is running and you are connecting to the correct host/port.
Contributing
- Fork the repository.
- Create a new branch for your feature or bug fix (
git checkout -b feature/your-feature-name
). - Make your changes and commit them (
git commit -am 'Add some feature'
). - Push your branch to your forked repository (
git push origin feature/your-feature-name
). - Create a new 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.
This server cannot be installed
An MCP server that implements a conversational AI 'waifu' character using a text generation service with Redis queuing and GPU acceleration.