korea-university-mcp

korea-university-mcp

대학알리미와 공공데이터포털의 분야별 대학정보 API를 하나의 MCP 서버와 CLI로 통합하는 프로젝트입니다.

현재 버전은 데이터 접근 기반 구축용 MVP입니다. 정원조정, 평가등급, 정책판단 등의 업무 로직은 포함하지 않습니다.

현재 지원 범위

• 대학 기본정보
• 대학 및 전문대학정보
• 대학별 학과정보
• 학생 현황
• 교원·연구 현황
• 교육여건 현황
• 재정 현황
• 산학협력 현황

공공데이터포털 서비스키는 한 번만 설정하며, 각 분야 API의 승인 상태는 공공데이터포털에서 별도로 관리합니다.

설치

npm install
npm run build

환경변수:

DATA_GO_KR_SERVICE_KEY=발급받은키

MCP 서버 실행

npx korea-university-mcp

또는 개발 중:

npm run dev

Remote MCP 실행

기존 STDIO 및 MCPB와 별도로 stateless Streamable HTTP 서버를 실행할 수 있습니다.

npm run build
npm run start:http

Remote MCP 엔드포인트는 http://localhost:3000/mcp이고, 상태 확인 주소는 http://localhost:3000/health입니다. 각 사용자는 자신의 공공데이터포털 서비스키를 요청마다 전달합니다.

커스텀 헤더를 설정할 수 있으면 다음 방식이 권장됩니다.

x-data-go-kr-service-key: 발급받은키

Korean Law 방식과 같은 apikey 헤더도 지원합니다. 커스텀 헤더를 설정할 수 없는 커넥터에서는 다음 URL을 사용할 수 있습니다.

https://example.com/mcp?serviceKey=발급받은키

짧은 별칭인 ?key=도 지원합니다. 쿼리 방식은 브라우저 기록이나 리버스 프록시 접근 로그에 남을 수 있으므로, 배포 환경에서도 URL 쿼리를 마스킹하도록 설정해야 합니다. 이 서버는 요청 URL이나 헤더를 로그에 기록하지 않습니다. Authorization 헤더는 MCP 서버 인증용으로 예약하며 공공데이터포털 서비스키로 사용하지 않습니다.

Remote 요청에 사용자 키가 없으면 STDIO/MCPB용 DATA_GO_KR_SERVICE_KEY로 되돌아가지 않습니다. 이 경우 데이터 검색·설명 도구는 사용할 수 있지만, 실제 API 호출은 키 누락 오류를 반환합니다.

Cloudflare Workers 무료 배포

0.1.3부터 별도 서버 요금 없이 Cloudflare Workers 무료 플랜에 stateless Remote MCP를 배포할 수 있습니다. 기존 STDIO·MCPB·Node HTTP 실행 방식은 그대로 유지됩니다.

npm install
npm run worker:check
npx wrangler login
npm run worker:deploy

배포가 끝나면 Wrangler가 표시하는 workers.dev 주소에 /mcp를 붙여 사용합니다.

https://korea-university-mcp.<계정-subdomain>.workers.dev/mcp

Cloudflare에는 DATA_GO_KR_SERVICE_KEY를 비밀값이나 환경변수로 등록하지 않습니다. 각 사용자가 자신의 키를 매 요청에 전달하며, 서버는 키·요청 URL·요청 헤더를 출력하지 않습니다. 가능하면 URL 쿼리보다 x-data-go-kr-service-key 헤더를 사용하십시오. 플랫폼 자체의 엣지 로그에 쿼리 문자열이 포함될 가능성까지 피하려면 헤더 방식이 필요합니다.

기본 설정은 다음 보호 기능을 적용합니다.

• /mcp 요청을 Cloudflare Rate Limiting으로 위치별 분당 120회까지 허용
• URL 호스트와 Host 헤더 불일치 차단
• 브라우저 Origin은 UNIVERSITY_MCP_ALLOWED_ORIGINS에 명시한 값만 허용
• 응답 캐시 방지 및 Referrer를 통한 URL 유출 방지
• 1MiB를 초과한다고 명시된 요청 본문 차단

