피움 (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 키 발급 후 응답 필드만 매핑하면 동작합니다.
설치 · 실행
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는 읽기 전용 → 안내까지)
- 모든 응답은 참고용이며 최종 판단은 학생·보호자·담당 교사가 합니다
로드맵
- API 키 발급 → 필드 매핑 → 5개 API 도구 활성화
- 응답 캐싱(일일 한도 대응)
- 원격 배포(Cloudflare Workers + D1) —
portfolio를 D1로 전환, PlayMCP 등록
