METU SAIS API & 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 and structured data parsing.

Features

• 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 2.x SDK): Exposes typed tools over standard I/O (stdio).

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

• Privacy & Security: Zero credential logging or exposure. Credentials stay local in your git-ignored .env file.

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. Configure Credentials

Copy .env.example to .env and enter your METU credentials:

cp .env.example .env

Edit .env:

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

Using with OpenCode

An opencode.json is already included in this repository.

Project-Level Usage

When starting OpenCode inside this repository:

opencode

OpenCode will automatically connect to the metu-sais MCP server.

Global Usage (Any Directory)

To use METU SAIS tools across any project in OpenCode, add the server to ~/.config/opencode/opencode.jsonc:

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

Verify Connection

opencode mcp list

You should see:

●  ✓ metu-sais connected

Running the MCP Server Standalone

You can run the MCP server directly over standard I/O:

uv run metu-sais-mcp

Running the 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

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.

• FastAPI REST endpoint tests.

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

Project Structure

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

License

MIT License.