Cola de Waifu de MCP (Edición Géminis)

Este proyecto implementa un servidor MCP (Protocolo de Contexto de Modelo) para un personaje "waifu" con IA conversacional, aprovechando la API de Google Gemini mediante una cola de Redis para el procesamiento asíncrono. Utiliza la biblioteca FastMCP para simplificar la configuración y la gestión del servidor.

Tabla de contenido

• Características

• Arquitectura

• Prerrequisitos

• Instalación

• Configuración

• Ejecución del servicio

• API de MCP

• Pruebas

• Solución de problemas

• Contribuyendo

• Licencia

Características

• Generación de texto mediante la API de Google Gemini ( gemini-2.5-pro-preview-03-25 ).

• Cola de solicitudes mediante Redis para gestionar solicitudes simultáneas de forma asincrónica.

• API compatible con MCP que utiliza FastMCP .

• Seguimiento del estado del trabajo a través de recursos de MCP.

• Configuración mediante variables de entorno (archivo .env ) y carga de clave API desde ~/.api-gemini .

Arquitectura

El proyecto consta de varios componentes clave:

• main.py : el punto de entrada principal, que inicializa la aplicación FastMCP y define herramientas/recursos de MCP.

• respond.py : contiene la lógica de generación de texto principal que utiliza la biblioteca google-generativeai para interactuar con la API de Gemini.

• task_queue.py : maneja las interacciones con la cola de Redis (usando python-rq ), poniendo en cola las solicitudes de generación.

• utils.py : contiene funciones de utilidad, específicamente call_predict_response que es ejecutada por el trabajador para llamar a la lógica Gemini en respond.py .

• worker.py : un trabajador de Redis ( python-rq ) que procesa trabajos de la cola, llamando call_predict_response .

• config.py : administra la configuración mediante pydantic-settings .

• models.py : define modelos de Pydantic para la validación de solicitudes y respuestas de MCP.

El flujo de una solicitud es el siguiente:

1. Un cliente envía una solicitud a la herramienta MCP generate_text (definida en main.py ).

2. La herramienta pone en cola la solicitud (prompt) en una cola de Redis (manejada por task_queue.py ).

3. Un proceso worker.py toma el trabajo de la cola.

4. El trabajador ejecuta la función call_predict_response (desde utils.py ).

5. call_predict_response llama a la función predict_response (en respond.py ), que interactúa con la API de Gemini.

6. El texto generado (o un mensaje de error) es devuelto por predict_response y almacenado como resultado del trabajo por RQ.

7. El cliente puede recuperar el estado y el resultado del trabajo utilizando el recurso MCP job://{job_id} (definido en main.py ).

Prerrequisitos

• Python 3.7+

• pip o uv (instalador de paquetes de Python)

• Servidor Redis (instalado y en funcionamiento)

• Una clave API de Google Gemini

Puede encontrar instrucciones para instalar Redis en su sistema en el sitio web oficial de Redis: https://redis.io/docs/getting-started/ Puede obtener una clave API de Gemini de Google AI Studio: https://aistudio.google.com/app/apikey

Instalación

1. Clonar el repositorio:

   git clone <YOUR_REPOSITORY_URL> cd mcp-waifu-queue

2. Crear y activar un entorno virtual (usando venv o uv ):

   Usando

   python -m venv .venv source .venv/bin/activate # On Linux/macOS # .venv\Scripts\activate # On Windows CMD # source .venv/Scripts/activate # On Windows Git Bash/PowerShell Core

   Usando

   # Ensure uv is installed (e.g., pip install uv) python -m uv venv .venv source .venv/bin/activate # Or equivalent activation for your shell

3. Instalar dependencias (usando pip dentro de venv o uv ):

   Usando

   pip install -e .[test] # Installs package in editable mode with test extras

   Usando

   # Ensure uv is installed inside the venv if desired, or use the venv's python # .venv/Scripts/python.exe -m pip install uv # Example for Windows .venv/Scripts/python.exe -m uv pip install -e .[test] # Example for Windows # python -m uv pip install -e .[test] # If uv is in PATH after venv activation

Configuración

