피움 (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는 읽기 전용 → 안내까지)
• 모든 응답은 참고용이며 최종 판단은 학생·보호자·담당 교사가 합니다

로드맵

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