内容
# 韩国小学学习地图-mcp
[](https://www.npmjs.com/package/korean-elementary-learning-map-mcp)
[](https://github.com/taehyeonglim/korean-elementary-learning-map-mcp/actions/workflows/ci.yml)
[](LICENSE)
**这是韩国小学2022修订教育课程学习图的MCP（Model Context Protocol）服务器**。通过在Claude Desktop、Claude Code等支持MCP的AI客户端中设置一行代码，即可让AI直接搜索和回答学生的学习目标、学习主题和先决条件。
| 数据 | 数量 |
| --- | ---: |
| 教育课程（科目） | 11 |
| 学习目标 — **官方原文收录** | 620 |
| 详细学习主题（包括观察证据和评估题目） | 1,956 |
| 先决条件（科目内的有向图） | 1,894 |
| 学习集群（为家长提供的摘要） | 153 |
## 特点
- **学习目标官方原文收录** — 全部620个学习目标均从NCIC公开的PDF中提取和验证。提供原文全文搜索工具
- **完全本地运行** — 数据内置于软件包中（约8.6MB），安装后无需网络，支持stdio方式
- **保证完整性** — 每个数据文件在服务器启动时都会重新验证SHA-256。如果安装包损坏，服务器将拒绝启动
- **LLM友好设计** — 搜索分为摘要和详细查询两步（节省令牌）。对于输入错误，提供相似候选项
## 快速入门
```bash
claude mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp
```
安装后可以直接向AI提问：
> "请给我小学三年级和四年级的数学学习目标"
> "请给我[2수01-01]的原文"
> "请给我小学一二年级的数学学习路线图"
## 安装
### Claude Code
```bash
claude mcp add curriculum-kr -- npx -y korean-elementary-learning-map-mcp
```
如果要在所有项目中使用，可以在用户范围内进行：
```bash
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`
```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.0"}`，则表示正常。
## 用法
向AI提出自然语言问题，它将调用适当的工具。代表性场景：
| 提问方式 | 调用的工具 |
| --- | --- |
| "小学有哪些科目？" | `list_curricula` |
| "请给我三年级和四年级的数学学习目标" | `search_standards` |
| "请给我包含‘问题解决’的原文的学习目标" | `search_standard_text` |
| "请给我[2수01-01]的详细内容和原文" | `get_standard` |
| "根据这个学习目标，学生应该学习和评估什么？" | `search_topics` → `get_topic` |
| "学习这个主题之前需要什么？" | `get_prerequisites`（depth=all时返回整个路径） |
| "请给我一二年级的数学学习路线图" | `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`](pipeline/sources.json)中。
- 学习主题、先决条件和集群：由[DECK](https://github.com/DECK6)独立构建的[korean-elementary-learning-map](https://github.com/taehyeonglim/korean-elementary-learning-map)数据集（MIT）基础上。
- 620个原文通过自动提取后**全部验证**，通过验证门槛（数量、代码有效性、空原文、剪切错误）。
### 文件构成
```
data/kr/
├── curriculum-standards.json # 11个科目 + 620个学习目标（代码、位置、来源证据）
├── standard-texts.json # 620个学习目标官方原文（v0.5新）
├── topics.json # 1956个详细学习主题
├── dependencies.json # 1894个先决条件（科目内的有向图，科目间无边）
├── clusters.json # 153个学习集群
└── manifest.json # 每个文件的字节数和SHA-256（服务器启动时重新验证）
```
### 数据特性
- 先决条件是该数据集模型的**推荐结构**，而非普遍的学习顺序主张。
- 620个学习目标中，373个没有`sequence`字段 — 路线图保留官方文档的顺序。
- 搜索是NFC规范化 + 子字符串匹配（无分词 — 短关键词匹配良好）。
## 原文管道重现（开发者）
`data/kr/standard-texts.json`已提交，因此通常不需要重现。如果要重新验证，请先安装`brew install poppler`（pdftotext），然后：
```bash
npm run pipeline:fetch # 下载NCIC的12个PDF → .cache/（git不跟踪，哈希对照）
npm run pipeline:extract # 通过代码模式匹配提取原文（失败部分在pipeline/exceptions.json中纠正）
npm run pipeline:verify # 全部验证 + 清单哈希记录
```
## 原始修订检测
每月1日，GitHub Actions（[revision-check](.github/workflows/revision-check.yml)）会下载NCIC原始PDF（12个）并与记录的SHA-256进行比较。如果检测到更改，则会自动创建带有`revision-alert`标签的issue。手动检查：`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/`：数据存储（加载、索引）→ 搜索/图/路线图（纯函数）→ 服务器（工具定义）→ cli（stdio入口）。
- CI：每次推送测试 → 原文全验证 → 包内容检查。
## 版本
| 版本 | 内容 |
| --- | --- |
| **0.5.0** | 独立存储库迁移 · 包含620个学习目标原文 · 新增`search_standard_text`/`get_learning_roadmap`（9种工具） |
| 0.4.0 | 首次npm发布（7种工具，[原始数据集存储库](https://github.com/taehyeonglim/korean-elementary-learning-map)的子包） |
详细历史记录见[CHANGELOG.md](CHANGELOG.md)。
## 许可证和声明
- **MIT** — 保留基于数据集的原始作者DECK（github.com/DECK6）的版权声明。
- 学习目标原文是教育部发布的**公共领域作品**（版权法第24条第2款），在注明来源的情况下收录 — 详情见[NOTICE.md](NOTICE.md)。
- 本项目不是教育部、国家教育委员会或NCIC的官方产品，不会诊断个别学习者。
