korean-elementary-learning-map-mcp

korean-elementary-learning-map-mcp

한국 초등 2022 개정 교육과정 학습 그래프를 AI가 조회할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. Claude Desktop, Claude Code 등 MCP를 지원하는 AI 클라이언트에 한 줄로 설정하면, AI가 성취기준·학습 주제·선수 관계를 직접 검색해 답변합니다.

데이터	수량
교육과정(교과)	11
성취기준 — 공식 원문 수록	620
세부 학습 주제 (관찰 증거·평가 문항 포함)	1,956
선수 관계 (교과 내 DAG)	1,894
학습 클러스터 (학부모용 요약 포함)	153

특징

• 성취기준 공식 원문 수록 — 620개 전부 NCIC 공개 PDF에서 추출하고 전수 검증했습니다. 원문 전문 검색 도구를 제공합니다.
• 완전 로컬 동작 — 데이터가 패키지에 내장되어(약 8.6MB) 설치 후 네트워크가 필요 없으며, stdio 방식으로 동작합니다.
• 무결성 보장 — 서버 기동 시 데이터 파일별 SHA-256을 재검증합니다. 손상된 설치본은 기동을 거부합니다.
• LLM 친화적 설계 — 검색은 요약만, 상세 내용은 조회로 나누는 2단계 패턴으로 토큰을 절약합니다. 오타가 입력되면 유사한 후보를 제안합니다.

빠른 시작

claude mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp

설치 후 AI에게 바로 물어보세요.

"3-4학년 수학에서 분수 관련 성취기준 찾아줘" "[2수01-01] 원문 보여줘" "초등 1-2학년 수학 한 학기 로드맵 정리해줘"

설치

Claude Code

claude mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp

모든 프로젝트에서 사용하려면 사용자 범위로 설정합니다.

claude mcp add -s user curriculum-kr -- npx -y korean-elementary-learning-map-mcp

Claude Desktop

설정 파일에 추가합니다. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "curriculum-kr": {
      "command": "npx",
      "args": ["-y", "korean-elementary-learning-map-mcp"]
    }
  }
}

저장한 후 Claude Desktop을 재시작하면 도구 9종이 로드됩니다.

Codex CLI

codex mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp

또는 ~/.codex/config.toml에 직접 추가합니다.

[mcp_servers.curriculum-kr]
command = "npx"
args = ["-y", "korean-elementary-learning-map-mcp"]

기타 MCP 클라이언트 (Cursor 등)

stdio 방식 MCP 서버를 지원하는 모든 클라이언트에 같은 형식으로 등록할 수 있습니다. 실행 명령은 npx, 인자는 ["-y", "korean-elementary-learning-map-mcp"]입니다.

요구 사항

• Node.js ≥ 20.11 (npx 포함)
• 첫 실행 시 npm에서 패키지를 다운로드합니다(약 320KB 압축). 이후에는 캐시를 사용해 즉시 실행됩니다.

동작 확인

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.0"}}}' | npx -y korean-elementary-learning-map-mcp | head -1

"serverInfo":{"name":"korean-elementary-learning-map","version":"0.5.2"}가 포함된 응답이 나오면 정상입니다.

프로그램 API

서버 애플리케이션이나 빌드 파이프라인에서는 stdio 자식 프로세스 없이 동일한 검증 데이터를 직접 읽을 수 있습니다.

import { createLearningMap } from 'korean-elementary-learning-map-mcp';

const learningMap = createLearningMap();
const standard = learningMap.getStandard('2수01-01');
const topics = learningMap.searchTopics({ standardCode: '2수01-01' });

프로그램 API는 읽기 전용이며, MCP 서버와 마찬가지로 기동 시 데이터 파일의 SHA-256을 검증합니다.

사용법

AI에게 자연어로 물어보면 적절한 도구를 알아서 호출합니다. 대표적인 사용 사례는 다음과 같습니다.

이렇게 물어보면	호출되는 도구
"초등 교과 뭐뭐 있어?"	list_curricula
"3-4학년 수학 분수 성취기준 찾아줘"	search_standards
"원문에 '문제 해결'이 들어간 성취기준은?"	search_standard_text
"[2수01-01] 자세히, 원문도"	get_standard
"이 성취기준으로 뭘 가르치고 평가하지?"	search_topics → get_topic
"이 주제 배우기 전에 뭘 알아야 해?"	get_prerequisites (depth=all이면 전체 경로)
"1-2학년 수학 로드맵 만들어줘"	get_learning_roadmap
"학부모한테 설명할 단원 묶음 보여줘"	list_clusters

