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단계 패턴(토큰 절약). 오타 입력엔 유사 후보 제안

빠른 시작

Terminal

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

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

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

설치

Claude Code

Terminal

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

모든 프로젝트에서 쓰려면 사용자 범위로:

Terminal

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

config.json

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

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

Codex CLI

bash

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

또는 ~/.codex/config.toml에 직접 추가:

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 압축), 이후에는 캐시로 즉시 실행됩니다

동작 확인

bash

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 자식 프로세스 없이 같은 검증 데이터를 직접 읽을 수 있습니다.

server.ts

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`와 동일

jsonc

// 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` 모두 허용

jsonc

// 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?	특정 영역만

jsonc

// 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건은 자동 추출 후 전수 검증 게이트(수량·코드 유효성·빈 원문·절취 오류)를 통과한 것만 수록

파일 구성

Code

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) 후:

Terminal

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 — 어떤 파일도 쓰지 않습니다.

개발

bash

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 참조.

라이선스·고지

이 프로젝트는 교육부·국가교육위원회·NCIC의 공식 산출물이 아니며, 개별 학습자를 진단하지 않습니다