METU SAIS API & MCP Server

Современный сервер Model Context Protocol (MCP) и сервис FastAPI для информационной системы Student Affairs Information System (SAIS / student.metu.edu.tr) Ближневосточного технического университета (METU / ODTÜ).

Подключает ваших ИИ-ассистентов (таких как OpenCode, Claude Desktop и Cursor) напрямую к METU SAIS с реальной аутентификацией и структурированным разбором данных.

Возможности

• Аутентификация SSO: Обрабатывает реальный процесс входа в METU SSO (/sso/backend/request/user/signin) и проверку токенов сеанса.

• Прокси-скрапер и HTML-парсер: Автоматически устанавливает аутентифицированные прокси-сеансы (/proxy/Student_Information/) и преобразует записи студентов в структурированный JSON.

• MCP-сервер (MCP 2.x SDK): Предоставляет типизированные инструменты через стандартный ввод-вывод (stdio).

• REST-сервис FastAPI: Альтернативный HTTP REST-бэкенд для интеграций.

• Конфиденциальность и безопасность: Никакого логирования или раскрытия учетных данных. Учетные данные остаются локально в вашем файле .env, который игнорируется Git.

Related MCP server: SABIS MCP Server

Доступные MCP-инструменты

Установка и настройка

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

• Python >= 3.11

• uv (рекомендуется) или pip

2. Установка зависимостей

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

3. Настройка учетных данных

Скопируйте .env.example в .env и введите свои учетные данные METU:

cp .env.example .env

Отредактируйте .env:

SAIS_USERNAME=your_metu_username
SAIS_PASSWORD=your_metu_password
LOCALE=tr
PORT=8300

[!NOTE] .env указан в .gitignore и никогда не будет закоммичен.

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

В этот репозиторий уже включён файл opencode.json.

Использование на уровне проекта

При запуске OpenCode внутри этого репозитория:

opencode

OpenCode автоматически подключится к MCP-серверу metu-sais.

Глобальное использование (из любой директории)

Чтобы использовать инструменты METU SAIS в любом проекте OpenCode, добавьте сервер в ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "metu-sais": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "/absolute/path/to/metu-sais-mcp",
        "run",
        "metu-sais-mcp"
      ],
      "enabled": true
    }
  }
}

Проверка подключения

opencode mcp list

Вы должны увидеть:

●  ✓ metu-sais connected

Запуск MCP-сервера отдельно

Вы можете запустить MCP-сервер напрямую через стандартный ввод-вывод:

uv run metu-sais-mcp

Запуск REST API

Чтобы запустить сервер FastAPI:

uv run uvicorn api.main:app --port 8300 --reload

Интерактивная документация API будет доступна по адресу:

• Swagger UI: http://localhost:8300/docs

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

REST-эндпоинты

• GET /api/sais/info — Информация о студенте

• GET /api/sais/schedule — Расписание занятий

• GET /api/sais/transcript — История успеваемости

• GET /api/sais/announcements — Объявления портала

• GET|POST|PUT|DELETE /api/connections — CRUD-управление соединениями

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

Запустите автоматический набор тестов с помощью pytest:

uv run pytest -v

Набор тестов включает:

• Модульные тесты для HTML-парсеров (parse_student_info, parse_schedule, parse_transcript, parse_announcements).

• Тесты регистрации MCP-инструментов и вызова инструментов.

• Тесты REST-эндпоинтов FastAPI.

• Живые интеграционные тесты с METU SAIS при настроенных учетных данных.

Структура проекта

├── sais/
│   ├── connector.py      # Core SAIS authentication, proxy scraping, and HTML parsers
│   └── connections.py    # Shared in-memory connection store
├── sais_mcp/
│   └── server.py         # MCP stdio server definition and tool registrations
├── api/
│   └── main.py           # FastAPI REST API wrapper
├── tests/
│   ├── test_connector.py # Scraper and HTML parser tests
│   ├── test_mcp_server.py# MCP server tests
│   └── test_api.py       # FastAPI tests
├── .env.example          # Environment variable template
├── opencode.json         # OpenCode MCP configuration
├── pyproject.toml        # Package dependencies and CLI entrypoints
└── README.md             # Project documentation

Лицензия

Лицензия MIT.