METU SAIS API & Multi-Tenant MCP Server

A modern Model Context Protocol (MCP) server and FastAPI service for Middle East Technical University (METU / ODTÜ) Student Affairs Information System (SAIS / student.metu.edu.tr).

Connects your AI assistants (such as OpenCode, Claude Desktop, and Cursor) directly to METU SAIS with real authentication, structured data parsing, and stateless multi-tenant remote streaming.

Features

• Multi-Tenant Architecture: Supports both local single-user runs and remote multi-tenant serving over Server-Sent Events (SSE) / HTTP. Remote users pass their own credentials via headers or query parameters without storing any passwords on the server.

• SSO Authentication: Handles the real METU SSO login flow (/sso/backend/request/user/signin) and session token validation.

• Proxy Scraper & HTML Parser: Automatically establishes authenticated proxy sessions (/proxy/Student_Information/) and parses student records into structured JSON.

• MCP Server (MCP SDK): Exposes typed tools over standard I/O (stdio), Server-Sent Events (sse), or Streamable HTTP.

• FastAPI REST Service: Alternative HTTP REST backend for API integrations.

• Privacy & Security: Zero credential logging or exposure.

Related MCP server: SABIS MCP Server

Available MCP Tools

Installation & Setup

1. Prerequisites

• Python >= 3.11

• uv (recommended) or pip

2. Install Dependencies

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

3. Local Configuration (Optional for Single-User Runs)

For local single-user runs, copy .env.example to .env:

cp .env.example .env

Edit .env:

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

Running Multi-Tenant Remote MCP (Online)

Start the Server with SSE Transport

# Direct MCP SSE server:
uv run metu-sais-mcp --transport sse --host 0.0.0.0 --port 8300

# Or via FastAPI (serves both REST API and MCP SSE at /sse and /messages/):
uv run uvicorn api.main:app --host 0.0.0.0 --port 8300

Connecting Remote Clients (Claude Desktop / Cursor / OpenCode)

Option 1: Custom Headers (Recommended)

{
  "mcpServers": {
    "metu-sais": {
      "url": "https://mcp.yourdomain.com/sse",
      "headers": {
        "X-SAIS-Username": "e123456",
        "X-SAIS-Password": "student_secret_password"
      }
    }
  }
}

Option 2: Basic Authentication Header

{
  "mcpServers": {
    "metu-sais": {
      "url": "https://mcp.yourdomain.com/sse",
      "headers": {
        "Authorization": "Basic <base64(username:password)>"
      }
    }
  }
}

Option 3: URL Query Parameters

{
  "mcpServers": {
    "metu-sais": {
      "url": "https://mcp.yourdomain.com/sse?u=e123456&p=student_secret_password"
    }
  }
}

Local Usage with OpenCode & Claude Desktop

Project-Level Usage with OpenCode

When starting OpenCode inside this repository:

opencode

OpenCode will automatically connect to the metu-sais MCP server defined in opencode.json.

Local Stdio Standalone Run

uv run metu-sais-mcp

REST API

To start the FastAPI server:

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

Interactive API documentation will be available at:

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

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

REST Endpoints

• GET /api/sais/info — Student information

• GET /api/sais/schedule — Class schedule

• GET /api/sais/transcript — Transcript history

• GET /api/sais/announcements — Portal announcements

• GET|POST|PUT|DELETE /api/connections — Connection management CRUD

(In multi-tenant mode, pass X-SAIS-Username and X-SAIS-Password headers or ?u=...&p=... query parameters to any REST endpoint).

Testing

Run the automated test suite with pytest:

uv run pytest -v

The test suite includes:

• Unit tests for HTML parsers (parse_student_info, parse_schedule, parse_transcript, parse_announcements).

• MCP tool registration and tool calling tests.

• Multi-tenant credential extraction and session isolation tests.

• FastAPI REST endpoint tests.

• Live integration tests against METU SAIS when credentials are configured.

Project Structure

├── sais/
│   ├── auth.py           # Multi-tenant credential resolver and session store
│   ├── connector.py      # Core SAIS authentication, proxy scraping, and HTML parsers
│   └── connections.py    # Shared in-memory connection store
├── sais_mcp/
│   └── server.py         # MCP multi-tenant server (stdio, sse, streamable-http)
├── api/
│   └── main.py           # FastAPI REST API + mounted MCP SSE app
├── tests/
│   ├── test_connector.py # Scraper and HTML parser tests
│   ├── test_mcp_server.py# MCP server and multi-tenant SSE isolation 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

License

MIT License.