edumints SCORM MCP

edumints SCORM MCP

一个用于编译交互式、符合标准的电子学习课程的 MCP 服务。 你（或 Claude 这样的 AI 客户端）是作者；此服务是编译器。 将课程描述为结构化规范——服务会对其进行验证、渲染，并打包为可在任何 LMS（Moodle、SCORM Cloud、Rustici Engine 等）中运行的 独立 SCORM 压缩包。 结果确定——服务不会运行大模型。

🌐 语言： English · Türkçe · Español · Русский · 简体中文 · Azərbaycanca · Қазақша · Кыргызча

线上演示

四门完整课程——面向四类受众，采用四种视觉风格——完全由此服务构建，并通过线上部署提供服务。点击任意截图即可启动。

做个密码英雄！	识别钓鱼邮件	人身攻击谬误	Grafik Dedektifi
9–13 岁 · 互联网安全 · style-playful + 自定义品牌	企业入职培训 · 电子邮件安全 · style-minimal + 企业品牌	研究生水平 · 论证理论 · style-premium	土耳其语 · 数据素养 · 探究式（5E）· 基于证据的评估

每个演示都包含叙事线索、逼真的素材模型 SVG、标记搜寻模拟、前后对比、时间线、案例游戏和自适应反馈，并提供底层的 SCORM 问题级报告。

项目缘起

电子学习通常是在笨重的桌面创作工具中手工制作的。本项目则将课程制作视为 AI Agent 的基础设施：

• 无需安装即可创作。 将任意 MCP 客户端连接到托管端点，即可开始构建——无需工具链，也无需本地配置。客户端通过 Model Context Protocol 描述课程（目标、屏幕、测验、分支、媒体）；服务负责繁重工作：验证、主题设置、无障碍 HTML 渲染、SCORM 运行时桥接和打包。
• 敢于说不的质量关卡。 AI 可以快速生成大量平庸内容。此服务会进行把关：对每份规范进行架构验证，通过 反低质内容检查（lint_course）把错误等级的问题拦截在构建之外，并提供 CI 验证链（XSD + 真实 SCORM Cloud 导入 + 行为探测），确保发布的内容确实能在 LMS 中运行——参见标准与证据。
• 不受供应商锁定。 输出为普通的 SCORM 1.2/2004 压缩包，附带独立播放器。采用 MIT 许可证，可自托管，并欢迎贡献。

作者 = MCP 客户端 · 编译器 = 此服务。

快速入门

选项 1 — 托管 MCP（零安装）

将任意 MCP 客户端（Claude desktop/web/Code、Antigravity、……）指向：

https://scorm.edumints.com/mcp

通过 OAuth 登录，或在门户网站 https://mcp.edumints.com 获取 API 密钥。 然后提出请求：“构建一门关于 X 的 6 分钟互动课程，包含测验和总结。” — 你会获得一个 可下载的 SCORM zip 文件。

最好搭配创作技能使用（这是一项 Claude Agent Skill，可教会 AI 客户端如何使用此服务 创作高质量课程）： https://github.com/kemalyy/edumints-scorm-skill

选项 2 — Docker（可自托管）

docker run -p 8000:8000 -v "$PWD/data:/data" ghcr.io/kemalyy/edumints-scorm-mcp:latest
# MCP endpoint: http://localhost:8000/mcp   ·   health: http://localhost:8000/health

该镜像包含所有可选功能（ffmpeg、用于视频的 Node + HyperFrames、Piper TTS）。

**Apple Silicon + Docker Desktop：**如果容器因 Illegal instruction（SIGILL）而崩溃， 这是 cryptography 的 Rust 绑定中的上游原生 ARM64 问题 （pyca/cryptography#14733），与本仓库无关。 解决方法：使用 --platform linux/amd64 运行（模拟执行）。

选项 3 — 本地运行（Python）

python -m venv .venv && source .venv/bin/activate
pip install ".[tts]"          # ".[tts]" adds offline Turkish TTS (Piper); drop it if unwanted
python server.py              # serves MCP over HTTP

如需生成视频，还需安装 Node 22+ 和 HyperFrames（npm i -g hyperframes），以及 ffmpeg。 配置：复制 .env.example 并进行相应调整（数据目录、配额、基础 URL、TTL）。本地运行 无需任何密钥。

示例

