Omnivox MCP

Сервер MCP, который предоставляет доступ к студенческим порталам колледжей Квебека (Omnivox/Lea) через инструменты MCP и REST-шлюз инструментов.

Он запускает постоянный браузер Puppeteer, выполнивший вход в Omnivox, и выполняет запросы через собственный JavaScript сайта — поэтому аутентификация challenge-response, куки и кодировка обрабатываются нативно.

Возможности

• 30 инструментов MCP — курсы, оценки, расписание, календарь, обмен сообщениями (MIO), документы, задания, новости колледжа

• Два режима транспорта — HTTP (по умолчанию, Express-сервер с MCP через HTTP + REST-шлюз инструментов) или stdio (устаревший, не рекомендуется)

• REST-шлюз инструментов — все инструменты MCP доступны в виде обычных HTTP-эндпоинтов для агентов, не поддерживающих MCP

• Загрузка файлов — прямая передача бинарных данных или временные ссылки для браузера (время жизни 15 минут)

• Внутренние сообщения — чтение, поиск, отправка, отметка, перемещение и удаление сообщений MIO

• Постоянная сессия — профиль Chrome сохраняется между перезапусками, не требуется повторный вход в систему

Related MCP server: Canvas MCP Server

Быстрый старт

# 1. Clone and install
git clone https://github.com/Beat-YT/omnivox-mcp.git
cd omnivox-mcp
npm install

# 2. Authenticate (first time only)
cd omnivox-connection
npm install && npm start
# Log in through the Electron window, save the data files

# 3. Start the server
cd ..
npm start              # HTTP mode (default) — Express server on port 3000
npm run start:stdio    # stdio mode (deprecated, not recommended)

Режим HTTP (по умолчанию): запускает Express-сервер с MCP через HTTP на /mcp?key=... и REST-шлюз инструментов. Ключ доступа автоматически генерируется в ~/.omnivox/accessKey.txt.

Режим stdio (устаревший, не рекомендуется): MCP-клиент запускает сервер как подпроцесс и общается через stdin/stdout. Express-сервер не требуется, ключ доступа не нужен.

Каждый экземпляр обслуживает один аккаунт Omnivox. Сервер поддерживает одну сессию браузера, привязанную к аккаунту, с которым вы вошли.

Повторная аутентификация

Если ваша сессия истекла или вам нужно войти в другой аккаунт, сбросьте данные сессии и перезапустите приложение Electron:

npm run reset
cd omnivox-connection && npm start
# Log in, wait for the success dialog, then close the window
cd .. && npm start

npm run reset удаляет ~/.omnivox/browser/, cookies.json и config.json, чтобы сервер запустился с чистого листа при следующем запуске.

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

Задайте эти переменные как переменные окружения или в файле .env в корне проекта:

Использование

MCP (для ИИ-ассистентов)

Режим stdio (устаревший, не рекомендуется): добавьте сервер в конфигурацию MCP-клиента — он запускает сервер как подпроцесс. Используйте npm run start:stdio. См. AGENT_SETUP.md для настройки подключения.

Режим HTTP: подключите ваш MCP-клиент к http://localhost:3000/mcp?key=YOUR_KEY через транспорт Streamable HTTP.

В любом случае ИИ получает доступ ко всем 30 инструментам — спрашивайте его о своих оценках, расписании, заданиях или сообщениях на естественном языке.

REST-шлюз инструментов (режим HTTP)

Для агентов или приложений, которые не поддерживают MCP, все инструменты доступны в виде обычных HTTP-эндпоинтов:

# List all available tools
curl http://localhost:3000/tools -H "x-mcp-auth: YOUR_KEY"

# Get your courses
curl -X POST http://localhost:3000/tools/get-courses-summary \
  -H "x-mcp-auth: YOUR_KEY" -d '{}'

# Check your grades
curl -X POST http://localhost:3000/tools/get-grades-summary \
  -H "x-mcp-auth: YOUR_KEY" -d '{}'

