METU SAIS API & MCP Server

Middle East Technical University (METU / ODTÜ) Student Affairs Information System (SAIS / student.metu.edu.tr) 向けの、モダンな Model Context Protocol (MCP) サーバーおよび FastAPI サービスです。

実際の認証と構造化データ解析により、AI アシスタント（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）で型付きツールを公開します。

• FastAPI REST サービス: 統合のための代替 HTTP REST バックエンド。

• プライバシーとセキュリティ: 認証情報のログ記録や漏えいは一切ありません。認証情報は git 管理外の .env ファイル内にローカルのみ保持されます。

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 は自動的に metu-sais MCP サーバーに接続します。

グローバル使用（任意のディレクトリ）

OpenCode のすべてのプロジェクトで METU SAIS ツールを使用するには、サーバーを ~/.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 ツール登録とツール呼び出しのテスト。

• FastAPI REST エンドポイントのテスト。

• 認証情報が設定されている場合、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 License.