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 시스템.