课程通过一次 build_from_spec 调用生成（此处为 examples/small.json 的简略内容）：

{
  "title": "Intro to SCORM",
  "scorm_version": "1.2",
  "language": "en",
  "tracking": { "completion_rule": "viewed_all_and_passed", "passing_score": 50 },
  "screens": [
    { "type": "title_slide", "id": "t1", "title": "Intro to SCORM", "subtitle": "Core concepts in 5 minutes" },
    { "type": "content_slide", "id": "c1", "title": "What is SCORM?", "body_html": "<p><strong>SCORM</strong> lets e-learning content talk to an LMS.</p>" },
    { "type": "mcq", "id": "q1", "title": "Mini quiz", "prompt_html": "<p>What is SCORM for?</p>",
      "options": [
        { "id": "a", "text_html": "Content–LMS communication", "correct": true },
        { "id": "b", "text_html": "Video editing" }
      ], "points": 10 },
    { "type": "summary", "id": "s1", "title": "Well done", "body_html": "<p>You learned the basics.</p>" }
  ]
}

build_from_spec(spec) → { project_id, screens: 4, warnings: [] }
build_package(project_id) → downloadable SCORM zip
                              ├─ imsmanifest.xml
                              ├─ index.html          (self-contained player + runtime)
                              └─ assets/

完整可用的规格文件位于 examples/（游戏、分支、主题化和 i18n 课程）。

功能

• 46 个 MCP 工具 — build_from_spec（单次调用流程）、精细化编辑 （create_project / add_screen / update_screen / …）、set_theme / set_tracking、 add_asset（带 SSRF 防护的导入）、synthesize_speech（离线 Piper TTS）、视频工具 （ffmpeg / HyperFrames 动态图形）、preview / validate_package / build_package、 lint_course（质量门禁）、export_qti（QTI 2.1）、list_compositions / set_composition / set_screen_composition。
• 构图系统 — 每门新课程都有明确的焦点、强调层级 （E1–E5：kicker、lead、<mark>），以及从 JSON 模式目录（黄金分割、Z/F 视线流、课程节奏）中选出的平衡对称或非对称布局，也可以使用任意自由网格，适用于所有 31 种屏幕类型。构建课程时，服务会询问关键决策（composition_questions）；问题/投票/分支可选用案例（stimulus）进行应用层评估，标签页采用主从布局，游戏场景则并排显示。新增默认调色板 mint（以及 ink、slate），内嵌 OFL 字体。现有课程渲染效果不变。
• 31 种屏幕类型 — 标题、内容、单选题、判断题、填空题、拖放题、热点题、 分支情景、视频、手风琴、标签页、抽认卡、配对题、排序题、时间线、lottie、 引导式软件模拟、决策情景、术语配对竞速、密室逃脱、标注图表、数据图表、图片对比、 结果细分、投票/反思、总结、可组合游戏、 自适应练习、例题讲解、探索、嵌入式 HTML（制品→SCORM）。 完整参考：docs/SCREEN_TYPES.md。
• 可组合游戏引擎 — game 屏幕可组合机制原语（得分/生命/计时器/提示）+ 声明式 when event if condition then action 规则 + 分支节点；adaptive_practice 会估算熟练度（Elo 或贝叶斯知识追踪），并为每位学习者校准难度。请参阅 docs/GAME-PATTERNS.md。
• 幻灯片舞台播放器 — 固定 16:9 舞台，可缩放至适配各种屏幕；播放器栏 （播放/进度条/字幕/菜单/重播）、与旁白同步的定时时间线、按章节分组的菜单、 完全响应式设计、内联 SVG 图标。支持 i18n 外壳（tr/en）和 RTL。
• 真实 SCORM 跟踪 — cmi.interactions（问题级报告）、cmi.objectives、 adlcp:masteryscore（1.2）/completionThreshold（2004）、LOM 元数据，以及用于 恢复状态的紧凑型 suspend-data v2 编码。
• 主题 — 样式预设（style-minimal / style-playful / style-premium 等） 与品牌令牌分层组合：一种样式，多种品牌。提供浅色/中性色/高对比度预设， 符合 WCAG，并支持 prefers-reduced-motion。
• 质量门禁 — 带阻断级错误的反低质内容 lint，以及游戏无障碍审计。
• 媒体 — 跨 MCP 导入资源（通过 data-URI 或 https 使用 add_asset）、ffmpeg 处理、 以编程方式生成动态视频图形/数据可视化（HyperFrames）、内置离线土耳其语 TTS（Piper）。
• 遥测 — 播放器可选发送 xAPI 语句；cmi5 仅部分支持（仅检测启动——尚未打包 cmi5.xml）。请参阅 docs/GAME-XAPI.md。
• QTI 2.1 导出 — 测验屏幕可导出为 QTI assessmentItem，以便与评估平台互操作。请参阅 docs/QTI.md。
• SCORM 1.2 和 2004、确定性打包、成本防护机制、重型功能需选择启用或按需加载。