1. Clave API: Crea un archivo llamado .api-gemini en tu directorio personal ( ~/.api-gemini ) e introduce tu clave API de Google Gemini. Asegúrate de que el archivo no contenga espacios en blanco.

   echo "YOUR_API_KEY_HERE" > ~/.api-gemini

   (Reemplace

2. Otras configuraciones: Copie el archivo .env.example a .env :

   cp .env.example .env

3. Modifique el archivo .env para establecer los valores de configuración restantes:

   • MAX_NEW_TOKENS : Número máximo de tokens para la respuesta de Gemini (predeterminado: 2048 ).

   • REDIS_URL : la URL de su servidor Redis (predeterminado: redis://localhost:6379 ).

   • FLASK_ENV , FLASK_APP : Opcional, relacionado con Flask si se usa en otro lugar, no es fundamental para la operación del servidor/trabajador MCP.

Ejecución del servicio

1. Asegúrese de que Redis esté ejecutándose. Si lo instaló localmente, es posible que deba iniciar el proceso del servidor Redis (por ejemplo, con el comando redis-server o mediante un administrador de servicios).

2. Inicie RQ Worker: abra una terminal, active su entorno virtual ( source .venv/bin/activate o similar) y ejecute:

   python -m mcp_waifu_queue.worker

   Este comando inicia el proceso de trabajo, que escuchará los trabajos en la cola de Redis definida en el archivo .env . Mantenga esta terminal en ejecución.

3. Inicie el servidor MCP: abra otra terminal, active el entorno virtual y ejecute el servidor MCP usando una herramienta como uvicorn (es posible que necesite instalarla: pip install uvicorn o uv pip install uvicorn ):

   uvicorn mcp_waifu_queue.main:app --reload --port 8000 # Example port

   Reemplace 8000 con el puerto deseado. El parámetro --reload es útil para el desarrollo.

   Como alternativa, puede utilizar el script start-services.sh (diseñado principalmente para entornos Linux/macOS) que intenta iniciar Redis (si no está en ejecución) y el trabajador en segundo plano:

   # Ensure the script is executable: chmod +x ./scripts/start-services.sh ./scripts/start-services.sh # Then start the MCP server manually as shown above.

API de MCP

El servidor proporciona los siguientes puntos finales compatibles con MCP:

Herramientas

• generate_text

  • Descripción: Envía una solicitud de generación de texto a la API de Gemini a través de la cola en segundo plano.

  • Entrada: {"prompt": "Your text prompt here"} (Tipo: GenerateTextRequest )

  • Salida: {"job_id": "rq:job:..."} (Un ID único para el trabajo en cola)

Recursos

• job://{job_id}

  • Descripción: Recupera el estado y el resultado de un trabajo enviado previamente.

  • Parámetro URI: job_id (el ID devuelto por la herramienta generate_text ).

  • Salida: {"status": "...", "result": "..."} (Tipo: JobStatusResponse )

    • status : El estado actual del trabajo (p. ej., "en cola", "iniciado", "finalizado", "fallido"). RQ utiliza términos ligeramente diferentes internamente ("iniciado" vs. "en proceso", "finalizado" vs. "completado"). El recurso los asigna.

    • result : El texto generado por Gemini si el estado del trabajo es "completado"; de lo contrario, null . Si el trabajo falló, el resultado podría ser null o contener información de error, dependiendo del procesamiento de la solicitud.

Pruebas

El proyecto incluye pruebas. Asegúrese de tener instaladas las dependencias de prueba ( pip install -e .[test] o uv pip install -e .[test] ).

Ejecutar pruebas usando pytest :

Nota: Las pruebas pueden requerir simular Redis ( fakeredis ) y potencialmente las llamadas a la API de Gemini dependiendo de su implementación.

Solución de problemas

• Error: . Asegúrese de haber creado el archivo ~/.api-gemini en su directorio personal y de haber guardado en él su clave de API de Gemini válida. Como alternativa, asegúrese de que la variable de entorno GEMINI_API_KEY esté configurada como alternativa.

• Error durante la llamada a la API de Gemini (p. ej., AuthenticationError, PermissionDenied) : Verifique que la clave de API en ~/.api-gemini (o la variable de entorno de respaldo) sea correcta y válida. Asegúrese de que la API esté habilitada para su proyecto de Google Cloud, si corresponde.

• Trabajos bloqueados en "en cola" : Verifique que el trabajador de RQ ( python -m mcp_waifu_queue.worker ) se esté ejecutando en una terminal independiente y conectado a la misma instancia de Redis especificada en .env . Revise los registros del trabajador para detectar errores.

• ConnectionRefusedError (Redis) : asegúrese de que su servidor Redis esté ejecutándose y sea accesible en la REDIS_URL especificada en .env .

• Problemas de conexión del servidor MCP : asegúrese de que el servidor MCP ( uvicorn ... ) esté ejecutándose y de que se esté conectando al host/puerto correcto.

Contribuyendo

1. Bifurcar el repositorio.

2. Crea una nueva rama para tu característica o corrección de error ( git checkout -b feature/your-feature-name ).

3. Realice sus cambios y confirme ( git commit -am 'Add some feature' ).

4. Envía tu rama a tu repositorio bifurcado ( git push origin feature/your-feature-name ).

5. Cree una nueva solicitud de extracción en el repositorio original.

Por favor, respete los estándares de codificación del proyecto y las reglas de linting ( ruff ).

Licencia

Este proyecto está licenciado bajo la licencia MIT-0: consulte el archivo de LICENCIA para obtener más detalles.