{
  "markdown": "# korean-elementary-learning-map-mcp\n\n[![npm](https://img.shields.io/npm/v/korean-elementary-learning-map-mcp)](https://www.npmjs.com/package/korean-elementary-learning-map-mcp)\n[![CI](https://github.com/taehyeonglim/korean-elementary-learning-map-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/taehyeonglim/korean-elementary-learning-map-mcp/actions/workflows/ci.yml)\n[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\n**한국 초등 2022 개정 교육과정 학습 그래프를 AI가 조회하게 해주는 MCP(Model Context Protocol) 서버**입니다.\nClaude Desktop, Claude Code 등 MCP를 지원하는 AI 클라이언트에 설정 한 줄로 연결하면, AI가\n성취기준·학습 주제·선수관계를 직접 검색해서 답합니다.\n\n| 데이터 | 수량 |\n| --- | ---: |\n| 교육과정(교과) | 11 |\n| 성취기준 — **공식 원문 수록** | 620 |\n| 세부 학습 주제 (관찰 증거·평가 문항 포함) | 1,956 |\n| 선수관계 (교과 내 DAG) | 1,894 |\n| 학습 클러스터 (학부모용 요약 포함) | 153 |\n\n## 특징\n\n- **성취기준 공식 원문 수록** — 620개 전부 NCIC 공개 PDF에서 추출·전수 검증. 원문 전문 검색 도구 제공\n- **완전 로컬 동작** — 데이터가 패키지에 내장(약 8.6MB)되어 설치 후 네트워크 불필요, stdio 방식\n- **무결성 보장** — 데이터 파일별 SHA-256을 서버 기동 시 재검증. 손상된 설치본은 기동 거부\n- **LLM 친화 설계** — 검색은 요약만, 상세는 조회로 나눈 2단계 패턴(토큰 절약). 오타 입력엔 유사 후보 제안\n\n## 빠른 시작\n\n```bash\nclaude mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp\n```\n\n설치 후 AI에게 바로 물어보세요:\n\n> \"3-4학년 수학에서 분수 관련 성취기준 찾아줘\"\n> \"[2수01-01] 원문 보여줘\"\n> \"초등 1-2학년 수학 한 학기 로드맵 정리해줘\"\n\n## 설치\n\n### Claude Code\n\n```bash\nclaude mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp\n```\n\n모든 프로젝트에서 쓰려면 사용자 범위로:\n\n```bash\nclaude mcp add -s user curriculum-kr -- npx -y korean-elementary-learning-map-mcp\n```\n\n### Claude Desktop\n\n설정 파일에 추가합니다.\nmacOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"curriculum-kr\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"korean-elementary-learning-map-mcp\"]\n    }\n  }\n}\n```\n\n저장 후 Claude Desktop을 재시작하면 도구 9종이 로드됩니다.\n\n### Codex CLI\n\n```bash\ncodex mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp\n```\n\n또는 `~/.codex/config.toml`에 직접 추가:\n\n```toml\n[mcp_servers.curriculum-kr]\ncommand = \"npx\"\nargs = [\"-y\", \"korean-elementary-learning-map-mcp\"]\n```\n\n### 기타 MCP 클라이언트 (Cursor 등)\n\nstdio 방식 MCP 서버를 지원하는 모든 클라이언트에서 동일한 형태로 등록됩니다:\n실행 명령 `npx`, 인자 `[\"-y\", \"korean-elementary-learning-map-mcp\"]`.\n\n### 요구 사항\n\n- Node.js ≥ 20.11 (`npx` 포함)\n- 첫 실행 시 npm에서 패키지를 내려받으며(약 320KB 압축), 이후에는 캐시로 즉시 실행됩니다\n\n### 동작 확인\n\n```bash\nprintf '%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\n```\n\n`\"serverInfo\":{\"name\":\"korean-elementary-learning-map\",\"version\":\"0.5.2\"}`가 포함된 응답이 나오면 정상입니다.\n\n### 프로그램 API\n\n서버 애플리케이션이나 빌드 파이프라인에서는 stdio 자식 프로세스 없이 같은 검증 데이터를 직접 읽을 수 있습니다.\n\n```js\nimport { createLearningMap } from 'korean-elementary-learning-map-mcp';\n\nconst learningMap = createLearningMap();\nconst standard = learningMap.getStandard('2수01-01');\nconst topics = learningMap.searchTopics({ standardCode: '2수01-01' });\n```\n\n프로그램 API는 읽기 전용이며 MCP 서버와 동일하게 기동 시 데이터 파일의 SHA-256을 검증합니다.\n\n## 사용법\n\nAI에게 자연어로 물어보면 알아서 적절한 도구를 호출합니다. 대표 시나리오:\n\n| 이렇게 물어보면 | 호출되는 도구 |\n| --- | --- |\n| \"초등 교과 뭐뭐 있어?\" | `list_curricula` |\n| \"3-4학년 수학 분수 성취기준 찾아줘\" | `search_standards` |\n| \"원문에 '문제 해결'이 들어간 성취기준은?\" | `search_standard_text` |\n| \"[2수01-01] 자세히, 원문도\" | `get_standard` |\n| \"이 성취기준으로 뭘 가르치고 평가하지?\" | `search_topics` → `get_topic` |\n| \"이 주제 배우기 전에 뭘 알아야 해?\" | `get_prerequisites` (depth=all이면 전체 경로) |\n| \"1-2학년 수학 로드맵 만들어줘\" | `get_learning_roadmap` |\n| \"학부모한테 설명할 단원 묶음 보여줘\" | `list_clusters` |\n\n### 도구 레퍼런스 (9종)\n\n#### `list_curricula`\n11개 교과의 ID·이름·성취기준 수·학년군·영역 목록. 파라미터 없음.\n\n#### `search_standards`\n성취기준 검색 — 코드 정확 일치 우선, 이후 키워드 부분 일치 랭킹.\n\n| 파라미터 | 타입 | 설명 |\n| --- | --- | --- |\n| `query` | string? | 키워드 또는 코드 (예: `분수`, `2수01-01`) |\n| `subject` | string? | 교과명 (`수학` 또는 `Mathematics`) |\n| `gradeBand` | string? | 학년군: `1-2`, `3-4`, `5-6` |\n| `domain` | string? | 영역명 (예: `수와 연산`) |\n| `limit` | number? | 기본 20, 최대 50 |\n\n#### `search_standard_text`\n**성취기준 공식 원문 전문 검색.** 매칭 지점 주변 스니펫을 반환합니다.\n\n| 파라미터 | 타입 | 설명 |\n| --- | --- | --- |\n| `query` | string | 원문에서 찾을 키워드 (필수) |\n| `subject`, `gradeBand`, `limit` | | `search_standards`와 동일 |\n\n```jsonc\n// search_standard_text { \"query\": \"수의 필요성\" } 응답 예\n{ \"total\": 3, \"results\": [\n  { \"code\": \"[2수01-01]\", \"subjectKorean\": \"수학\", \"gradeBand\": \"1-2\",\n    \"snippet\": \"수의 필요성을 인식하면서 0과 100까지의 수 개념을 이해하고, 수를 세고 읽고 쓸…\" } ] }\n```\n\n#### `get_standard`\n성취기준 전체 레코드 + **공식 원문(`officialText`)** + 연결된 학습 주제 목록.\n\n| 파라미터 | 타입 | 설명 |\n| --- | --- | --- |\n| `code` | string | 성취기준 코드 — `[2수01-01]`, `2수01-01` 모두 허용 |\n\n```jsonc\n// get_standard { \"code\": \"2수01-01\" } 응답 발췌\n{ \"code\": \"[2수01-01]\", \"gradeBand\": \"1-2\", \"domainKorean\": \"수와 연산\",\n  \"officialText\": \"수의 필요성을 인식하면서 0과 100까지의 수 개념을 이해하고, 수를 세고 읽고 쓸 수 있다.\",\n  \"linkedTopics\": [ { \"id\": \"kr.mt.math.number-operations.g1-2.s2-01-01.application\", \"...\": \"...\" } ] }\n```\n\n#### `search_topics`\n세부 학습 주제 검색.\n\n| 파라미터 | 타입 | 설명 |\n| --- | --- | --- |\n| `query` | string? | 키워드 |\n| `subject`, `gradeBand`, `limit` | | 위와 동일 |\n| `type` | string? | 주제 유형 (예: `CONCEPTUAL`, `PROCEDURAL`) |\n| `standardCode` | string? | 이 성취기준에 연결된 주제만 |\n\n#### `get_topic`\n주제 전체 레코드 — 관찰 가능한 증거, 평가 발문(`assessmentPrompt`), 출처 증거 포함.\n\n| 파라미터 | 타입 | 설명 |\n| --- | --- | --- |\n| `topicId` | string | 주제 ID (예: `kr.mt.math.…`) |\n\n#### `get_prerequisites`\n선수/후속 관계 조회. `depth: \"all\"`이면 위상 정렬된 전이적 학습 경로를 반환합니다.\n\n| 파라미터 | 타입 | 설명 |\n| --- | --- | --- |\n| `topicId` | string | 주제 ID |\n| `direction` | string? | `prerequisites`(기본) 또는 `unlocks`(후속) |\n| `depth` | 1 \\| \"all\" | 1 = 직접 관계만(기본), `all` = 전체 경로 |\n| `strength` | string? | `hard` 또는 `soft` 관계만 필터 |\n\n#### `get_learning_roadmap`\n교과·학년군의 성취기준을 **영역 → 모듈 계층**으로 집계한 로드맵. 기존 데이터의 집계이며 순서를 새로 생성하지 않습니다.\n\n| 파라미터 | 타입 | 설명 |\n| --- | --- | --- |\n| `subject` | string | 교과명 (필수) |\n| `gradeBand` | string | 학년군 (필수) |\n| `domain` | string? | 특정 영역만 |\n\n```jsonc\n// get_learning_roadmap { \"subject\": \"수학\", \"gradeBand\": \"1-2\" } 응답 발췌\n{ \"subjectKorean\": \"수학\", \"gradeBand\": \"1-2\", \"standardCount\": 29,\n  \"domains\": [ { \"domainKorean\": \"수와 연산\", \"domainOrder\": 1,\n    \"clusters\": [ { \"id\": \"kr.cluster….\", \"titleKorean\": \"…\" } ],\n    \"modules\": [ { \"module\": \"네 자리 이하의 수\",\n      \"standards\": [ { \"code\": \"[2수01-01]\", \"topicCount\": 3 } ] } ] } ] }\n```\n\n#### `list_clusters`\n학습 클러스터(학부모용 요약이 있는 단원 묶음) 목록·상세.\n\n| 파라미터 | 타입 | 설명 |\n| --- | --- | --- |\n| `clusterId` | string? | 지정 시 단건 전체 레코드 |\n| `subject`, `gradeBand` | string? | 목록 필터 |\n\n### 리소스\n\n`about://korean-elementary-learning-map` — 데이터 릴리스·수량·라이선스·원문 수록 정책·비보증 고지.\nAI가 데이터의 출처와 법적 성격을 확인할 때 읽습니다.\n\n### 에러 응답\n\n존재하지 않는 코드·ID를 주면 한국어 메시지와 함께 **유사 후보 최대 3개**를 제안합니다\n(예: `2수01-1` → `[2수01-01]`). AI가 오타를 스스로 교정해 재시도할 수 있습니다.\n검색 결과가 0건이면 사용 가능한 교과명·학년군 형식을 힌트로 돌려줍니다.\n\n## 데이터\n\n### 출처와 구축 방식\n\n- 성취기준 코드·구조·원문: 국가교육과정정보센터(NCIC)가 공개한 2022 개정 교육과정 고시 PDF 12종에서 추출.\n  각 PDF의 URL·SHA-256은 [`pipeline/sources.json`](pipeline/sources.json)에 기록\n- 학습 주제·선수관계·클러스터: [DECK](https://github.com/DECK6)이 독립 구축한\n  [korean-elementary-learning-map](https://github.com/taehyeonglim/korean-elementary-learning-map) 데이터셋(MIT) 기반\n- 원문 620건은 자동 추출 후 **전수 검증 게이트**(수량·코드 유효성·빈 원문·절취 오류)를 통과한 것만 수록\n\n### 파일 구성\n\n```\ndata/kr/\n├── curriculum-standards.json  # 교과 11 + 성취기준 620 (코드·위치·출처 증거)\n├── standard-texts.json        # 성취기준 공식 원문 620 (v0.5 신규)\n├── topics.json                # 세부 학습 주제 1,956\n├── dependencies.json          # 선수관계 1,894 (교과 내 DAG, 교과 간 간선 없음)\n├── clusters.json              # 학습 클러스터 153\n└── manifest.json              # 파일별 바이트 수·SHA-256 (서버 기동 시 재검증)\n```\n\n### 알아둘 데이터 특성\n\n- 선수관계는 이 데이터셋 모델의 **추천 구조**이며 보편적 학습 순서 주장이 아닙니다\n- 성취기준 620개 중 373개는 `sequence` 필드가 없습니다 — 로드맵은 공식 문서 수록 순서를 보존합니다\n- 검색은 NFC 정규화 + 부분 문자열 일치입니다 (형태소 분석 없음 — 짧은 핵심어가 잘 맞습니다)\n\n## 원문 파이프라인 재현 (개발자용)\n\n`data/kr/standard-texts.json`은 커밋되어 있으므로 일반 사용에는 재현이 필요 없습니다.\n직접 재현·검증하려면 `brew install poppler`(pdftotext) 후:\n\n```bash\nnpm run pipeline:fetch     # NCIC PDF 12종 다운로드 → .cache/ (git 미추적, 해시 대조)\nnpm run pipeline:extract   # 코드 패턴 매칭으로 원문 절취 (실패분은 pipeline/exceptions.json으로 보정)\nnpm run pipeline:verify    # 620건 전수 검증 + manifest 해시 기록\n```\n\n## 원본 개정 감지\n\n매월 1일 GitHub Actions([revision-check](.github/workflows/revision-check.yml))가 NCIC 원본\nPDF 12종을 새로 내려받아 기록된 SHA-256과 대조하고, 변경이 감지되면 `revision-alert` 라벨의\n이슈를 자동 생성합니다. 수동 점검: `node pipeline/fetch-ncic.mjs --check` — 어떤 파일도 쓰지 않습니다.\n\n## 개발\n\n```bash\ngit clone https://github.com/taehyeonglim/korean-elementary-learning-map-mcp.git\ncd korean-elementary-learning-map-mcp\nnpm install\nnpm test          # 49개 테스트 (node --test)\nnode src/cli.mjs  # stdio 서버 직접 실행\n```\n\n- 순수 ESM(.mjs), 런타임 의존성은 `@modelcontextprotocol/sdk` + `zod` 2종뿐\n- `src/`: data-store(로드·인덱스) → search/graph/roadmap(순수 함수) → server(도구 정의) → cli(stdio 진입점)\n- CI: push마다 테스트 → 원문 전수 게이트 → 패키지 내용물 검사\n\n## 버전\n\n| 버전 | 내용 |\n| --- | --- |\n| **0.5.2** | 프로그램 API·TypeScript 선언 추가 · 패키지와 MCP 서버 버전 단일화 |\n| **0.5.1** | MCP 공식 레지스트리 메타데이터와 npm 문서 보강 |\n| **0.5.0** | 독립 레포 이전 · 성취기준 원문 620건 수록 · `search_standard_text`/`get_learning_roadmap` 추가 (도구 9종) |\n| 0.4.0 | 최초 npm 공개 (도구 7종, [원 데이터셋 레포](https://github.com/taehyeonglim/korean-elementary-learning-map)의 서브패키지) |\n\n상세 이력은 [CHANGELOG.md](CHANGELOG.md) 참조.\n\n## 라이선스·고지\n\n- **MIT** — 기반 데이터셋 원저작자 DECK(github.com/DECK6)의 저작권 고지를 유지합니다\n- 성취기준 원문은 교육부가 공표한 **공공저작물**(저작권법 제24조의2)로서 출처를 표기해 수록합니다 — 상세는 [NOTICE.md](NOTICE.md)\n- 이 프로젝트는 교육부·국가교육위원회·NCIC의 공식 산출물이 아니며, 개별 학습자를 진단하지 않습니다\n",
  "bytes": 9418,
  "sha": "c01541c2b87798e649cfda14fd766da09fafa0c02fe03f7fd3d3dca262bd2108",
  "repo_slug": "taehyeonglim/korean-elementary-learning-map-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_taehyeonglim_korean_elementary_6e78e297/readme"
}