METU SAIS API & MCP Server

一个面向中东技术大学（METU / ODTÜ）学生事务信息系统（SAIS / student.mete.edu.tr）的现代 Model Context Protocol (MCP) 服务器和 FastAPI 服务。

通过真实身份验证和结构化数据解析，将你的 AI 助手（如 OpenCode、Claude Desktop 和 Cursor）直接连接到 METU SAIS。

功能特性

• SSO 身份验证：处理真实的 METU SSO 登录流程（/ssO/backend/request/user/signin）和会话令牌验证。

• 代理抓取器与 HTML 解析器：自动建立经过身份验证的代理会话（/pxoxy/Student_Information/），并将学生记录解析为结构化 JSON。

• MCP 服务器（MCP 2.x SDK）：通过标准 I/O（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 服务器

你可以直接通过标准 I/O 运行 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。