korean-secondary-learning-map-mcp

# korean-secondary-learning-map-mcp

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

## 데이터 규모

| 항목 | 수량 |
| --- | ---: |
| 과목(교육과정) | 179 (중학교 24 · 고교 보통교과 155) |
| 성취기준 | 2,887 (중학교 714 · 고교 2,173) |
| 성취기준 원문 | 2,887 (자동 추출 2,875 + 수식 수동 보정 12) |
| 세부 학습 주제 | 4,333 |
| 선수관계 (교과 내) | 213 (중학교 56 · 고교 157) |
| 학습 클러스터 | 632 |
| 중→고 전이 | 175 |
| 과목관계 (고교 과목 간 선후) | 37 |

빌드 시 드롭된 항목:

- 고교 선수관계는 DECK6 원본 508건 중 351건이 특성화고·특목고 과목 제외로 드롭되어 157건만 포함되었습니다(중학교 56건과 합쳐 213건).
- 중→고 전이는 원본 대비 드롭 0건(175건 전부 포함).
- 과목관계는 원본 39건 중 포함 범위 밖 과목을 참조하는 2건이 드롭되어 37건이 포함되었습니다.

## 범위와 한계

- **특성화고 전문교과(47,625건)와 특목고 계열(예술·과학·체육고, 951건)은 포함하지 않습니다.** 이 서버는 중학교 전체와 고등학교 **보통교과**(공통·일반선택·진로선택·융합선택)만 다룹니다. 단, 「연극」과목(13건)은 DECK6 분류상 예술 계열이지만 실제로는 별책4(보통교과)에 수록된 과목이라 예외적으로 포함했습니다.
- 11개 코드(12스문·12심독 계열)는 서로 다른 두 과목이 공유합니다 — `get_standard`에서 `subject` 파라미터로 구분해야 합니다.
- 선수관계·전이·과목관계는 공식 문서(별책3·별책4, DECK6 근거)가 직접 뒷받침하는 관계만 수록했습니다. 초등판 대비 선수관계 수가 상대적으로 적은 것은 데이터가 부실해서가 아니라, 근거 없는 추정 관계를 배제했기 때문입니다.
- 선수관계·전이·과목관계는 모델의 추천 구조이며 보편적 학습 순서 주장이 아닙니다.

## 도구 11종

검색·목록형 도구 6종(`list_curricula`, `search_standards`, `search_topics`, `search_standard_text`, `get_learning_roadmap`, `list_clusters`)은 `schoolLevel`(`middle` | `high`) 필터를 지원합니다. 나머지 5종(`get_standard`, `get_topic`, `get_prerequisites`, `get_transitions`, `get_course_pathway`)은 ID·코드 단건 조회라 필터가 없습니다.

| 도구 | 설명 |
| --- | --- |
| `list_curricula` | 필터 없으면 학교급·교과군 요약, `schoolLevel`/`subjectGroup` 지정 시 과목 목록 |
| `search_standards` | 성취기준을 코드·키워드·필터로 검색 (요약 목록) |
| `search_standard_text` | 성취기준 공식 원문 전문에서 키워드 검색 (매칭 스니펫) |
| `get_standard` | 성취기준 코드로 전체 레코드 + 공식 원문 + 연결 주제 조회. 코드 공유 과목은 `subject`로 구분 |
| `search_topics` | 세부 학습 주제 검색 (요약 목록) |
| `get_topic` | 주제 ID로 관찰 증거·평가 문항·출처를 포함한 전체 레코드 조회 |
| `get_prerequisites` | 주제의 선수/후속 관계 조회. `depth: "all"`이면 위상 정렬된 전이적 학습 경로 반환 |
| `get_learning_roadmap` | 과목의 성취기준을 영역→클러스터 계층으로 집계한 로드맵 |
| `list_clusters` | 학습 클러스터 목록·상세 조회 |
| `get_transitions` | 주제 ID 또는 성취기준 코드로 중→고 전이(심화 연계)를 양방향 조회 |
| `get_course_pathway` | 과목명으로 고교 과목 간 권장 선후 흐름(예: 영어Ⅰ→영어Ⅱ) 조회 |

## 설치

### Claude Code

```bash
claude mcp add curriculum-kr-secondary -- npx -y korean-secondary-learning-map-mcp
```

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

```bash
claude mcp add -s user curriculum-kr-secondary -- npx -y korean-secondary-learning-map-mcp
```

### Claude Desktop

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

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

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

### 요구 사항

- Node.js ≥ 20.11 (`npx` 포함)

## 로컬 개발

```bash
git clone https://github.com/raphysicst-create/korean-secondary-learning-map-mcp.git
cd korean-secondary-learning-map-mcp
npm install
npm test          # node --test tests/*.test.mjs
```

`data/kr/`의 데이터는 커밋되어 있으므로 일반 사용에는 파이프라인 재현이 필요 없습니다. 데이터를 재구축하려면 다음 순서로 실행합니다.

```bash
npm run pipeline:fetch     # DECK6 원본 + NCIC PDF 4권 확보·해시 검증 (.cache/, git 미추적)
npm run pipeline:build     # DECK6 원본에서 범위 필터링해 data/kr/*.json 생성
npm run pipeline:extract   # PDF에서 성취기준 원문 추출 (실패분은 pipeline/exceptions.json으로 수동 보정)
npm run pipeline:verify    # 전수 검증(수량 게이트·참조 무결성) + manifest.json 해시 기록
```

PDF 4권(별책3, 별책4 Ⅰ·Ⅱ·Ⅲ)은 저장소 밖에 있어야 하며, `PDF_DIR` 환경 변수(기본값: 저장소 부모 폴더)에서 찾습니다.

## 법적 고지

- **MIT** — 기반 데이터셋(학습 주제·선수관계·클러스터·전이·과목관계) 원저작자 [DECK6](https://github.com/DECK6)의 저작권 고지를 유지합니다 (고정 커밋 `68e6228`).
- 성취기준 원문은 교육부가 공표한 **공공저작물**(저작권법 제24조의2)로서 출처(NCIC 공개 별책3·별책4 PDF)를 표기해 수록합니다 — 상세는 [NOTICE.md](NOTICE.md)
- 이 프로젝트는 교육부·국가교육위원회·NCIC의 공식 산출물이 아니며, 개별 학습자를 진단하지 않습니다.