SCORM Packager (HTML → SCORM 2004)

scorm-mcp-server

将独立 HTML、Claude Design .dc bundle 或移动学习平台内容导出文件（Excel 活动模板 + 媒体）转换为可导入任何 LMS 的 **SCORM 2004（或 1.2）**包——资源内嵌，实现 100% 离线运行；注入完成状态 / 进度 / 分数跟踪功能，并打包 ADL 架构文件。

内置的本地测试工具（scorm-test-harness.html）正在运行一个包：进度从 0 → 100%、完成状态，以及实时 LMS API 调用日志（0 个错误）。示意图。

这是一个 MCP 服务，提供三个工具：scorm_package 将完成的 HTML 学习模块转换为 .zip（PIF），供任何符合 SCORM 标准的 LMS 导入；scorm_validate 检查任何现有的 SCORM zip（由任意工具制作），并准确说明 LMS 会拒绝它的原因；scorm_selftest 是一项耗时 1 秒的健康检查。

原则：封装，而非重写。 保留你的 HTML；该工具只会：

1. 内嵌所有资源（CSS、@import、字体、JS、图片、srcset、网站图标），将其转换为 data URI → 实现 100% 离线运行。
2. 注入一个小型运行时，用于报告完成状态、进度（%）和用时，并支持跨会话恢复。
3. 生成清单并打包 15 个官方 ADL XSD 架构文件——清单会依据这些架构进行验证（真正符合标准，而不只是“格式正确”）。

✅ 状态——已在真实 LMS 上验证

• 325/325 项自动化检查通过：23 项转换器 · 15 项运行时 · 15 项 MCP · 1 项架构符合性（xmllint）· 6 项安全性 · 11 项功能 · 13 项自动里程碑 · 21 项 V2（bundle / .dc / 分数）· 10 项输出目录 · 9 项跟踪信号 · 32 项加固 · 29 项 SCORM 1.2 · 12 项 CLI/批处理 · 16 项 Web UI · 44 项移动学习迁移 · 35 项包验证 · 33 项题目级交互——另有 6 项额外严格运行时检查（scorm-again）。
• SCORM Cloud（真实 LMS）： 可顺利导入（识别为 SCORM 2004 4th Ed.，“清单看起来很棒”），且仪表板显示完成状态 = complete，成功状态 = passed，时间已跟踪。

输入格式

输入（input_path 或 html）	处理方式
单个独立 .html 文件（例如 Claude Design 的“独立 HTML”导出文件）	内嵌资源并注入运行时——v1 路径
文件夹或 .zip（多文件模块）	保留整个目录树；内嵌入口 HTML；清单列出所有文件
Claude Design .dc bundle（*.dc.html + support.js + _ds/）	自动检测；通过 window.__resources 将 CDN 库（React/Babel…）打包为本地资源以支持离线运行（不修改源码）；在 support.js 之前注入运行时
移动学习平台内容导出文件（Excel 活动模板 + media/）	自动检测；根据模板重建交互式 HTML 课程——信息卡 / 过渡卡 / 闪卡、测验题目、媒体代码（[media:…]、[H1:…]、[quote:…]、!!）、会报告 cmi.score 的计分测验——然后打包。课程标题根据模板名称生成；使用 --batch 时，可在一次运行中迁移整个目录

将 .dc bundle 作为**文件夹或 .zip**传入（不要只传单独的 .dc.html，没有其他配套文件时它无法运行）。

分数与测验（可选）

设置 mastery_score（0..1）即可启用基于分数的成功判定，并向清单添加顺序目标。只需用一行报告内容中的分数，无需了解 SCORM：

window.SCORM2004.score(8, 0, 10);                                   // raw, min, max
window.dispatchEvent(new CustomEvent("scorm:score",    { detail: { raw: 8, min: 0, max: 10 } }));
window.dispatchEvent(new CustomEvent("scorm:progress", { detail: 0.5 }));  // 0..1
window.dispatchEvent(new CustomEvent("scorm:complete"));

运行时会将这些值映射到 cmi.score.*，根据 mastery_score 设置 success_status = passed/failed，并报告完成状态/进度。（dc:* 事件名称也可作为别名使用。）

题目级跟踪（v2.3）——将每个答案报告为一条 cmi.interactions 记录，这样 LMS 成绩册会显示错了哪些题目，而不只是总分：

