Cola de Waifu MCP

Este proyecto implementa un servidor MCP (Model Context Protocol) para un personaje "waifu" de IA conversacional, aprovechando la API de OpenRouter a través de una cola Redis para el procesamiento asíncrono. Utiliza la biblioteca FastMCP para una configuración y gestión simplificadas del servidor.

Tabla de contenidos

• Características

• Arquitectura

• Requisitos previos

• Instalación

• Configuración

• Ejecución del servicio

• API MCP

• Pruebas

• Solución de problemas

• Contribución

• Licencia

Related MCP server: local-agent-context

Características

• Generación de texto a través de OpenRouter utilizando el modelo de ~/.model-openrouter o openrouter/free.

• Cola de solicitudes mediante Redis para gestionar solicitudes concurrentes de forma asíncrona.

• API compatible con MCP utilizando FastMCP.

• Seguimiento del estado del trabajo mediante recursos MCP.

• Configuración mediante variables de entorno (archivo .env).

• Carga de clave API:

  • OpenRouter: OPENROUTER_API_KEY o ~/.api-openrouter

• Archivos de selección de modelo en el directorio de inicio:

  • ~/.model-openrouter para el nombre del modelo de OpenRouter

Arquitectura

El proyecto consta de varios componentes clave:

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

• respond.py: Contiene la lógica central de generación de texto utilizando la API de OpenRouter.

• task_queue.py: Gestiona las interacciones con la cola Redis (usando python-rq), encolando 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 de generación en respond.py.

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

• config.py: Gestiona la configuración utilizando pydantic-settings.

• models.py: Define modelos Pydantic para la validación de solicitudes y respuestas 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 encola la solicitud (prompt) en una cola Redis (gestionada por task_queue.py).

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

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

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

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).

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

Requisitos previos

• Python 3.7+

• pip o uv (instalador de paquetes de Python)

• Servidor Redis (instalado y en ejecución)

• Una clave API de OpenRouter

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 OpenRouter en: https://openrouter.ai/

Instalación

1. Clone el repositorio:

   git clone <YOUR_REPOSITORY_URL>
   cd mcp-waifu-queue

2. Cree y active un entorno virtual usando uv:

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

3. Instale las dependencias:

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

Configuración

1. Nombres de modelo mediante archivos en $HOME:

   • Archivo de modelo de OpenRouter:

     echo "openrouter/free" > ~/.model-openrouter

2. Claves API: Preferiblemente mediante variables de entorno con respaldo en archivo:

   • OpenRouter: OPENROUTER_API_KEY o ~/.api-openrouter GXP6

   (Reemplace YOUR_API_KEY_HERE con su clave real)

3. Otros ajustes: Copie el archivo .env.example a .env:

   cp .env.example .env

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

   • MAX_NEW_TOKENS: Número máximo de tokens para la respuesta (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é en ejecución. Si lo instaló localmente, es posible que deba iniciar el proceso del servidor Redis (por ejemplo, el comando redis-server, o a través de un gestor de servicios).

2. Inicie el trabajador RQ: 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 del trabajador, que escuchará los trabajos en la cola Redis definida en su archivo .env. Mantenga esta terminal abierta.

3. Inicie el servidor MCP: Abra otra terminal, active el entorno virtual y ejecute el servidor MCP utilizando una herramienta como uvicorn (es posible que deba 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. La bandera --reload es útil para el desarrollo.

   Alternativamente, puede usar el script start-services.sh (diseñado principalmente para entornos Linux/macOS) que intenta iniciar Redis (si no se está ejecutando) 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 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 OpenRouter a través de la cola en segundo plano.

  • Entrada: {"prompt": "Su prompt de texto aquí"} (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 anteriormente.

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

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

    • status: El estado actual del trabajo (por ejemplo, "queued", "started", "finished", "failed"). RQ utiliza términos ligeramente diferentes internamente ("started" vs "processing", "finished" vs "completed"). El recurso los mapea.

    • result: El texto generado si el estado del trabajo es "completed", de lo contrario null. Si el trabajo falló, el resultado podría ser null o contener información de error dependiendo del manejo de RQ.

Pruebas

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

Ejecute las pruebas usando pytest:

pytest tests

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

Solución de problemas

• Error: OpenRouter API key not available: Asegúrese de que OPENROUTER_API_KEY esté configurado o que ~/.api-openrouter exista con su clave en una sola línea (sin espacios).

• Trabajos atascados en "queued": Verifique que el trabajador RQ (python -m mcp_waifu_queue.worker) se esté ejecutando en una terminal separada y conectado a la misma instancia de Redis especificada en .env. Compruebe los registros del trabajador en busca de errores.

• ConnectionRefusedError (Redis): Asegúrese de que su servidor Redis esté en ejecución y accesible en la REDIS_URL especificada en .env.

• Problemas de conexión al servidor MCP: Asegúrese de que el servidor MCP (uvicorn ...) se esté ejecutando y que se esté conectando al host/puerto correcto.

Contribución

1. Haga un fork del repositorio.

2. Cree una nueva rama para su característica o corrección de errores (git checkout -b feature/nombre-de-su-caracteristica).

3. Realice sus cambios y confírmelos (git commit -am 'Añadir alguna característica').

4. Envíe su rama al repositorio bifurcado (git push origin feature/nombre-de-su-caracteristica).

5. Cree una Pull Request en el repositorio original.

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

Licencia

Este proyecto tiene la licencia MIT-0; consulte el archivo LICENSE para obtener más detalles.