# 피움 (pium-mcp)

> 예측이 아니라 방향 — 공식 공시데이터로 피우는 진로·진학 상담 파트너 MCP

진학상담 교사·입시컨설턴트와 학생·학부모를 위한 진로·진학 상담 보조 도구입니다.
사설 배치표/합격예측이 아니라 **커리어넷·대학알리미 공식 데이터**로 객관적인
학과·진로·대학 정보를 정리하고, 상담 문서 초안과 학생별 기록을 돕습니다.

## 데이터 출처 (전부 공식 무료 OpenAPI)

- **커리어넷** — 학과·직업·학교·진로심리검사 (`CAREERNET_API_KEY` 또는 공공데이터포털)
- **대학알리미(대학정보공시)** — 경쟁률·충원율·등록금·장학금·취업률 (공공데이터포털)
- **표준데이터** — 전국 대학별 입학정원·입학결과

## 도구 8개

| 도구 | 설명 | 상태 |
|------|------|------|
| `search_major` | 관심사·계열로 학과 탐색 | API 필드 확정 대기 |
| `get_major` | 학과 상세(교육과정·진출·취업률) | API 필드 확정 대기 |
| `explore_job` | 직업 상세(하는일·임금·전망) | API 필드 확정 대기 |
| `match_aptitude` | 흥미·강점 → 학과/직업 매칭 | 대화형 동작 / 검사연동 대기 |
| `search_university` | 조건별 대학 + 입시지표 | API 필드 확정 대기 |
| `compare` | 대학·학과 비교 + 가성비 | API 필드 확정 대기 |
| `draft_counsel` | 상담 코멘트·안내문 초안 | ✅ 동작 |
| `portfolio` | 학생별 진학 기록(메모리) | ✅ 동작 |

> `draft_counsel`·`portfolio`·`match_aptitude`(대화형)는 외부 API 없이 바로 동작합니다.
> 나머지는 API 키 발급 후 응답 필드만 매핑하면 동작합니다.

## 설치 · 실행

```bash
npm install
cp .env.example .env   # 키 입력
npm run build
npm start              # stdio MCP 서버
```

## 환경변수

`.env` (커밋 금지 — `.gitignore`에 포함):

- `DATA_GO_KR_SERVICE_KEY` — 공공데이터포털 Decoding 인증키
- `CAREERNET_API_KEY` — 커리어넷 자체 OpenAPI 키(진로심리검사용, 선택)
- `PIUM_PORTFOLIO_PATH` — 포트폴리오 저장 경로(기본 `./data/portfolio.json`)

## 🔑 키 발급 직후 확정 체크리스트

- [ ] 커리어넷: 매뉴얼 v4.1로 학과/직업/심리검사 *엔드포인트·요청변수·응답필드* 확정
- [ ] 대학알리미: 경쟁률·등록금·취업률·장학금의 *조사항목코드*·*연도 파라미터* 확정
- [ ] 취업률 단위(학과별/계열별/대학별) 확인
- [ ] 표준데이터(입학정원) 호출 방식(파일 vs API) 확정
- [ ] 각 API 일일 호출 한도 → 캐싱 전략 결정

확정 지점은 코드에서 `TODO(확정)` 주석으로 표시되어 있습니다
(`src/clients/careernet.ts`, `src/clients/academyinfo.ts`).

## 포지셔닝 / 면책

- 합격 **예측·배치**는 의도적으로 제외 (데이터 부재 + 신뢰·법적 리스크 회피)
- 원서 접수·신청 **대행 없음** (공식 API는 읽기 전용 → 안내까지)
- 모든 응답은 참고용이며 최종 판단은 학생·보호자·담당 교사가 합니다

## 로드맵

1. API 키 발급 → 필드 매핑 → 5개 API 도구 활성화
2. 응답 캐싱(일일 한도 대응)
3. 원격 배포(Cloudflare Workers + D1) — `portfolio`를 D1로 전환, PlayMCP 등록