ClassCraftMCP

2022 개정 교육과정의 초·중·고 주요 교과 근거를 조회하고, 수업지도안 초안을 검증·렌더링하는 공모전 제출용 Remote MCP 서버입니다. 실제 학습 목표, 활동, 발문과 평가는 MCP 호스트의 LLM이 작성하며, 서버는 공식 근거 조회와 결정론적 검증을 담당합니다.

제출 범위

런타임에는 주요 교과 45개 과목 팩과 성취기준 1,253개만 포함합니다.

학교급	포함 범위	팩	성취기준
초등학교	국어, 수학, 사회, 과학, 영어	5	399
중학교	국어, 수학, 사회, 역사, 과학, 영어	6	333
고등학교	국어·수학·사회·과학·영어 교과군의 공통 과목과 일반 선택 과목	34	521
합계	직업계고·진로 선택·융합 선택·전문 교과 제외	45	1,253

고등학교 수록 과목은 공통국어1·2, 화법과 언어, 독서와 작문, 문학, 공통수학1·2, 기본수학1·2, 대수, 미적분Ⅰ, 확률과 통계, 한국사1·2, 통합사회1·2, 세계시민과 지리, 세계사, 사회와 문화, 통합과학1·2, 과학탐구실험1·2, 물리학, 화학, 생명과학, 지구과학, 공통영어1·2, 기본영어1·2, 영어Ⅰ·Ⅱ, 영어 독해와 작문입니다.

각 성취기준은 공식 원문·해설·내용 요소·수업 유의점과 출처를 보존합니다. 핵심 개념·선수 개념·대표 오개념·핵심 용어는 파생 정보로 구분합니다. 전체 교과 원본은 Git 이력의 8fe0215 커밋에서 복구할 수 있습니다.

공개 MCP 도구

서버는 역할이 겹치지 않는 5개 도구만 공개합니다.

• prepare_lesson_plan_context: 공식·파생 근거, 범위 경계, 활동·평가 후보와 Draft 스키마 제공
• validate_lesson_plan: 호스트가 작성한 Draft의 형식, 시간, 성취기준 참조와 provenance 검증
• render_lesson_plan: 검증된 Draft에 공식 출처를 재결합해 Markdown 생성
• query_curriculum: 학교급·과목 목록, 검색, 단건 조회와 고시 이력 조회
• build_time_flow: 수업 시간 흐름 생성

query_curriculum의 operation은 list_subjects, list, search, get, history를 지원합니다. 모든 응답은 단일 compact JSON text block이며, 오류에는 내부 경로나 스택을 노출하지 않습니다.

로컬 실행

Node.js 22 이상이 필요합니다.

npm install
npm run dev

• MCP endpoint: http://localhost:3000/mcp
• health check: http://localhost:3000/health
• transport: Streamable HTTP
• server mode: 요청별 stateless transport

환경 변수 HOST와 PORT를 지원합니다. 기본값은 각각 0.0.0.0, 3000입니다.

대표 호출

{
  "operation": "search",
  "curriculum": "2022-revised",
  "schoolLevel": "middle",
  "subject": "수학",
  "topic": "소인수분해",
  "limit": 5
}

Inspector로 공개 메타데이터와 호출 결과를 확인할 수 있습니다.

npm run inspector
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http --method tools/list
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http --method tools/call --tool-name query_curriculum --tool-arg operation=get --tool-arg schoolLevel=middle --tool-arg subject=mathematics --tool-arg code=9수02-03

PlayMCP 개발 가이드 검증

다음 명령은 빌드 후 실제 HTTP 서버에 연결하여 제출 계약을 자동 검증합니다.

npm run verify:playmcp

검증 항목은 다음과 같습니다.

• MCP 프로토콜 2025-03-26과 2025-11-25 초기화
• Streamable HTTP 및 stateless 서버 구성
• 도구 5개 이하, 이름 문자 규칙, 대소문자 무관 금칙어 검사
• 영문 설명 안의 ClassCraft(클래스크래프트) 서비스명과 1,024자 제한
• 모든 도구의 inputSchema와 5개 annotations
• compact 응답, 오류 정제, 대표 응답 256KB 미만
• warm 요청 50회의 평균 100ms 이하, p99 3,000ms 미만
• 레지스트리 45팩·성취기준 1,253개 readiness

기준은 PlayMCP 서버 개발가이드와 Agentic Player 10 공식 페이지를 따릅니다. 자동 검사는 저장소에 고정된 제출 계약이며, 등록 직전 공식 가이드의 최신 변경사항을 다시 확인해야 합니다.

테스트와 컨테이너 검증

npm test
npm run build
npm run verify:playmcp
npm run verify:container

verify:container는 linux/amd64 이미지를 빌드하고 비루트 사용자, 45팩·1,253개 문서, 공개 도구 5개, 초·중·고 대표 조회, health check와 SIGTERM 정상 종료를 실제 컨테이너에서 검사합니다.

수동 실행:

docker build --platform linux/amd64 -t classcraft-mcp:latest .
docker run --rm -p 3000:3000 classcraft-mcp:latest

배포 등록값:

• 방식: Git 소스 빌드
• Git URL: https://github.com/yangisu/ClassCraftMCP
• 브랜치/ref: main
• Dockerfile 경로: Dockerfile

데이터 구조와 제출 프로필

data/curriculum/
├─ registry.json
└─ 2022-revised/
   ├─ elementary/<subject>/<version>/
   ├─ middle/<subject>/
   └─ high/<course-id>/<version>/
      ├─ manifest.json
      ├─ sources/source-metadata.json
      ├─ standards/<code>.json
      ├─ guides/<domain>.md
      └─ index/

현재 레지스트리가 제출 범위와 일치하는지 미리 확인하거나 원본 데이터에서 원자적으로 적용할 수 있습니다.

npm run curriculum:submission
npm run curriculum:submission:apply

첫 명령은 dry run이며 파일을 변경하지 않습니다. 적용 명령은 예상 수량을 먼저 검증하고, 임시 디렉터리에서 새 레지스트리를 만든 뒤 교체합니다. 실패하면 기존 데이터를 유지합니다.

공식 자료 갱신기는 교육부·NCIC·한국교육과정평가원 HTTPS 주소만 허용하며, 기본 실행은 변경 여부만 검사합니다.

npm run curriculum:update
npm run curriculum:update -- school elementary
npm run curriculum:update -- school middle subject mathematics
npm run curriculum:update -- school high subject "공통수학1"

검증된 변경 적용은 명령 인수에 apply를 추가합니다. 갱신 후에는 제출 프로필 dry run과 전체 검증을 다시 실행해야 합니다.