edumints SCORM MCP

edumints SCORM MCP

[License: MIT] [Release] [Python 3.11+] [MCP]

An MCP server that compiles interactive, standards-conformant e-learning courses. You (or an AI client like Claude) are the author; this server is the compiler. Describe a course as a structured spec — the server validates it, renders it, and packages it as a self-contained SCORM zip that runs in any LMS (Moodle, SCORM Cloud, Rustici Engine, …). Deterministic — no LLM runs on the server.

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

Live demos

Four complete courses — four audiences, four visual identities — built entirely with this server and served from a live deploy. Click any screenshot to launch.

Each demo features a narrative thread, realistic artifact-mockup SVGs, flag-hunting simulations, before/after comparisons, timelines, a case game, and adaptive feedback — with question-level SCORM reporting underneath.

Why this exists

E-learning is usually hand-crafted in heavy desktop authoring tools. This project treats course production as infrastructure for AI agents instead:

• Zero-install authoring. Connect any MCP client to the hosted endpoint and start building — no toolchain, no local setup. The client describes the course (objectives, screens, quizzes, branching, media) over the Model Context Protocol; the server does the hard part: validation, theming, accessible HTML rendering, the SCORM runtime bridge, and packaging.
• A quality gate that says no. AI can generate a lot of mediocre content fast. This server pushes back: schema validation on every spec, an anti-slop lint (lint_course) whose error tier blocks builds, and a CI proof chain (XSD + real SCORM Cloud imports + behavioral probe) so that what ships actually works in an LMS — see Standards & evidence.
• No vendor lock-in. Output is a plain SCORM 1.2/2004 zip with a self-contained player. MIT licensed, self-hostable, and open to contributions.

Author = the MCP client · Compiler = this server.

[A quiz screen rendered in the built-in slide-stage player]

Quickstart

Option 1 — Hosted MCP (zero install)

Point any MCP client (Claude desktop/web/Code, Antigravity, …) at:

https://scorm.edumints.com/mcp

Sign in via OAuth or get an API key at the portal: https://mcp.edumints.com. Then ask: "Build a 6-minute interactive course on X with a quiz and a summary." — you get a downloadable SCORM zip back.

Works best together with the authoring skill (a Claude Agent Skill that teaches an AI client how to author high-quality courses with this server): https://github.com/kemalyy/edumints-scorm-skill

Option 2 — Docker (self-hosted)

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

The image includes all optional features (ffmpeg, Node + HyperFrames for video, Piper TTS).

Apple Silicon + Docker Desktop: if the container crashes with Illegal instruction (SIGILL), it is an upstream native-ARM64 issue in cryptography's Rust bindings (pyca/cryptography#14733) — not this repo. Workaround: run with --platform linux/amd64 (emulated).

Option 3 — Local (Python)

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

For video generation also install Node 22+ with HyperFrames (npm i -g hyperframes) plus ffmpeg. Configuration: copy .env.example and adapt (data dir, quotas, base URL, TTLs). No secrets are required to run locally.

Example

A course is produced from a single build_from_spec call (this is examples/small.json, abridged):

