korean-elementary-learning-map-mcp

korean-elementary-learning-map-mcp

**这是一个让 AI 查询韩国小学 2022 修订版教育课程学习图谱的 MCP（Model Context Protocol）服务。**只需在 Claude Desktop、Claude Code 等支持 MCP 的 AI 客户端中进行一行配置，AI 就能直接搜索成就标准、学习主题和先修关系并给出回答。

数据	数量
教育课程（学科）	11
成就标准 — 收录官方原文	620
详细学习主题（包含观察证据、评估题目）	1,956
先修关系（学科内 DAG）	1,894
学习集群（包含面向家长的摘要）	153

特点

• 收录成就标准官方原文 — 从 NCIC 公开 PDF 中提取并逐一验证全部 620 条。提供原文全文搜索工具
• 完全本地运行 — 数据内置于软件包中（约 8.6MB），安装后无需联网，采用 stdio 方式
• 确保完整性 — 服务启动时重新验证每个数据文件的 SHA-256。拒绝启动损坏的安装版本
• 面向大模型设计 — 采用两步模式，将搜索（仅摘要）与详情查询分开（节省令牌）。输入错别字时会推荐相似候选项

快速开始

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의 공식 산출물이 아니며, 개별 학습자를 진단하지 않습니다