수업지도안 메이커 MCP

로컬 Streamable HTTP MCP 서버입니다. 서버는 과목 팩 레지스트리로 관리되는 2022 개정 교육과정 근거, 활동 구성 후보, 고정 Draft 스키마, 결정론적 검증과 Markdown 렌더링을 제공합니다. 현재 중학교 17개 과목 팩과 성취기준 714개가 등록되어 있으며, 같은 구조로 초·고등학교를 확장할 수 있습니다. 실제 학습 목표, 활동, 발문과 평가는 MCP 호스트의 LLM이 작성합니다.

지도안 작성 흐름은 다음과 같습니다.

1. prepare_lesson_plan_context로 공식 근거, 범위 경계, 활동 유형 후보와 LessonPlanDraft 스키마를 조회합니다.

2. 호스트 LLM이 모든 작성 항목을 teacherAuthored로 작성합니다.

3. validate_lesson_plan으로 스키마, 시간, 성취기준 참조와 provenance를 검사합니다.

4. render_lesson_plan이 공식 원문과 출처를 코드로 다시 조회해 고정 Markdown 양식으로 렌더링합니다.

Local Run

npm install
npm run dev

Endpoint:

http://localhost:3000/mcp

Health check:

curl http://localhost:3000/health

Related MCP server: hwp-mcp

PlayMCP in KC Deployment

PlayMCP in KC의 Git 소스 빌드 방식은 이 저장소 루트의 Dockerfile을 사용합니다. 컨테이너는 HOST=0.0.0.0, 기본 PORT=3000에서 실행되며 data/curriculum 준비 상태를 /health로 확인합니다.

로컬 이미지 빌드와 실행:

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

전체 컨테이너 계약을 한 번에 검증하려면 Docker 엔진을 실행한 뒤 다음 명령을 사용합니다.

npm run verify:container

이 명령은 linux/amd64 빌드, 17개 과목 팩·714개 성취기준 readiness, 비루트 사용자, MCP 툴 6개, 범용 과목 조회, SIGTERM 정상 종료를 검사하고 테스트 컨테이너를 정리합니다.

다른 터미널에서 검증:

curl http://localhost:3000/health
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http --method tools/list

PlayMCP in KC 등록값:

• 방식: Git 소스 빌드

• Git URL: https://github.com/yangisu/ClassCraftMCP

• 브랜치/ref: main

• Dockerfile 경로: Dockerfile

배포 환경이 다른 포트를 제공하면 PORT 환경변수를 자동으로 사용합니다. 종료 시 SIGTERM/SIGINT를 받아 진행 중인 HTTP 요청을 정리합니다.

MCP Inspector

npm run inspector

Inspector connection:

Transport: Streamable HTTP
URL: http://localhost:3000/mcp

CLI에서 공개 툴과 대표 호출을 검증할 수 있습니다.

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_middle_math_curriculum --tool-arg operation=get --tool-arg code=9수02-03
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http --method tools/call --tool-name build_time_flow --tool-arg durationMinutes=50 --tool-arg lessonType=cooperative

tools/list 결과에는 아래 6개 툴과 각 툴의 inputSchema, annotations가 표시되어야 합니다.

Lesson Authoring Tools

• prepare_lesson_plan_context: 공식/파생 근거, 범위 경계, 활동·평가 유형 후보, Draft 스키마 제공

• validate_lesson_plan: 호스트 LLM Draft의 형식, 시간, 코드 정렬과 provenance 검증

• render_lesson_plan: 검증 후 공식 출처를 재결합해 Markdown 생성

• build_time_flow: 수업 시간 흐름 생성

Prepare Request

{
  "subject": "수학",
  "gradeLevel": "중학교 1학년",
  "unit": "일차방정식",
  "topic": "방정식과 해의 뜻, 등식의 성질",
  "durationMinutes": 50,
  "lessonType": "cooperative",
  "studentLevel": "mixed",
  "templateProfile": "winter_school_2026",
  "sessionNumber": 1,
  "totalSessions": 1,
  "largeUnit": "변화와 관계",
  "middleUnit": "일차방정식",
  "location": "교실",
  "instructors": ["김교사"],
  "classSize": 24,
  "groupSize": 4,
  "achievementStandardCodes": ["9수02-03"],
  "assessmentMode": "observation_and_exit_ticket",
  "availableTools": ["PPT", "활동지", "포스트잇"],
  "outputProfile": "official_and_appendix"
}

LessonPlanDraft에는 공식 원문, 고시 번호, URL, SHA-256을 넣을 수 없습니다. 이 정보는 render_lesson_plan이 성취기준 코드로 로컬 저장소에서 재조회합니다.