도구 레퍼런스 (9종)

list_curricula

11개 교과의 ID·이름·성취기준 수·학년군·영역 목록입니다. 매개변수는 없습니다.

search_standards

성취기준을 검색합니다. 코드가 정확히 일치하는 항목을 우선하고, 이후 키워드 부분 일치 순으로 순위를 매깁니다.

파라미터	타입	설명
query	string?	키워드 또는 코드 (예: 분수, 2수01-01)
subject	string?	교과명 (수학 또는 Mathematics)
gradeBand	string?	학년군: 1-2, 3-4, 5-6
domain	string?	영역명 (예: 수와 연산)
limit	number?	기본값 20, 최대 50

search_standard_text

성취기준 공식 원문 전문 검색. 일치하는 지점 주변의 스니펫을 반환합니다.

파라미터	타입	설명
query	string	원문에서 검색할 키워드 (필수)
subject, gradeBand, limit		search_standards와 동일

// search_standard_text { "query": "수의 필요성" } 응답 예
{ "total": 3, "results": [
  { "code": "[2수01-01]", "subjectKorean": "수학", "gradeBand": "1-2",
    "snippet": "수의 필요성을 인식하면서 0과 100까지의 수 개념을 이해하고, 수를 세고 읽고 쓸…" } ] }

get_standard

성취기준 전체 레코드와 공식 원문(officialText), 연결된 학습 주제 목록을 반환합니다.

파라미터	타입	설명
code	string	성취기준 코드 — [2수01-01], 2수01-01 모두 허용

// get_standard { "code": "2수01-01" } 응답 발췌
{ "code": "[2수01-01]", "gradeBand": "1-2", "domainKorean": "수와 연산",
  "officialText": "수의 필요성을 인식하면서 0과 100까지의 수 개념을 이해하고, 수를 세고 읽고 쓸 수 있다.",
  "linkedTopics": [ { "id": "kr.mt.math.number-operations.g1-2.s2-01-01.application", "...": "..." } ] }

search_topics

세부 학습 주제를 검색합니다.

파라미터	타입	설명
query	string?	키워드
subject, gradeBand, limit		위와 동일
type	string?	주제 유형 (예: CONCEPTUAL, PROCEDURAL)
standardCode	string?	이 성취기준에 연결된 주제만

get_topic

주제 전체 레코드를 반환합니다. 관찰 가능한 증거, 평가 발문(assessmentPrompt), 출처 증거가 포함됩니다.

파라미터	타입	설명
topicId	string	주제 ID (예: kr.mt.math.…)

get_prerequisites

선수/후속 관계 조회. depth: "all"이면 위상 정렬된 전이적 학습 경로를 반환합니다.

파라미터	타입	설명
topicId	string	주제 ID
direction	string?	prerequisites(기본) 또는 unlocks(후속)
depth	1 | "all"	1 = 직접 관계만(기본), all = 전체 경로
strength	string?	hard 또는 soft 관계만 필터

get_learning_roadmap

교과·학년군의 성취기준을 영역 → 모듈 계층으로 집계한 로드맵. 기존 데이터의 집계이며 순서를 새로 생성하지 않습니다.

파라미터	타입	설명
subject	string	교과명 (필수)
gradeBand	string	학년군 (필수)
domain	string?	특정 영역만

// get_learning_roadmap { "subject": "수학", "gradeBand": "1-2" } 응답 발췌
{ "subjectKorean": "수학", "gradeBand": "1-2", "standardCount": 29,
  "domains": [ { "domainKorean": "수와 연산", "domainOrder": 1,
    "clusters": [ { "id": "kr.cluster….", "titleKorean": "…" } ],
    "modules": [ { "module": "네 자리 이하의 수",
      "standards": [ { "code": "[2수01-01]", "topicCount": 3 } ] } ] } ] }

list_clusters

학습 클러스터(학부모용 요약이 있는 단원 묶음) 목록·상세.

파라미터	타입	설명
clusterId	string?	지정 시 단건 전체 레코드
subject, gradeBand	string?	목록 필터

리소스

about://korean-elementary-learning-map — 데이터 릴리스·수량·라이선스·원문 수록 정책·비보증 고지. AI가 데이터의 출처와 법적 성격을 확인할 때 읽습니다.

에러 응답

