iGuat-MCP

Сервис MCP (Model Context Protocol) только для чтения, предназначенный для данных кампуса i桂航. Проект основан на Python, FastMCP и Streamable HTTP и предоставляет запросы расписания, классов и кампусов в виде стандартных инструментов, доступных для вызова AI-клиентами.

Этот проект предоставляет только возможности запроса и не изменяет данные мини-программы WeChat или вышестоящей учебной системы.

Возможности

• Получение полного списка семестров, текущего и следующего семестра

• Поиск классов по специальности, курсу и ключевому слову класса

• Запрос расписания для указанного класса, семестра и недели

• Запрос расписания для указанного лица с удалением полей идентификации перед возвратом

• Определение кампуса на основе информации о специальности

• Встроенный TTL-кэш расписания, ограничение параллелизма и проверка работоспособности

• Защита MCP и административных интерфейсов с помощью Bearer API Key

• Поддержка горячего обновления вышестоящего токена через административный интерфейс

• Поддержка развертывания через Docker, переменные окружения и Docker Secrets

Related MCP server: gaokao-helper-worker-mcp

Инструменты MCP

Технологический стек

• Python 3.11+

• MCP / FastMCP

• HTTPX

• Uvicorn

• Pytest

• Docker

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

Локальный запуск

git clone https://github.com/Strayed2SE/iGuat-MCP.git
cd iGuat-MCP

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[test]"

cp .env.example .env
# 按下方说明配置环境变量后启动
python server.py

Сервис по умолчанию прослушивает 0.0.0.0:8000:

• MCP: http://127.0.0.1:8000/mcp

• Проверка работоспособности: http://127.0.0.1:8000/healthz

Заголовки запросов MCP-клиента:

Authorization: Bearer <MCP_PUBLIC_API_KEY>

Docker

docker build -t iguat-mcp .
docker run --rm -p 8000:8000 --env-file .env iguat-mcp

В производственной среде рекомендуется использовать форму NAME_FILE для загрузки конфиденциальных настроек из Docker Secrets или файлов, доступных только для чтения:

docker run --rm -p 8000:8000 \
  -e IGUAT_USER_TOKEN_FILE=/run/secrets/iguat_token \
  -e IGUAT_MAIN_SIGN_KEY_FILE=/run/secrets/main_sign_key \
  -e MCP_PUBLIC_API_KEY_FILE=/run/secrets/public_key \
  -e MCP_ADMIN_API_KEY_FILE=/run/secrets/admin_key \
  --mount type=bind,src=/secure/secrets,dst=/run/secrets,ro \
  iguat-mcp

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

Скопируйте .env.example и настройте по необходимости:

Обновление вышестоящего токена

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

curl -X PUT http://127.0.0.1:8000/admin/token \
  -H "Authorization: Bearer <MCP_ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"token":"<NEW_TOKEN>"}'

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

pip install -e ".[test]"
pytest -q

Замечания по безопасности

• Не отправляйте реальные токены, ключи подписи, API-ключи или .env в репозиторий.

• Сервис не возвращает токены, подписи или поля личной идентификации MCP-клиентам.

• По умолчанию переменные системного прокси не читаются; устанавливайте IGUAT_TRUST_ENV=1 только если это действительно необходимо в среде развертывания.

Связанные проекты

• 桂航百科查询系统: база знаний кампуса и система интеллектуальных ответов на вопросы, интегрирующая этот MCP-сервис.