korean-elementary-learning-map-mcp

# Tool List [](https://www.npmjs.com/package/korean-elementary-learning-map-mcp) [](https://github.com/taehyeonglim/korean-elementary-learning-map-mcp/actions/workflows/ci.yml) [](LICENSE) **An MCP (Model Context Protocol) server that allows AI to query the 2022 revised Korean elementary school curriculum learning graph.** ## Features - **Official text of achievement standards** — 620 achievement standards extracted and verified from NCIC's official PDF documents. - **Complete local operation** — Data is embedded in the package (approximately 8.6MB) and does not require a network connection after installation. - **Integrity guarantee** — SHA-256 verification of data files during server startup. Damaged installations are rejected. - **LLM-friendly design** — Search is divided into two stages: summary and detailed query (token saving). Suggests similar candidates for typo inputs. ## Quick Start ```bash claude mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp ``` Ask your AI: > "What are the achievement standards for fractions in 3-4 grade math?" > "Show me the original text of [2수01-01]" > "Summarize the learning roadmap for 1-2 grade math for one semester" ## Installation ### Claude Code ```bash claude mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp ``` For all projects: ```bash claude mcp add -s user curriculum-kr -- npx -y korean-elementary-learning-map-mcp ``` ### Claude Desktop Add to the configuration file. macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "curriculum-kr": { "command": "npx", "args": ["-y", "korean-elementary-learning-map-mcp"] } } } ``` Restart Claude Desktop to load 9 tools. ### Codex CLI ```bash codex mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp ``` Or add directly to `~/.codex/config.toml`: ```toml [mcp_servers.curriculum-kr] command = "npx" args = ["-y", "korean-elementary-learning-map-mcp"] ``` ### Other MCP Clients (Cursor, etc.) All clients supporting stdio-style MCP servers can be registered in the same way: Execution command `npx`, arguments `["-y", "korean-elementary-learning-map-mcp"]`. ### Requirements - Node.js ≥ 20.11 (including `npx`) - The package is downloaded from npm during the first execution (approximately 320KB compressed) and then runs immediately from the cache. ### Verification ```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 ``` A response containing `"serverInfo":{"name":"korean-elementary-learning-map","version":"0.5.0"}` indicates normal operation. ## Usage Ask your AI in natural language, and it will call the appropriate tool. Representative scenarios: | Question | Called Tool | | --- | --- | | "What are the elementary school subjects?" | `list_curricula` | | "Find the achievement standards for fractions in 3-4 grade math" | `search_standards` | | "Find achievement standards with 'problem solving' in the original text" | `search_standard_text` | | "Detail [2수01-01], including the original text" | `get_standard` | | "What do I teach and assess with this achievement standard?" | `search_topics` → `get_topic` | | "What should I know before learning this topic?" | `get_prerequisites` (depth=all for the entire path) | | "Create a learning roadmap for 1-2 grade math" | `get_learning_roadmap` | | "Show me the unit clusters for parents" | `list_clusters` | ### Tool Reference (9 types) #### `list_curricula` List of 11 subjects: IDs, names, number of achievement standards, grade bands, and domains. #### `search_standards` Search achievement standards — prioritizes exact code matches, then keyword partial matches. | Parameter | Type | Description | | --- | --- | --- | | `query` | string? | Keyword or code (e.g., `fraction`, `2수01-01`) | | `subject` | string? | Subject name (`Mathematics`) | | `gradeBand` | string? | Grade band: `1-2`, `3-4`, `5-6` | | `domain` | string? | Domain name (e.g., `Numbers and Operations`) | | `limit` | number? | Default 20, maximum 50 | #### `search_standard_text` **Full-text search of official achievement standard text.** Returns snippets around matched points. | Parameter | Type | Description | | --- | --- | --- | | `query` | string | Keyword to find in the original text (required) | | `subject`, `gradeBand`, `limit` | | Same as `search_standards` | ```jsonc // search_standard_text { "query": "necessity of numbers" } response example { "total": 3, "results": [ { "code": "[2수01-01]", "subjectKorean": "Mathematics", "gradeBand": "1-2", "snippet": "Recognize the necessity of numbers and understand the concept of numbers up to 100..." } ] } ``` #### `get_standard` Achievement standard record + **official text (`officialText`)** + linked learning topics. | Parameter | Type | Description | | --- | --- | --- | | `code` | string | Achievement standard code — `[2수01-01]`, `2수01-01` both allowed | ```jsonc // get_standard { "code": "2수01-01" } response excerpt { "code": "[2수01-01]", "gradeBand": "1-2", "domainKorean": "Numbers and Operations", "officialText": "Recognize the necessity of numbers and understand the concept of numbers up to 100...", "linkedTopics": [ { "id": "kr.mt.math.number-operations.g1-2.s2-01-01.application", "...": "..." } ] } ``` #### `search_topics` Search detailed learning topics. | Parameter | Type | Description | | --- | --- | --- | | `query` | string? | Keyword | | `subject`, `gradeBand`, `limit` | | Same as above | | `type` | string? | Topic type (e.g., `CONCEPTUAL`, `PROCEDURAL`) | | `standardCode` | string? | Topics linked to this achievement standard | #### `get_topic` Detailed topic record — observable evidence, assessment prompts, and source evidence. | Parameter | Type | Description | | --- | --- | --- | | `topicId` | string | Topic ID (e.g., `kr.mt.math.…`) | #### `get_prerequisites` Prerequisite/successor relationships. If `depth: "all"`, returns a topologically sorted transitive learning path. | Parameter | Type | Description | | --- | --- | --- | | `topicId` | string | Topic ID | | `direction` | string? | `prerequisites`(default) or `unlocks`(successors) | | `depth` | 1 \| "all" | 1 = direct relationships only (default), `all` = entire path | | `strength` | string? | Filter by `hard` or `soft` relationships | #### `get_learning_roadmap` Learning roadmap aggregated by subject and grade band — **domain → module hierarchy**. | Parameter | Type | Description | | --- | --- | --- | | `subject` | string | Subject name (required) | | `gradeBand` | string | Grade band (required) | | `domain` | string? | Specific domain only | ```jsonc // get_learning_roadmap { "subject": "Mathematics", "gradeBand": "1-2" } response excerpt { "subjectKorean": "Mathematics", "gradeBand": "1-2", "standardCount": 29, "domains": [ { "domainKorean": "Numbers and Operations", "domainOrder": 1, "clusters": [ { "id": "kr.cluster….", "titleKorean": "…" } ], "modules": [ { "module": "Numbers up to four digits", "standards": [ { "code": "[2수01-01]", "topicCount": 3 } ] } ] } ] } ``` #### `list_clusters` List of learning clusters (unit bundles with parent summaries) and details. | Parameter | Type | Description | | --- | --- | --- | | `clusterId` | string? | Returns a single detailed record if specified | | `subject`, `gradeBand` | string? | Filters the list | ### Resources `about://korean-elementary-learning-map` — Data release, quantity, license, original text inclusion policy, and non-guarantee notice. Read by AI to confirm data source and legal status. ### Error Response If a non-existent code or ID is provided, a Korean message with **up to 3 similar candidates** is suggested (e.g., `2수01-1` → `[2수01-01]`). AI can correct typos and retry. ## Data ### Source and Construction - Achievement standard codes, structure, and original text: Extracted from 12 revised curriculum announcement PDFs (2022) by the National Center for Education Information (NCIC). URLs and SHA-256 for each PDF are recorded in [`pipeline/sources.json`](pipeline/sources.json). - Learning topics, prerequisite relationships, and clusters: Based on the [korean-elementary-learning-map](https://github.com/taehyeonglim/korean-elementary-learning-map) dataset (MIT) independently constructed by [DECK](https://github.com/DECK6). - 620 original texts are automatically extracted and **verified through a thorough gate** (quantity, code validity, empty text, and truncation errors). ### File Composition ``` data/kr/ ├── curriculum-standards.json # 11 subjects + 620 achievement standards (code, location, source evidence) ├── standard-texts.json # Official texts of 620 achievement standards (new in v0.5) ├── topics.json # 1,956 detailed learning topics ├── dependencies.json # 1,894 prerequisite relationships (intra-subject DAG, no inter-subject edges) ├── clusters.json # 153 learning clusters └── manifest.json # Byte count and SHA-256 for each file (verified during server startup) ``` ### Data Characteristics - Prerequisite relationships are **recommended structures** of this dataset and do not imply a universal learning order. - 373 out of 620 achievement standards do not have a `sequence` field — roadmaps preserve the order specified in official documents. - Search uses NFC normalization and substring matching (no morphological analysis — short keywords work well). ## Reproducing the Original Text Pipeline (for developers) `data/kr/standard-texts.json` is committed, so reproduction is not necessary for general use. To reproduce and verify: ```bash brew install poppler npm run pipeline:fetch # Download 12 NCIC PDFs → .cache/ (not tracked by git, hash verified) npm run pipeline:extract # Extract original text using code patterns (failures are corrected in pipeline/exceptions.json) npm run pipeline:verify # Verify 620 records + record manifest hashes ``` ## Detecting Original Revisions Monthly on the 1st, GitHub Actions ([revision-check](.github/workflows/revision-check.yml)) downloads the 12 NCIC PDFs, compares their hashes, and creates an issue labeled `revision-alert` if changes are detected. Manual check: `node pipeline/fetch-ncic.mjs --check` — does not write any files. ## Development ```bash git clone https://github.com/taehyeonglim/korean-elementary-learning-map-mcp.git cd korean-elementary-learning-map-mcp npm install npm test # 49 tests (node --test) node src/cli.mjs # Run the stdio server directly ``` - Pure ESM (.mjs), runtime dependencies are `@modelcontextprotocol/sdk` and `zod`. - `src/`: data-store (loading and indexing) → search/graph/roadmap (pure functions) → server (tool definitions) → cli (stdio entry point). - CI: tests on every push → original text gate → package content inspection. ## Version | Version | Content | | --- | --- | | **0.5.0** | Moved to independent repo, included 620 achievement standard texts, added `search_standard_text` and `get_learning_roadmap` (9 tools) | | 0.4.0 | Initial npm release (7 tools, subpackage of [original dataset repo](https://github.com/taehyeonglim/korean-elementary-learning-map)) | See [CHANGELOG.md](CHANGELOG.md) for detailed history. ## License and Notice - **MIT** — Maintains the copyright notice of the base dataset's original author, DECK (github.com/DECK6). - Achievement standard texts are **publicly licensed works** (Copyright Act Article 24-2) and are included with source attribution — see [NOTICE.md](NOTICE.md) for details. - This project is not an official product of the Ministry of Education, the National Education Commission, or NCIC and does not diagnose individual learners.