Metadata-Version: 2.4
Name: kids-coding-tutor-mcp
Version: 1.3.0
Summary: 给 5-16 岁孩子、家长和老师的编程学习助手：Scratch 概念白话讲解、1-4 级考级考点与备考、Python 项目实战指导、课程备课。191 条蒸馏知识，纯中文作答。
Author: yiten hua
License: MIT
Project-URL: Homepage, https://github.com/yiten5885-a11y/kids-coding-tutor
Project-URL: Source, https://github.com/yiten5885-a11y/kids-coding-tutor
Keywords: mcp,kids-coding,scratch,python,education
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Natural Language :: Chinese (Simplified)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: mcp<2,>=1.0
Dynamic: license-file

# 少儿编程通 MCP 服务器

把「少儿编程通」skill（191 条记录）变成可远程调用的 MCP 服务器，供 Qoder 这类远端 agent 靠 URL 调用。只读原 skill 的数据文件，不改动原 skill 包。

- 数据来源：`/home/hatch/workspace/skills/kids-coding-tutor/assets/records.jsonl`（可用环境变量 `KIDS_CODING_RECORDS` 换路径）
- 检索/规划/刷题逻辑与原 skill 的 `search.py`、`answer.py`、`plan.py`、`quiz.py`、`videos.py` 一致
- 技术栈：官方 mcp SDK（v1，FastMCP）+ streamable-http transport，Python 3.12，依赖装在项目自带 `.venv`，不动系统全局

## 本地启动

```bash
cd ~/workspace/mcp-servers/kids-coding-tutor
.venv/bin/python server.py --host 127.0.0.1 --port 8000
```

启动后 MCP 端点：`http://127.0.0.1:8000/mcp`

自测（需另开一个终端，先启动服务器再跑）：

```bash
cd ~/workspace/mcp-servers/kids-coding-tutor
.venv/bin/python test_client.py http://127.0.0.1:8000/mcp
```

## Qoder 配置示例（mcp.json，URL 形式）

端口先写占位，部署到服务器后把 `<服务器地址>` 和 `<端口>` 换成实际值：

```json
{
  "mcpServers": {
    "kids-coding-tutor": {
      "url": "http://<服务器地址>:<端口>/mcp",
      "transport": "streamable-http"
    }
  }
}
```

在 Qoder 里添加远程 MCP 服务器时粘贴上面这个 URL 即可（若 Qoder 界面字段名不同，按其提示填 URL 与 streamable-http 类型）。

注意：本服务器的 streamable-http 端点本身不带鉴权，不要直接裸暴露到公网；远端部署时请放在反向代理后加鉴权，或只放在内网/可信网络使用。

## 工具（7 个，全部返回纯中文正文）

| 工具 | 说明 |
| --- | --- |
| `search_knowledge(query, type?, limit?=5)` | 按关键词搜记录，计分规则与原 search.py 一致（标题命中 x3、关键词精确命中 +5）；type 可限定 concept、exam_point、lesson、project、faq、practice、tutorial、parent_guide、video_lesson |
| `get_record(id)` | 按编号取一条全文（含 title/body/example/tip） |
| `list_exam_points(level)` | 列某考级（1-4）全部考级考点（实测：1 级 7 条、2 级 8 条、3 级 7 条、4 级 5 条） |
| `get_practice(level, n?=8)` | 取某级别原创模拟题（各级别 8 道），每题含题目、选项、答案与解析，并注明“原创模拟题，非真题” |
| `study_plan(age, goal?, level?)` | 学习规划，goal 三选一：兴趣 / 考级 / 转python，含路线、课程清单与 4 周节奏 |
| `list_video_courses()` | 列全部视频课（实测 3 门：打砖块 13 节、Boss 战射击游戏 7 节、scratch2.0 零散 4 节） |
| `get_video_lesson(course?, id?)` | 按课程关键词列章节，或按编号取某节配套讲解全文 |

## 实测结果（2026-10-26，MCP SDK 客户端实际调通）

| 调用 | 结果 |
| --- | --- |
| search_knowledge（搜“变量”） | 成功，1016 字，首条【三级考点：变量】 |
| search_knowledge（搜“变量”，type=concept） | 成功，1222 字，首条【Scratch：变量是什么】 |
| get_record（exam-L1-overview） | 成功，231 字 |
| list_exam_points（level=1） | 成功，1459 字，1 级共 7 条 |
| get_practice（level=1） | 成功，1073 字，8 道，含答案、解析与“非真题”注明 |
| study_plan（age=9，goal=考级，level=0） | 成功，503 字，含 4 周节奏与备考指引 |
| list_video_courses | 成功，3 门课 |
| get_video_lesson（course=打砖块） | 成功，13 节章节列表 |
| get_video_lesson（id=vl-brick-11） | 成功，161 字配套讲解全文 |

7 个工具全部调通，无失败项。

## 目录

- `server.py`：服务器本体（FastMCP + streamable-http）
- `test_client.py`：SDK 客户端实测脚本
- `.venv/`：项目自带虚拟环境（mcp 1.30.0，FastMCP）