window.SCORM2004.interaction({
  id: "quiz1-q3", type: "choice",
  description: "Which colour is the brand?",
  learnerResponse: "Blue", correctResponse: "Red",
  result: false, latencyMs: 12000,
});
// or, without touching the API:
window.dispatchEvent(new CustomEvent("scorm:interaction", { detail: { id: "q3", result: true } }));

支持方言差异（2004 使用 learner_response/timestamp，而 1.2 使用 student_response/time；incorrect 对应 wrong），并且按设计尽力而为：如果 LMS 拒绝写入交互记录，会记录警告并继续会话。通过移动学习迁移生成的测验会自动报告交互记录——每道题一条，包含题目文本、学习者的答案、预期答案和作答耗时。

SCORM 1.2、批处理模式、CLI（v2.1）

SCORM 1.2——传入 scorm_version: "1.2"，即可获得 1.2 清单（使用随附的 1.2 XSD 进行验证，并在设置 mastery_score 时包含 adlcp:masteryscore）。注入的运行时具有自适应性：它会与托管 LMS 所提供的 API 通信（API_1484_11 或 API），映射数据模型（单个 lesson_status、0-100 分、HH:MM:SS 会话时间、4096 字符的挂起数据），且绝不会将 passed 状态降级。

批处理——batch: true 会将 input_path 视为课程目录（每个子目录、.zip 或 .html 文件代表一门课程）。每门课程生成一个包，生成一份汇总的 batch-report.json；某门课程损坏也不会影响其他课程。

CLI——无需 MCP 客户端：

npx -y scorm-mcp-server ui            # local drag & drop web UI
npx -y scorm-mcp-server pack course.html --title "My course"
npx -y scorm-mcp-server pack ./courses --batch --scorm-version 1.2
npx -y scorm-mcp-server validate pkg.zip   # conformance-check an existing package
npx -y scorm-mcp-server selftest      # 1-second health check

Web UI——ui 会打开一个 localhost 页面：拖入 .html 或 .zip 文件，选择 SCORM 版本和可选的及格分数，然后下载包。所有操作都在你的机器上运行；不会上传任何内容。

库——buildPackage() 是供流水线和 SaaS 后端使用的公共 API：

import { buildPackage } from "scorm-mcp-server";
const r = await buildPackage({ html, title: "My course", scormVersion: "1.2", masteryScore: 0.6 });
// r.zip (Buffer) · r.fileName · r.warnings · r.milestoneIds …

诊断——scorm_selftest MCP 工具会打包一个内置的固定 HTML 文件，并报告版本、耗时和输出路径：只需一秒即可区分“服务端故障”和“输入问题”。

验证任意 SCORM 包（v2.3）

“为什么我的 LMS 拒绝这个 zip？”——scorm_validate 可验证任意 SCORM 包，而不只是此处生成的包，并且绝不会修改输入：

npx -y scorm-mcp-server validate course.zip          # human-readable report
npx -y scorm-mcp-server validate course.zip --json   # machine-readable

检查项：zip 可读性、imsmanifest.xml 是否位于根目录（检测常见的*“打包了文件夹而非其内容”*错误，并说明如何修复）、清单格式是否正确、SCORM 版本检测（2004/1.2）、可启动的组织/项目/资源链、启动文件以及归档中是否存在每个 <file href>（会标记仅大小写不同的路径——它们在 Windows 上可用，但在 Linux LMS 服务端会失败），以及使用官方 ADL 架构进行完整的 XSD 验证——优先使用包自身的 XSD，若无则回退到内嵌副本，因此不含架构文件的包也能通过验证。退出代码为 0/1，可用于 CI 流水线；也可作为 scorm_validate MCP 工具和 validatePackage() 库 API 使用。

安装

选项 0 — 在线试用，无需安装

https://scormpackager.vercel.app——拖入课程，选择 SCORM 版本，然后下载包。 文件会在内存中处理，绝不会存储，但会传输到服务器； 实际使用时，请选择下方的本地选项，数据不会离开你的机器 （且没有 4 MB 限制）。

选项 A — 一键安装（推荐）

从 Releases 下载 scorm-mcp-server-x.y.z.mcpb，然后在 Claude Desktop → Settings → Extensions 中拖放 .mcpb 文件，选择输出文件夹并启用。

选项 B — npm（任何 MCP 客户端）

无需安装：将以下内容添加到客户端的 MCP 配置中（Claude Desktop 的配置文件为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "scorm": {
      "command": "npx",
      "args": ["-y", "scorm-mcp-server"],
      "env": { "SCORM_OUTPUT_DIR": "/ABSOLUTE/PATH/scorm-packages" }
    }
  }
}