# Read your inbox
curl -X POST http://localhost:3000/tools/get-mio-messages \
  -H "x-mcp-auth: YOUR_KEY" -d '{}'

Эндпоинт инструментов принимает JSON-тела независимо от заголовка Content-Type — явно задавать его не нужно.

Прокси Omnivox (режим HTTP)

Сервер предоставляет сквозной прокси на /Mobl/*, который пересылает запросы напрямую в мобильный API Omnivox через аутентифицированную сессию браузера. Поддерживаются любые HTTP-методы и типы содержимого.

# Example: hit an Omnivox mobile API endpoint directly
curl http://localhost:3000/Mobl/some/endpoint \
  -H "x-mcp-auth: YOUR_KEY" -H "Content-Type: application/json" -d '{}'

Это полезно, когда вам нужно вызвать эндпоинт Omnivox, который не обёрнут в инструмент MCP.

Создавайте собственные проекты

REST-шлюз инструментов предназначен не только для ИИ — это полноценный API Omnivox, который можно использовать в любом проекте:

• Панель оценок — выгружайте свои оценки в собственное веб-приложение или таблицу

• Виджет расписания — отображайте своё еженедельное расписание на главном экране или в виджете рабочего стола

• Трекер заданий — создавайте уведомления о новых заданиях или предстоящих сроках

• Бот для Discord/Slack — получайте уведомления о новых оценках или сообщениях

• Мобильное приложение — создайте собственный клиент Omnivox только с нужными вам функциями

• Экспорт данных — архивируйте свои оценки, документы и сообщения для личных записей

Подойдёт любой язык, который может выполнять HTTP-запросы — Python, JavaScript, Swift, Kotlin, Go, что угодно. Используйте GET /tools, чтобы узнать все доступные инструменты и их входные схемы.

Документация

Полная документация — в Wiki:

• Setup — предварительные требования, установка, переменные окружения

• Architecture — как устроена система

• MCP Tools — все 30 инструментов с параметрами

• REST Tool Gateway — использование шлюза инструментов для агентов, не поддерживающих MCP

• Authentication — ключи доступа, веб-токены, управление сессиями

Безопасно ли это?

Мы никогда не видим ваш пароль или данные. Всё работает локально на вашем компьютере (или вашем собственном сервере):

• Вы входите сами через приложение Electron — ваш пароль Omnivox вводится непосредственно на официальной странице входа Omnivox. Этот проект никогда не запрашивает, не хранит и не передаёт ваш пароль.

• Никаких внешних серверов. MCP-сервер работает полностью на вашем компьютере. Ваши данные никогда не проходят через сторонние сервисы — все запросы идут напрямую между вашим сервером и Omnivox.

• Сессия остаётся локальной. Сессия браузера и куки хранятся в ~/.omnivox/ на вашем диске. Доступ к ним есть только у вас.

• Открытый исходный код. Весь код здесь — вы можете его изучить. Никаких скрытых сетевых вызовов, аналитики или телеметрии.

Рекомендации по безопасности

• Никогда не открывайте сервер без HTTPS. Используйте обратный прокси (например, Nginx) с TLS. Пример конфигурации см. в вики Setup.

• Держите ~/.omnivox/ в тайне. В нём хранятся ваша сессия Omnivox и ключ доступа. Относитесь к accessKey.txt как к паролю — не делитесь им ни с кем.

• См. Security Precautions для получения дополнительной информации.

Отказ от ответственности

Этот проект является неофициальным и не связан с Skytech Communications, Omnivox или любым колледжем Квебека, не одобрен ими и не имеет к ним отношения. Он предоставляется как есть только для личного и образовательного использования. Используйте его на свой страх и риск — авторы не несут ответственности за любые последствия его использования, включая, помимо прочего, ограничения учётной записи, потерю данных или нарушение условий обслуживания вашего учебного заведения.

Лицензия

ISC