Очередь MCP Waifu

Этот проект реализует сервер MCP (Model Context Protocol) для разговорного ИИ-персонажа «вайфу», использующий API OpenRouter через очередь Redis для асинхронной обработки. Он использует библиотеку FastMCP для упрощенной настройки и управления сервером.

Содержание

• Возможности

• Архитектура

• Предварительные требования

• Установка

• Конфигурация

• Запуск службы

• API MCP

• Тестирование

• Устранение неполадок

• Участие в разработке

• Лицензия

Related MCP server: local-agent-context

Возможности

• Генерация текста через OpenRouter с использованием модели из ~/.model-openrouter или openrouter/free.

• Очередь запросов с использованием Redis для асинхронной обработки параллельных запросов.

• API, совместимый с MCP, с использованием FastMCP.

• Отслеживание статуса заданий через ресурсы MCP.

• Конфигурация через переменные окружения (файл .env).

• Загрузка ключей API:

  • OpenRouter: OPENROUTER_API_KEY или ~/.api-openrouter

• Файлы выбора модели в домашней директории:

  • ~/.model-openrouter для имени модели OpenRouter

Архитектура

Проект состоит из нескольких ключевых компонентов:

• main.py: Основная точка входа, инициализирующая приложение FastMCP и определяющая инструменты/ресурсы MCP.

• respond.py: Содержит основную логику генерации текста с использованием API OpenRouter.

• task_queue.py: Обрабатывает взаимодействие с очередью Redis (используя python-rq), ставя запросы на генерацию в очередь.

• utils.py: Содержит вспомогательные функции, в частности call_predict_response, которая выполняется воркером для вызова логики генерации в respond.py.

• worker.py: Воркер Redis (python-rq), который обрабатывает задания из очереди, вызывая call_predict_response.

• config.py: Управляет конфигурацией с помощью pydantic-settings.

• models.py: Определяет модели Pydantic для валидации запросов и ответов MCP.

Поток запроса выглядит следующим образом:

1. Клиент отправляет запрос к инструменту MCP generate_text (определен в main.py).

2. Инструмент ставит запрос (промпт) в очередь Redis (обрабатывается task_queue.py).

3. Процесс worker.py забирает задание из очереди.

4. Воркер выполняет функцию call_predict_response (из utils.py).

5. call_predict_response вызывает функцию predict_response (в respond.py), которая взаимодействует с API OpenRouter.

6. Сгенерированный текст (или сообщение об ошибке) возвращается функцией predict_response и сохраняется как результат задания в RQ.

7. Клиент может получить статус и результат задания, используя ресурс MCP job://{job_id} (определен в 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

Предварительные требования

• Python 3.7+

• pip или uv (установщик пакетов Python)

• Сервер Redis (установлен и запущен)

• Ключ API OpenRouter

Инструкции по установке Redis в вашей системе можно найти на официальном сайте Redis: https://redis.io/docs/getting-started/ Вы можете получить ключ API OpenRouter здесь: https://openrouter.ai/

Установка

1. Клонируйте репозиторий:

   git clone <YOUR_REPOSITORY_URL>
   cd mcp-waifu-queue

2. Создайте и активируйте виртуальное окружение с помощью uv:

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

3. Установите зависимости:

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

Конфигурация

1. Имена моделей через файлы в $HOME:

   • Файл модели OpenRouter:

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

2. Ключи API: Предпочтительно через переменные окружения с резервным копированием в файл:

   • OpenRouter: OPENROUTER_API_KEY или ~/.api-openrouter GXP6

   (Замените YOUR_API_KEY_HERE на ваш реальный ключ)

3. Другие настройки: Скопируйте файл .env.example в .env:

   cp .env.example .env