{  "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/

Full working specs live in examples/ (games, branching, themed and i18n courses).

Features

• 46 MCP tools — build_from_spec (single-call path), granular editing (create_project / add_screen / update_screen / …), set_theme / set_tracking, add_asset (SSRF-guarded imports), synthesize_speech (offline Piper TTS), video tools (ffmpeg / HyperFrames motion-graphics), preview / validate_package / build_package, lint_course (quality gate), export_qti (QTI 2.1), list_compositions / set_composition / set_screen_composition.
• Composition system — every new course gets a deliberate focal point, an emphasis hierarchy (E1–E5: kicker, lead, <mark>) and a balanced symmetric/asymmetric layout chosen from a JSON pattern catalogue (rule of thirds, Z/F eye flow, course rhythm) — or any free grid — on all 31 screen types. The server asks the decisions that matter while the course is built (composition_questions), questions/polls/branching take an optional case (stimulus) for application-level assessment, tabs become master–detail and game scenes go side by side. New default palette mint (+ ink, slate), embedded OFL fonts. Existing courses render unchanged.
• 31 screen types — title, content, MCQ, true/false, fill-in-the-blank, drag & drop, hotspot, branching scenario, video, accordion, tabs, flashcards, matching, sorting, timeline, lottie, guided software simulation, decision scenario, term-match race, escape room, labeled diagram, data chart, image compare, results breakdown, poll/reflection, summary, composable game, adaptive practice, worked example, exploration, embedded HTML (artifact→SCORM). Full reference: docs/SCREEN_TYPES.md.
• Composable game engine — the game screen composes mechanic primitives (score/lives/timer/hints) + declarative when event if condition then action rules + branching nodes; adaptive_practice estimates proficiency (Elo or Bayesian Knowledge Tracing) and calibrates difficulty per learner. See docs/GAME-PATTERNS.md.
• Slide-stage player — fixed 16:9 stage scaled to every screen, player bar (play/seekbar/captions/menu/replay), narration-synced timed timelines, section-grouped menu, fully responsive, inline SVG icons. i18n shell (tr/en) with RTL support.
• Real SCORM tracking — cmi.interactions (question-level reporting), cmi.objectives, adlcp:masteryscore (1.2) / completionThreshold (2004), LOM metadata, and a compact suspend-data v2 encoding for resume state.
• Theming — style presets (style-minimal / style-playful / style-premium, and more) layered with brand tokens: one style, many brands. Light/neutral/high-contrast presets, WCAG-aware, prefers-reduced-motion support.
• Quality gates — anti-slop lint with a blocking error tier, plus game accessibility audits.
• Media — cross-MCP asset import (add_asset via data-URI or https), ffmpeg processing, programmatic motion-graphic/data-viz video (HyperFrames), built-in offline Turkish TTS (Piper).
• Telemetry — optional xAPI statements from the player; cmi5 is partial (launch detection only — no cmi5.xml packaging yet). See docs/GAME-XAPI.md.
• QTI 2.1 export — quiz screens export as QTI assessmentItems for interop with assessment platforms. See docs/QTI.md.
• SCORM 1.2 & 2004, deterministic packaging, cost guardrails, opt-in/lazy heavy features.

Standards & evidence

Claims are cheap; this repo ships its proof chain in CI:

1. XSD conformance — generated imsmanifest.xml files are validated against the official ADL/IMS schemas for both SCORM 1.2 and 2004 (automated in tests/test_conformance.py).
2. Real SCORM Cloud round-trip — CI imports built packages into actual SCORM Cloud via its REST API: 4/4 combinations (small/rich × 1.2/2004) must import with 0 parser warnings and produce a launchable registration. This is a blocking gate, not an advisory check.
3. Behavioral probe — scorm-probe launches built courses in real Chromium against a fake LMS and asserts runtime behavior (init, navigation, scoring, completion). Also blocking in CI; a silent skip fails the build.

Details, procedures and honest limits: docs/CONFORMANCE.md. Accessibility: WCAG 2.2 AA conformance statement with explicitly documented limitations — docs/ACCESSIBILITY-CONFORMANCE.md.

Official sources

The only official distribution channels for this project are:

Anything else — mirror repos, re-uploaded zips, PyPI/npm packages, other registries or domains — is unofficial and unverified. We publish no PyPI or npm packages today. If you find a lookalike, please report it via SECURITY.md.

Documentation

Architecture

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)

Output: self-contained index.html + imsmanifest.xml + assets + SCORM runtime, zipped.

Contributing

Issues and PRs welcome. The codebase favors small focused modules, additive changes and backward compatibility. See CONTRIBUTING.md. Tests: pytest.

License

• This project: MIT — LICENSE.
• Vendored third-party components (scorm-again, lottie-web): THIRD_PARTY_NOTICES.md.

Built by edumints.com. SCORM is a trademark of ADL; other product names mentioned are trademarks of their respective owners (nominative use only).