iGuat-MCP

i桂航 キャンパスデータ向けの読み取り専用 MCP（Model Context Protocol）サービスです。このプロジェクトは Python、FastMCP、Streamable HTTP をベースに、時間割・クラス・キャンパスの照会を AI クライアントから呼び出せる標準ツールとして提供します。

このプロジェクトは照会機能のみを提供し、WeChat ミニプログラムや上流の教务データを変更することはありません。

機能

• 学期リスト全体、現在の学期、次の学期を取得

• 専攻・学年・クラスのキーワードによるクラス検索

• 指定したクラス・学期・週次の時間割を照会

• 指定した人物の時間割を照会し、返却前に身分フィールドを除去

• 専攻情報に基づいて所属キャンパスを推定

• 内蔵 TTL 時間割キャッシュ、同時実行制限、ヘルスチェック

• Bearer API Key による MCP および管理インターフェースの保護

• 管理インターフェースによる上流トークンのホットアップデートに対応

• Docker、環境変数、Docker Secrets によるデプロイに対応

Related MCP server: gaokao-helper-worker-mcp

MCP ツール

技術スタック

• Python 3.11+

• MCP / FastMCP

• HTTPX

• Uvicorn

• Pytest

• Docker

クイックスタート

ローカル実行

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

サービスはデフォルトで 0.0.0.0:8000 をリッスンします：

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

• ヘルスチェック：http://127.0.0.1:8000/healthz

MCP クライアントのリクエストヘッダー：

Authorization: Bearer <MCP_PUBLIC_API_KEY>

Docker

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

本番環境では、NAME_FILE 形式を使用して Docker Secrets または読み取り専用ファイルから機密設定を読み込むことを推奨します：

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

設定

.env.example をコピーし、必要に応じて設定します：

上流トークンの更新

上流トークンが無効になった場合、管理者はサービスを再起動せずにメモリ内のトークンを更新できます：

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>"}'

テスト

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

セキュリティに関する注意

• 実際のトークン、署名キー、API Key、.env をリポジトリにコミットしないでください。

• サービスはトークン、署名、個人の身分フィールドを MCP クライアントに返しません。

• デフォルトではシステムプロキシ環境変数を読み取りません。デプロイ環境で本当に必要な場合のみ IGUAT_TRUST_ENV=1 を設定してください。

関連プロジェクト

• 桂航百科查询系统：本 MCP サービスを統合したキャンパス知識ベースおよびインテリジェント Q&A システム。