서버 간 MCP 클라이언트처럼 Origin 헤더가 없는 요청은 허용됩니다. 브라우저 기반 클라이언트를 연결해야 할 때만 wrangler.jsonc의 UNIVERSITY_MCP_ALLOWED_ORIGINS에 쉼표로 구분한 정확한 Origin을 입력하십시오. Cloudflare Worker에서는 내장 레지스트리만 사용하며, UNIVERSITY_MCP_REGISTRY_FILE 외부 파일 확장은 Node STDIO·MCPB·HTTP에서만 지원합니다.

공식 문서: Cloudflare Remote MCP, Workers 무료 플랜, Rate Limiting 바인딩

GitHub Actions 자동 배포

main 브랜치에 반영된 변경은 타입검사, 테스트, 빌드, 보안 감사와 Worker 번들 검사를 모두 통과한 뒤 Cloudflare에 자동 배포됩니다. 저장소에는 다음 Actions 설정이 필요합니다.

• Secret CLOUDFLARE_API_TOKEN: 최소 권한의 Cloudflare 배포 토큰
• Variable CLOUDFLARE_ACCOUNT_ID: 배포 대상 Cloudflare 계정 ID
• Variable CLOUDFLARE_API_TOKEN_EXPIRES_ON: 배포 토큰 만료일 (YYYY-MM-DD)
• Variable DATA_GO_KR_API_EXPIRES_ON: 운영자가 사용하는 대학정보 API 중 가장 이른 이용기간 만료일 (YYYY-MM-DD, 선택)

배포가 끝나면 워크플로가 공개 /health 주소까지 확인합니다. 자격 증명 만료일은 매주 확인하며, 60일 전부터 실제 비밀값을 포함하지 않는 GitHub 이슈를 생성합니다. 자세한 교체 절차는 자격 증명과 만료 대응을 참고하십시오.

자동 설정

npx korea-university-mcp setup

CLI

korea-university list
korea-university list --query "중도탈락"
korea-university describe student getComparisonDropOutStudentCrntSt
korea-university call student getComparisonDropOutStudentCrntSt --params '{"pageNo":1,"numOfRows":100}'
korea-university doctor
korea-university http

MCP 도구

도구	기능
discover_datasets	분야·지표 검색
describe_operation	데이터셋·오퍼레이션 설명
execute_operation	분야별 API 실행
doctor	키·레지스트리·실호출 진단

오류 처리

오류를 감추지 않습니다. 다음 정보를 구조화하여 반환합니다.

• MCP 오류코드
• 사용자용 설명
• 해결방법
• 재시도 가능 여부
• 공공데이터포털 HTTP 상태·결과코드·결과메시지
• 요청 ID

서비스키와 전체 요청 URL은 노출하지 않습니다.

중요: 실제 요청 파라미터

분야별 API는 오퍼레이션마다 요청변수가 다릅니다. MVP의 execute_operation은 공공데이터포털 Swagger 명세의 요청변수를 그대로 전달합니다. 서비스키를 설정한 뒤 실제 응답을 검증하여 오퍼레이션별 필수 파라미터와 응답 스키마를 단계적으로 레지스트리에 추가해야 합니다.

배포

• 로컬 STDIO: 기본 실행
• 원격 stateless Streamable HTTP: korea-university http 또는 npm run start:http
• 무료 원격 배포: npm run worker:deploy로 Cloudflare Workers 배포
• Docker: Dockerfile
• npm: 태그 푸시 시 GitHub Actions 배포
• Claude Code 플러그인: .claude-plugin 및 .mcp.json

출처

• 공공데이터포털 한국대학교육협의회 대학정보 API
• Model Context Protocol 공식 TypeScript SDK

라이선스

MIT