knu-mcp: Instructions file for Codex

AGENTS.md

강원대학교 춘천캠퍼스 공개 정보 MCP 서버. Python. (Codex/Claude Code 등 코딩 에이전트가 읽는 규칙 파일. CLAUDE.md와 동일 내용을 Codex용으로 둠.)

목표

강원대 춘천캠퍼스 공개 정보를 MCP tool로 노출. Claude Desktop/Cursor/Cline 등 MCP 클라이언트에서 자연어로 조회. 여러 tool을 조합해 "캠퍼스 브리핑" 한방 응답이 차별점.

로그인 필요한 것(수강신청·성적·도서관좌석)은 범위 밖.

스택 / 실행

• Python >=3.10, 패키지 관리 uv, 공식 mcp SDK(FastMCP)
• 의존성: mcp, httpx, beautifulsoup4 + (dev)pytest. 새 의존성 추가 금지.

uv sync                      # 설치
uv run knu-mcp               # 실행 (기본 stdio)
uv run pytest                # 테스트 (네트워크 안 탐, fixture 기반)
KNU_BUS_API_KEY=<키> uv run python scripts/e2e_smoke.py   # E2E (실 네트워크)

원격(HTTP) 실행: KNU_MCP_TRANSPORT=streamable-http PORT=8000 uv run knu-mcp → http://host:8000/mcp

구조

knu_mcp/
  server.py     # FastMCP, tool 7개 등록 (각 tool에 annotations + description에 "강원대학교 도우미")
  http.py       # 공용 get(10분 TTL 캐시)/post
  academic.py   # 학사일정 (re, scheduleData 파싱)
  cafeteria.py  # 학식 (POST + bs4)
  notices.py    # 공지 검색 (bs4, pageIndex 페이징)
  shuttle.py    # 두리버스 시간표/다음차 (bs4)
  bus.py        # 시내버스 실시간 (TAGO 공공API, httpx 직접)
tests/          # 파서 단위 테스트
scripts/e2e_smoke.py

데이터 소스 (중요 — 사이트 특성)

• 5개 tool 중 4개 = 웹 스크래핑(강원대 사이트 개편 시 깨질 수 있음), 버스만 공식 API(TAGO).
• 학사일정: 사이트가 year/month 파라미터를 무시하고 "현재 다가오는 일정"만 줌. 연간 전체 조회 불가(사이트 한계). 1회 요청.
• 공지: GET 키워드 검색·pageUnit 미지원. pageIndex 페이징만 됨 → 최근 N페이지 훑어 필터.
• 버스: 엔드포인트 반드시 https://(http는 일부 환경서 timeout). cityCode=32010, 강원대 정류소 nodeId는 bus.py 상수.

규칙 (Karpathy 4원칙 + 이 프로젝트 규약)

1. Think Before Coding — 가정 명시. 애매하면 질문.
2. Simplicity First — 요청한 것만. 단일 사용 코드에 추상화 금지 (ponytail).
3. Surgical Changes — 건드릴 것만. 기존 스타일 따름. 바뀐 줄은 요청에 직결.
4. Goal-Driven — 검증가능 목표로. 테스트 쓰고 통과까지.

프로젝트 규약:

• 외부 사이트/API 실패 시 예외 대신 {"error": "..."} 반환. 크래시 금지.
• 날짜 YYYY-MM-DD, 시간 HH:MM.
• API 키는 코드/커밋에 절대 하드코딩 금지. 환경변수 KNU_BUS_API_KEY로만.
• 테스트는 네트워크 안 탐 — 저장 fixture 또는 monkeypatch.
• 새 기능은 파서 단위 테스트 먼저(TDD).