标准与证据

声明很容易做出；本仓库在 CI 中提供完整的证据链：

1. XSD 一致性 — 生成的 imsmanifest.xml 文件会根据 ADL/IMS 官方架构进行验证，涵盖 SCORM 1.2 和 2004（在 tests/test_conformance.py 中自动执行）。
2. 真实 SCORM Cloud 往返测试 — CI 通过 REST API 将构建好的软件包导入实际的 SCORM Cloud：4/4 种组合 （小型/丰富型 × 1.2/2004）都必须成功导入，且解析器警告为 0，并生成可启动的注册记录。这是一个阻断门禁，而非仅供参考的检查。
3. 行为探测 — scorm-probe 会在真实 Chromium 中对接模拟 LMS，启动构建好的课程并断言运行时行为（初始化、导航、评分、完成）。这同样是 CI 中的阻断检查；若无声跳过，则构建失败。

详情、流程及如实说明的限制：docs/CONFORMANCE.md。 无障碍：WCAG 2.2 AA 一致性声明，并明确记录限制 — docs/ACCESSIBILITY-CONFORMANCE.md。

官方来源

本项目唯一的官方发布渠道如下：

渠道	URL
源代码仓库	https://github.com/kemalyy/edumints-scorm-mcp
创作技能	https://github.com/kemalyy/edumints-scorm-skill
容器镜像	ghcr.io/kemalyy/edumints-scorm-mcp
托管的 MCP 端点	https://scorm.edumints.com/mcp
账户门户	https://mcp.edumints.com

其他任何内容——镜像仓库、重新上传的 zip 文件、PyPI/npm 软件包、其他注册表或域名——均为非官方且未经验证。目前我们没有发布 PyPI 或 npm 软件包。如果发现仿冒内容，请通过 SECURITY.md 报告。

文档

文档	内容
docs/SCREEN_TYPES.md	全部 31 种屏幕类型及其字段和示例
docs/CONFORMANCE.md	SCORM 一致性证据与流程
docs/ACCESSIBILITY-CONFORMANCE.md	WCAG 2.2 AA 声明
docs/LMS-INTEGRATION.md	针对特定 LMS 的集成说明
docs/QTI.md	QTI 2.1 导出
docs/GAME-PATTERNS.md	游戏引擎模式
docs/GAME-ADAPTIVE.md	自适应练习（Elo/BKT）
docs/GAME-ANTISLOP.md	反劣质内容质量门禁
docs/GAME-XAPI.md	xAPI/cmi5 遥测
docs/GAME-A11Y.md	游戏无障碍
docs/ARCHITECTURE.md	系统架构

架构

MCP client (author)  ──►  scorm-mcp (compiler)
                            ├─ core/        models (Pydantic), packaging, storage
                            ├─ components/  HTML renderer + runtime engine + video compiler
                            ├─ auth/        API-key + OAuth, SSRF guards
                            ├─ themes/      design tokens / presets
                            ├─ runtime/     vendored SCORM runtime (scorm-again, MIT)
                            └─ server.py    FastMCP tools (HTTP)

输出：自包含的 index.html + imsmanifest.xml + 资源 + SCORM 运行时，打包为 zip。

贡献

欢迎提交 Issue 和 PR。代码库倾向于采用小型、专注的模块，进行增量式更改并保持向后兼容。请参阅 CONTRIBUTING.md。测试：pytest。

许可证

• 本项目：MIT — LICENSE。
• 随附的第三方组件（scorm-again、lottie-web）：THIRD_PARTY_NOTICES.md。

由 edumints.com 构建。SCORM 是 ADL 的商标；文中提及的其他产品名称均为其各自所有者的商标（仅作指称用途）。