Uses environment variables via .env file for configuration management, allowing customization of service parameters like maximum token count and Redis connection details.
Leverages the Google Gemini API (gemini-2.5-pro-preview-03-25) for text generation in a conversational AI 'waifu' character, with request queuing for handling concurrent requests asynchronously.
Implements a queue system for asynchronous processing of AI generation requests, providing job status tracking and efficient handling of concurrent requests.
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.
gemini-2.5-pro-preview-03-25 ).FastMCP ..env ) y carga de clave API desde ~/.api-gemini .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:
generate_text (definida en main.py ).task_queue.py ).worker.py toma el trabajo de la cola.call_predict_response (desde utils.py ).call_predict_response llama a la función predict_response (en respond.py ), que interactúa con la API de Gemini.predict_response y almacenado como resultado del trabajo por RQ.job://{job_id} (definido en main.py ).pip o uv (instalador de paquetes de Python)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
venv o uv ):Usando venv (biblioteca estándar):uv (si está instalado):pip dentro de venv o uv ):Usando pip :uv :.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.YOUR_API_KEY_HERE con su clave real).env.example a .env :.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.redis-server o mediante un administrador de servicios).source .venv/bin/activate o similar) y ejecute:.env . Mantenga esta terminal en ejecución.uvicorn (es posible que necesite instalarla: pip install uvicorn o uv pip install uvicorn ):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:El servidor proporciona los siguientes puntos finales compatibles con MCP:
generate_text{"prompt": "Your text prompt here"} (Tipo: GenerateTextRequest ){"job_id": "rq:job:..."} (Un ID único para el trabajo en cola)job://{job_id}job_id (el ID devuelto por la herramienta generate_text ).{"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.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.
Gemini API key not found in .../.api-gemini or GEMINI_API_KEY environment variable . 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.~/.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.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.REDIS_URL especificada en .env .uvicorn ... ) esté ejecutándose y de que se esté conectando al host/puerto correcto.git checkout -b feature/your-feature-name ).git commit -am 'Add some feature' ).git push origin feature/your-feature-name ).Por favor, respete los estándares de codificación del proyecto y las reglas de linting ( ruff ).
Este proyecto está licenciado bajo la licencia MIT-0: consulte el archivo de LICENCIA para obtener más detalles.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Un servidor MCP que implementa un personaje 'waifu' de IA conversacional utilizando un servicio de generación de texto con cola de Redis y aceleración de GPU.