존재하지 않는 코드·ID를 주면 한국어 메시지와 함께 유사 후보 최대 3개를 제안합니다 (예: 2수01-1 → [2수01-01]). AI가 오타를 스스로 교정해 재시도할 수 있습니다. 검색 결과가 0건이면 사용 가능한 교과명·학년군 형식을 힌트로 돌려줍니다.

데이터

출처와 구축 방식

• 성취기준 코드·구조·원문: 국가교육과정정보센터(NCIC)가 공개한 2022 개정 교육과정 고시 PDF 12종에서 추출. 각 PDF의 URL·SHA-256은 pipeline/sources.json에 기록
• 학습 주제·선수관계·클러스터: DECK이 독립 구축한 korean-elementary-learning-map 데이터셋(MIT) 기반
• 원문 620건은 자동 추출 후 전수 검증 게이트(수량·코드 유효성·빈 원문·절취 오류)를 통과한 것만 수록

파일 구성

data/kr/
├── curriculum-standards.json  # 교과 11 + 성취기준 620 (코드·위치·출처 증거)
├── standard-texts.json        # 성취기준 공식 원문 620 (v0.5 신규)
├── topics.json                # 세부 학습 주제 1,956
├── dependencies.json          # 선수관계 1,894 (교과 내 DAG, 교과 간 간선 없음)
├── clusters.json              # 학습 클러스터 153
└── manifest.json              # 파일별 바이트 수·SHA-256 (서버 기동 시 재검증)

알아둘 데이터 특성

• 선수관계는 이 데이터셋 모델의 추천 구조이며 보편적 학습 순서 주장이 아닙니다
• 성취기준 620개 중 373개는 sequence 필드가 없습니다 — 로드맵은 공식 문서 수록 순서를 보존합니다
• 검색은 NFC 정규화 + 부분 문자열 일치입니다 (형태소 분석 없음 — 짧은 핵심어가 잘 맞습니다)

원문 파이프라인 재현 (개발자용)

data/kr/standard-texts.json은 커밋되어 있으므로 일반 사용에는 재현이 필요 없습니다. 직접 재현·검증하려면 brew install poppler(pdftotext) 후:

npm run pipeline:fetch     # NCIC PDF 12종 다운로드 → .cache/ (git 미추적, 해시 대조)
npm run pipeline:extract   # 코드 패턴 매칭으로 원문 절취 (실패분은 pipeline/exceptions.json으로 보정)
npm run pipeline:verify    # 620건 전수 검증 + manifest 해시 기록

원본 개정 감지

매월 1일 GitHub Actions(revision-check)가 NCIC 원본 PDF 12종을 새로 내려받아 기록된 SHA-256과 대조하고, 변경이 감지되면 revision-alert 라벨의 이슈를 자동 생성합니다. 수동 점검: node pipeline/fetch-ncic.mjs --check — 어떤 파일도 쓰지 않습니다.

개발

git clone https://github.com/taehyeonglim/korean-elementary-learning-map-mcp.git
cd korean-elementary-learning-map-mcp
npm install
npm test          # 49개 테스트 (node --test)
node src/cli.mjs  # stdio 서버 직접 실행

• 순수 ESM(.mjs), 런타임 의존성은 @modelcontextprotocol/sdk + zod 2종뿐
• src/: data-store(로드·인덱스) → search/graph/roadmap(순수 함수) → server(도구 정의) → cli(stdio 진입점)
• CI: push마다 테스트 → 원문 전수 게이트 → 패키지 내용물 검사

버전

버전	내용
0.5.2	프로그램 API·TypeScript 선언 추가 · 패키지와 MCP 서버 버전 단일화
0.5.1	MCP 공식 레지스트리 메타데이터와 npm 문서 보강
0.5.0	독립 레포 이전 · 성취기준 원문 620건 수록 · search_standard_text/get_learning_roadmap 추가 (도구 9종)
0.4.0	최초 npm 공개 (도구 7종, 원 데이터셋 레포의 서브패키지)

상세 이력은 CHANGELOG.md 참조.

라이선스·고지

• MIT — 기반 데이터셋 원저작자 DECK(github.com/DECK6)의 저작권 고지를 유지합니다
• 성취기준 원문은 교육부가 공표한 공공저작물(저작권법 제24조의2)로서 출처를 표기해 수록합니다 — 상세는 NOTICE.md
• 이 프로젝트는 교육부·국가교육위원회·NCIC의 공식 산출물이 아니며, 개별 학습자를 진단하지 않습니다