注册表名称：io.github.giacomomaria81/scorm-mcp-server（MCP 注册表）。

选项 C — 从源代码安装（开发者）

git clone <this-repo> && cd scorm-mcp-server
npm install        # dist/ is prebuilt; npm run build is optional

然后将配置指向 node /ABSOLUTE/PATH/scorm-mcp-server/dist/index.js。

重启 Claude。现在可以使用 scorm_package 工具了。

使用方法

在对话中：先用 Claude Design 构建模块，然后说 “将此模块打包为 SCORM。” Claude 会调用 scorm_package 并返回 .zip 的路径。

进度与完成状态 — 自动生效

无需进行任何准备：如果 HTML 未声明里程碑，打包器会根据文档结构自动生成里程碑（章节 → 文章 → 标题，最多 8 个，触发条件为 view）。普通 HTML 也能开箱即用地获得有意义的进度。使用 auto_milestones: false 可禁用此功能。想在完成时将 success_status 设为 passed，又不想修改 HTML？传入 success_on_completion: true。

声明式里程碑（建议用于精细控制）

在 HTML 中直接标记有意义的步骤——显式里程碑始终优先于自动生成的里程碑。运行时会计算 progress_measure = milestones_reached / total，并在所有里程碑均已达成时将 completion_status = "completed"。

属性	效果
data-jalon="unique-id"	声明一个里程碑
data-trigger="view"	滚动到视口中时达成（默认值）
data-trigger="click"	点击时达成
data-trigger="ended"	视频或音频结束时达成

<section data-jalon="intro"       data-trigger="view">…</section>
<button  data-jalon="read-pitch"  data-trigger="click">I read it</button>
<video   data-jalon="demo"        data-trigger="ended">…</video>

建议：每个微型模块设置 4–8 个里程碑。进度会自动恢复（cmi.suspend_data + cmi.location）；不会倒退。

以编程方式设置里程碑 — 即使没有带 data-jalon 的元素，window.SCORM2004.reach("quiz-passed") 也能正常工作：未知 ID 会即时声明，并计入总数。若想在达成前注册里程碑（以获得准确的分母），请提前调用 window.SCORM2004.declare("quiz-passed")。两种方式的状态都会在恢复时保留。

成功状态（可选） — 在任意元素（例如 <body>）上添加 data-scorm-success="on-completion"，模块完成时运行时也会将 cmi.success_status="passed" 写入。若不添加此属性，则永远不会写入 success_status。

语言 — 如果源 HTML 未声明语言，工具的 language（BCP-47，默认值为 fr-FR）会应用为 <html lang="…">。

安全性 — 资源引用仅限于模块文件夹：不会内联 ../ 或指向该文件夹之外的绝对路径（会发出警告）。

无需 LMS 账户即可测试

通过一个简单的本地服务器打开 scorm-test-harness.html，然后将生成的 .zip 拖放到页面中：

python3 -m http.server 8000   # then open http://localhost:8000/scorm-test-harness.html

你将看到实时进度百分比、完成状态以及 LMS API 调用的完整日志（预期错误数为 0）。

构建与测试

npm install
npm run build     # tsc -> dist/
npm test          # 325 checks across 17 suites (xmllint required for the schema tests)

# bonus: validate against a strict independent SCORM 2004 runtime
npm i -D scorm-again && node test/scorm-again.test.mjs

要求：Node ≥ 20，以及用于架构测试的 xmllint（libxml2-utils）。

项目结构

src/        index.ts (MCP server + CLI) · converter.ts (inlining + manifest + zip) · runtime.ts (injected SCORM runtime) · validate.ts (package conformance checker) · tom.ts (mobile-learning migration) · ui.ts (local web UI)
dist/       compiled output (shipped)
schemas/    15 ADL XSD (SCORM 2004 4th Ed.) + schemas12/ (4 XSD SCORM 1.2), bundled into every package
test/       17 suites (converter / runtime / mcp / schema / validation / interactions / migration…) + fixtures
ARCHITECTURE.md           design decisions, data flow, testing strategy
scorm-test-harness.html   local browser SCORM player (fake LMS, no account)
manifest.json             MCPB manifest (for building the .mcpb desktop extension)

隐私政策

此扩展完全在本地运行：不收集数据、不进行遥测，也不涉及第三方。唯一的网络活动是下载你自己的 HTML 引用的资源，并将其嵌入离线包中。完整政策：PRIVACY.md。

许可证

MIT