4. Измените файл .env, чтобы задать остальные значения конфигурации:

   • MAX_NEW_TOKENS: Максимальное количество токенов для ответа (по умолчанию: 2048).

   • REDIS_URL: URL вашего сервера Redis (по умолчанию: redis://localhost:6379).

   • FLASK_ENV, FLASK_APP: Опционально, относится к Flask, если он используется где-то еще, не является основным для работы сервера/воркера MCP.

Запуск службы

1. Убедитесь, что Redis запущен. Если вы установили его локально, вам может потребоваться запустить процесс сервера Redis (например, командой redis-server или через менеджер служб).

2. Запустите воркер RQ: Откройте терминал, активируйте виртуальное окружение (source .venv/bin/activate или аналогично) и выполните:

   python -m mcp_waifu_queue.worker

   Эта команда запускает процесс воркера, который будет прослушивать задания в очереди Redis, определенной в вашем файле .env. Оставьте этот терминал запущенным.

3. Запустите сервер MCP: Откройте другой терминал, активируйте виртуальное окружение и запустите сервер MCP с помощью инструмента типа uvicorn (возможно, вам потребуется установить его: pip install uvicorn или uv pip install uvicorn):

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

   Замените 8000 на желаемый порт. Флаг --reload полезен для разработки.

   Альтернативно, вы можете использовать скрипт start-services.sh (предназначен в основном для сред Linux/macOS), который пытается запустить Redis (если он не запущен) и воркер в фоновом режиме:

   # 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

Сервер предоставляет следующие конечные точки, совместимые с MCP:

Инструменты

• generate_text

  • Описание: Отправляет запрос на генерацию текста в API OpenRouter через фоновую очередь.

  • Входные данные: {"prompt": "Ваш текстовый промпт здесь"} (Тип: GenerateTextRequest)

  • Выходные данные: {"job_id": "rq:job:..."} (Уникальный ID для задания в очереди)

Ресурсы

• job://{job_id}

  • Описание: Получает статус и результат ранее отправленного задания.

  • Параметр URI: job_id (ID, возвращенный инструментом generate_text).

  • Выходные данные: {"status": "...", "result": "..."} (Тип: JobStatusResponse)

    • status: Текущее состояние задания (например, "queued", "started", "finished", "failed"). RQ внутренне использует немного другие термины ("started" против "processing", "finished" против "completed"). Ресурс выполняет их сопоставление.

    • result: Сгенерированный текст, если статус задания "completed", в противном случае null. Если задание завершилось ошибкой, результат может быть null или содержать информацию об ошибке в зависимости от обработки RQ.

Тестирование

Проект включает тесты. Убедитесь, что вы установили тестовые зависимости (pip install -e .[test] или uv pip install -e .[test]).

Запустите тесты с помощью pytest:

pytest tests

Примечание: Тесты могут потребовать имитации Redis (fakeredis) и, возможно, вызовов API OpenRouter в зависимости от их реализации.

Устранение неполадок

• Ошибка: OpenRouter API key not available: Убедитесь, что OPENROUTER_API_KEY задан или файл ~/.api-openrouter существует и содержит ваш ключ в одну строку (без пробелов).

• Задания застревают в "queued": Проверьте, что воркер RQ (python -m mcp_waifu_queue.worker) запущен в отдельном терминале и подключен к тому же экземпляру Redis, который указан в .env. Проверьте логи воркера на наличие ошибок.

• ConnectionRefusedError (Redis): Убедитесь, что ваш сервер Redis запущен и доступен по адресу REDIS_URL, указанному в .env.

• Проблемы с подключением к серверу MCP: Убедитесь, что сервер MCP (uvicorn ...) запущен и вы подключаетесь к правильному хосту/порту.

Участие в разработке

1. Сделайте форк репозитория.

2. Создайте новую ветку для вашей функции или исправления ошибки (git checkout -b feature/your-feature-name).

3. Внесите изменения и закоммитьте их (git commit -am 'Add some feature').

4. Отправьте ветку в ваш форкнутый репозиторий (git push origin feature/your-feature-name).

5. Создайте Pull Request в оригинальный репозиторий.

Пожалуйста, придерживайтесь стандартов кодирования и правил линтинга проекта (ruff).

Лицензия

Этот проект лицензирован по лицензии MIT-0 — подробности см. в файле LICENSE.