2022 개정 교육과정 과목 팩 레지스트리

범용 query_curriculum은 다음 연산을 지원합니다.

• list_subjects: 학교급에 등록된 과목과 준비 상태 조회

• list: 과목의 영역·주제·성취기준 목록 조회

• search: 과목·영역·단원·주제·코드 검색

• get: 성취기준과 공식 출처 단건 조회

• history: 과목 팩 또는 성취기준의 고시 이력 조회

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

레지스트리와 과목 팩 구조는 다음과 같습니다.

data/curriculum/
├─ registry.json
└─ 2022-revised/middle/<subject>/
   ├─ manifest.json
   ├─ sources/source-metadata.json
   ├─ standards/9수01-01.json ...
   ├─ guides/수와-연산.md ...
   └─ index/

등록 과목은 국어, 도덕, 사회, 역사, 수학, 과학, 기술·가정, 정보, 체육, 음악, 미술, 영어, 생활 외국어, 한문, 환경, 보건, 진로와 직업입니다. 공식 성취기준과 성취기준별 적용 시 고려 사항은 official/verified, 핵심 개념·선수 개념·대표 오개념·핵심 용어는 derived/needsReview로 구분합니다. 공식 내용 요소가 영역 단위 표로만 제시되어 성취기준별 자동 연결을 보류한 경우에는 빈 배열과 unavailableReason을 함께 기록합니다.

중학교 과목별 기준 원문은 교육부 고시 제2022-33호 별책 514, 1618을 사용합니다. 이후 고시 이력도 과목 팩에 기록하며, 현재 최신 고시 검토에서 중학교 과목별 성취기준을 변경하는 후속 고시는 확인되지 않았습니다.

중학교 수학 호환 인터페이스

교육부 고시 제2022-33호 별책 8의 중학교 수학 성취기준 60개를 로컬 JSON과 영역별 Markdown으로 제공합니다.

data/curriculum/2022-revised/middle/mathematics/
├─ manifest.json
├─ sources/source-metadata.json
├─ standards/9수01-01.json ...
├─ guides/수와-연산.md ...
└─ index/standards-index.json

각 공식 문장은 고시 번호, 별책, 공식 URL, HWP 절 경로, 다운로드 날짜, SHA-256을 보존합니다. 교육부 HWP에는 안정적인 공식 페이지 번호가 없으므로 page는 null, sectionPath는 실제 영역·단원·성취기준 경로로 기록합니다. 교사용 선수 개념과 오개념은 derived로 표시하여 공식 원문과 구분합니다.

Curriculum MCP Tools

• query_middle_math_curriculum: operation에 따라 네 영역과 성취기준 목록 조회, 공식/파생 근거 검색, 성취기준 단건 조회

지원하는 operation은 다음과 같습니다.

• list: 전체 교육과정 목록 조회

• search: 코드·영역·단원·주제로 검색

• get: 성취기준 코드로 단건 조회

지도안 목표·평가의 성취기준 정렬 검사는 validate_lesson_plan에 포함됩니다.

검색 예시:

{
  "operation": "search",
  "topic": "자연수를 소인수의 곱으로 나타내기",
  "domain": "수와 연산",
  "limit": 5
}

첫 검색 결과는 [9수01-01] 소인수분해의 뜻을 알고, 자연수를 소인수분해 할 수 있다.입니다. 검색 결과는 officialContext, derivedContext, groundingRules를 분리해 반환합니다.

prepare_lesson_plan_context는 단원과 주제로 교육과정 근거를 검색합니다. 정확한 코드를 알고 있다면 다음처럼 지정할 수 있습니다.

{
  "achievementStandardCodes": ["9수01-01"]
}

일치하는 기준이 없으면 no_match, 서로 다른 세부 단원이 최고점 동점이면 needs_selection을 반환하며 특정 기준을 임의 선택하지 않습니다.

Manual Curriculum Update

공식 자료 변경 여부만 점검:

npm run curriculum:update

검증된 변경을 적용:

npm run curriculum:update -- apply

특정 과목만 점검하거나 적용:

npm run curriculum:update -- subject science
npm run curriculum:update -- apply subject science

갱신기는 교육부·NCIC·한국교육과정평가원 HTTPS 주소만 허용합니다. 교육부 ZIP에서 중학교 관련 별책 HWP를 추출하고, SHA-256과 성취기준 추가·변경·삭제 차이를 보고합니다. apply가 없으면 파일을 변경하지 않으며, 삭제나 스키마 오류가 감지되면 적용을 거부하고 기존 코퍼스를 유지합니다.