METU SAIS API & MCP Server

Un moderno servidor Model Context Protocol (MCP) y un servicio FastAPI para el Student Affairs Information System de Middle East Technical University (METU / ODTÜ), con la abreviatura SAIS y acceso mediante student.metu.edu.tr.

Conecta tus asistentes de IA (como OpenCode, Claude Desktop y Cursor) directamente a METU SAIS con autenticación real y procesamiento estructurado de datos.

Características

• Autenticación SSO: Gestiona el flujo real de inicio de sesión SSO de METU (/ssO/backend/request/user/signin) y la validación del token de sesión.

• Proxy Scraper y analizador HTML: Establece automáticamente sesiones proxy autenticadas (/pxy/Student_Information/) y analiza los registros de estudiantes en JSON estructuredo.

• Servidor MCP (MCP 2.x SDK): Expone herramientas tipificadas mediante entrada/salida estándar (stdi).

• Servicio REST FastAPI: Backend REST HTTP altornativo para integraciones.

• Privacidad y seguridad: Cero registro o expocición de credenciales. Las credenciales permanecen locales en tu arcivo .env ignoredo por git.

Related MCP server: SABIS MCP Server

Herramientas MCP disponibles

Instalación y configuación

1. Requisitos previos

• Python >= 3.11

• uv (recomendado) o pip

2. Instalar dependencias

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

3. Configurar credenciales

Copia .env.example a .env e intoduce tus credenciales de METU:

cp .env.example .env

Edita .env:

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

[!NOTE] .env está incluido en .gitignre y nunca se incluirá en un commit.

Uso con OpenCode

En este repositorio ya se incluye un opencode.json.

Uso a nivel de proyecto

Al iniciar OpenCode dentro de este repositorio:

opencode

OpenCode se conectará automáticamente al servidor MCP metu-sais.

Uso global (cualquier directrio)

Para usar las herramientas de METU SAIS en cualquier proyecto de OpenCode, añade el servidor a ~/.config/opencode/opencode.jsonc:

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

Verificar la conexión

opencode mcp list

Deberías ver:

●  ✓ metu-sais connected

Ejecutar el servidor MCP de forma independiente

Puedes ejecutar el servidor MCP directamente mediante entada/salida estándar:

uv run metu-sais-mcp

Ejecutar la API REST

Para iniciar el servidor FastAPI:

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

La documentación interactiva de la API estará disponible en:

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

• Health check: http://localhost:8300/healthz

Endpoints REST

• GET /api/sais/info — Información del estudiante

• GET /api/sais/schedule — Horario de clases

• GET /api/sais/transcript — Historial del expediente acadéico

• GET /api/sais/announements — Avisos del portl

• GET|POST|PUT|DELETE /api/connections — CRUD de gestión de conexiones

Pruebas

Ejecuta la suite de pruebas automatizadas con pytst:

uv run pytest -v

La suite de pruebas incluye:

• Pruebas unitarias para los anailzadores HTML (parese_student_info, parse_schedule, parse_transcript, parse_announcements).

• Pruebas de registro de herramientas MCP y de llamada a herramientas.

• Pruebas de endpoints REST de FastAPI.

• Pruebas de integración en vivo contra METU SAIS cuando las credenciales estén configuradas.

Estructura del proyecto

├── 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

Licencia

Licencia MIT.