METU SAIS API & MCP Server

Ein moderner Model Context Protocol (MCP)-Server und FastAPI-Dienst für das Student Affairs Information System (SAIS / student.metu.edu.tr) der Middle East Technical University (METU / ODTÜ).

Verbindet Ihre KI-Assistenten (wie OpenCode, Claude Desktop und Cursor) direkt mit METU SAIS, mit echter Authentifizierung und strukturiertem Daten-Parsing.

Features

• SSO-Authentifizierung: Übernimmt den echten METU-SSO-Anmeldeablauf (/sso/backend/request/user/signin) und die Validierung von Sitzungstokens.

• Proxy-Scraper & HTML-Parser: Richtet automatisch authentifizierte Proxy-Sitzungen ein (/proxy/Student_Information/) und parst Studentendatensätze in strukturiertes JSON.

• MCP-Server (MCP 2.x SDK): Stellt typisierte Tools über Standard-I/O (stdio) bereit.

• FastAPI-REST-Dienst: Alternatives HTTP-REST-Backend für Integrationen.

• Datenschutz & Sicherheit: Keinerlei Protokollierung oder Offenlegung von Anmeldedaten. Anmeldedaten bleiben lokal in Ihrer git-ignorierten .env-Datei.

Related MCP server: SABIS MCP Server

Verfügbare MCP-Tools

Installation & Einrichtung

1. Voraussetzungen

• Python >= 3.11

• uv (empfohlen) oder pip

2. Abhängigkeiten installieren

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

3. Anmeldedaten konfigurieren

Kopieren Sie .env.example nach .env und geben Sie Ihre METU-Anmeldedaten ein:

cp .env.example .env

Bearbeiten Sie .env:

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

[!NOTE] .env ist in .gitignore aufgeführt und wird niemals eingecheckt.

Verwendung mit OpenCode

Eine opencode.json ist bereits in diesem Repository enthalten.

Verwendung auf Projektebene

Wenn Sie OpenCode in diesem Repository starten:

opencode

OpenCode verbindet sich automatisch mit dem metu-sais-MCP-Server.

Globale Verwendung (beliebiges Verzeichnis)

Um die METU-SAIS-Tools projektübergreifend in OpenCode zu verwenden, fügen Sie den Server zu ~/.config/opencode/opencode.jsonc hinzu:

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

Verbindung prüfen

opencode mcp list

Sie sollten Folgendes sehen:

●  ✓ metu-sais connected

Ausführen des MCP-Servers im Standalone-Modus

Sie können den MCP-Server direkt über Standard-I/O ausführen:

uv run metu-sais-mcp

Ausführen der REST-API

Um den FastAPI-Server zu starten:

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

Die interaktive API-Dokumentation ist verfügbar unter:

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

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

REST-Endpunkte

• GET /api/sais/info — Studenteninformationen

• GET /api/sais/schedule — Stundenplan

• GET /api/sais/transcript — Transcript-Verlauf

• GET /api/sais/announcements — Portal-Ankündigungen

• GET|POST|PUT|DELETE /api/connections — Verbindungsverwaltung (CRUD)

Testen

Führen Sie die automatisierte Testsuite mit pytest aus:

uv run pytest -v

Die Testsuite umfasst:

• Unit-Tests für HTML-Parser (parse_student_info, parse_schedule, parse_transcript, parse_announcements).

• Tests zur MCP-Tool-Registrierung und zum Tool-Aufruf.

• Tests für FastAPI-REST-Endpunkte.

• Live-Integrationstests gegen METU SAIS, wenn Anmeldedaten konfiguriert sind.

Projektstruktur

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

Lizenz

MIT-Lizenz.