# korea-university-mcp

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

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

## 현재 지원 범위

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

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

## 설치

```bash
npm install
npm run build
```

환경변수:

```bash
DATA_GO_KR_SERVICE_KEY=발급받은키
```

## MCP 서버 실행

```bash
npx korea-university-mcp
```

또는 개발 중:

```bash
npm run dev
```

## Remote MCP 실행

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

```bash
npm run build
npm run start:http
```

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

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

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

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

```text
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 실행 방식은 그대로 유지됩니다.

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

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

```text
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](https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/), [Workers 무료 플랜](https://developers.cloudflare.com/workers/platform/pricing/), [Rate Limiting 바인딩](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/)

## 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 이슈를 생성합니다. 자세한 교체 절차는 [자격 증명과 만료 대응](docs/CREDENTIALS.md)을 참고하십시오.

## 자동 설정

```bash
npx korea-university-mcp setup
```

## CLI

```bash
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