iGuat-MCP

A read-only MCP (Model Context Protocol) service for iGuihang campus data. Built on Python, FastMCP, and Streamable HTTP, it wraps timetable, class, and campus queries into standard tools callable by AI clients.

This project only provides query capabilities and does not modify the WeChat mini program or upstream academic data.

Features

• Get the full term list, including the current and next term

• Search classes by major, grade, and class keyword

• Get the timetable for a specified class, term, and week

• Query the timetable for a specified person, removing identity fields before returning

• Infer the campus from major information

• Built-in TTL timetable cache, concurrency limits, and health checks

• Protect the MCP and admin APIs with a Bearer API Key

• Support hot-updating the upstream token through the admin API

• Support deployment via Docker, environment variables, and Docker Secrets

Related MCP server: gaokao-helper-worker-mcp

MCP Tools

Tech Stack

• Python 3.11+

• MCP / FastMCP

• HTTPX

• Uvicorn

• Pytest

• Docker

Quick Start

Run Locally

git clone https://github.com/Strayed2SE/iGuat-MCP.git
cd iGuat-MCP

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[test]"

cp .env.example .env
# 按下方说明配置环境变量后启动
python server.py

The service listens on 0.0.0.0:8000 by default:

• MCP: http://127.0.0.1:8000/mcp

• Health check: http://127.0.0.1:8000/healthz

MCP client request headers:

Authorization: Bearer <MCP_PUBLIC_API_KEY>

Docker

docker build -t iguat-mcp .
docker run --rm -p 8000:8000 --env-file .env iguat-mcp

For production, use the NAME_FILE form to load sensitive configuration from Docker Secrets or read-only files:

docker run --rm -p 8000:8000 \
  -e IGUAT_USER_TOKEN_FILE=/run/secrets/iguat_token \
  -e IGUAT_MAIN_SIGN_KEY_FILE=/run/secrets/main_sign_key \
  -e MCP_PUBLIC_API_KEY_FILE=/run/secrets/public_key \
  -e MCP_ADMIN_API_KEY_FILE=/run/secrets/admin_key \
  --mount type=bind,src=/secure/secrets,dst=/run/secrets,ro \
  iguat-mcp

Configuration

Copy .env.example and set as needed:

Update Upstream Token

When the upstream token expires, admins can update the in-memory token without restarting the service:

curl -X PUT http://127.0.0.1:8000/admin/token \
  -H "Authorization: Bearer <MCP_ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"token":"<NEW_TOKEN>"}'

Testing

pip install -e ".[test]"
pytest -q

Security Notes

• Do not commit real tokens, signing keys, API Keys, or .env to the repository.

• The service does not return tokens, signatures, or personally identifiable fields to MCP clients.

• System proxy environment is not read by default; set IGUAT_TRUST_ENV=1 only if your deployment environment actually needs it.

Related Projects

• Guihang Encyclopedia Query System: A campus knowledge base and intelligent Q&A system that integrates this MCP service.