feat(mcp): render lesson MDX in the lesson widgets the way the app does

[guillermoscript]

What

The MCP lesson widgets (lesson-viewer, lesson-preview) now render lessons.content with the same component set the web app uses, instead of running MDX through a plain markdown renderer.

Closes #

Why

lessons.content is MDX — markdown plus the ~30 JSX components registered in components/lesson/mdx-components.tsx (<Callout>, <Quiz>, <Steps>, <Definition>, <Table>, <Comparison>, <FlashcardSet>, <Ordering>, <Video>, <LessonCheckpoint>, …). The web app compiles it with next-mdx-remote-client and hands <MDXClient> that map.

Both widgets instead passed the same string to react-markdown, which knows nothing about those tags — so a student reading a lesson through the MCP server got the raw source printed at them, JSON.parse('…') payloads and all (see the before shot). embed_code was never sent to the widget at all, and video_url rendered as a bare link rather than a player.

Why parse instead of compile: widgets can not compile-and-run MDX — @mdx-js/mdx's run() (and next-mdx-remote-client's MDXClient) build the module with the Function constructor, which the widget CSP sandbox blocks. So this parses only (remark + remark-mdx keeps JSX as mdxJsxFlowElement nodes) and renders that mdast tree with React. JSX attribute expressions are resolved without a JS runtime, including the {JSON.parse('…')} form components/teacher/block-editor/serializer.ts emits.

How

• mcp-server/resources/shared/lesson/ (new)
  • mdx.ts — mdast parse + attribute resolution (JSON.parse('…'), literals, bare attrs)
  • components.tsx — widget port of the app's lesson components, app tokens mapped to the widget zinc/violet palette
  • renderer.tsx — mdast → React, plus the tag→component map mirroring lessonMdxComponents
  • index.tsx — <LessonBody>: video → embed → MDX, the same order as lesson-content.tsx
• Both widgets call <LessonBody>; lms_get_lesson now selects and passes embed_code (the student path already carried it).
• embed_code is rendered sandboxed (sandbox="allow-scripts allow-popups"), never injected — the widget host is not the tenant's own page, so the app's trusted mode does not apply.
• Failure modes are contained: unknown tags keep their text, an unparseable lesson falls back to its source with a notice, and an error boundary stops one bad component from blanking the lesson.
• <LessonCheckpoint> renders a marker rather than an answerable exercise — checkpoint attempts are server-write-only and entitlement-gated (Lesson-checkpoint attempt route gates on a self-issuable enrollment row, bypassing entitlements and the access cutoff (#509 follow-up) #532/Lock the write side: grades, progress and practice rows are self-issuable #543), and the exercise renderer needs the lesson's checkpoint provider.

Deliberate differences from the app

• No Shiki highlighting in code blocks (it would add ~1 MB to each widget); the code block keeps its filename/language header and copy button.
• Widget strings are English; the app's lesson components hardcode Spanish regardless of locale.
• The widget honours <Spoiler label> and <Vocabulary audioUrl> — the names the block editor actually serializes. The app's components only read title / audio, so those authored values are silently dropped there. Pre-existing app bug, worth its own issue.

Cost: +280 KB raw (+70 KB gzip) per lesson widget bundle for remark-mdx.

How to QA

1. cd mcp-server && npm install && npm run build — both lesson widgets build.
2. npx vitest run tests/unit/mcp-lesson-mdx.test.ts — 15 tests covering attribute resolution and a full render of a serializer-shaped lesson.
3. In-app: as creator@codeacademy.com (code-academy.lvh.me:3000), author a lesson in the visual editor with a callout, a quiz and a table; then call lms_view_lesson / lms_get_lesson through the MCP server and confirm the widget shows the rendered components rather than source text.

Screenshots

Same lesson source, rendered by the widget before and after. Files are in the branch at docs/images/mcp-lesson-render-*.png if the embeds do not load.

Before — authored components printed as source:

After (light):

After (dark):

In the inspector, with realistic data

Run through mcp-use dev + mcp-use client screenshot against a throwaway no-auth entry, so the widget renders exactly as an MCP client shows it.

Lesson 2008 from the local seed (plain markdown — code blocks keep their language header and copy button):

A lesson authored in the visual block editor — callout, steps, table, definition, quiz, ordering, fill-in-the-blank, spoiler, comparison, flashcards, checkpoint, file download, video:

Same lesson, dark:

Teacher-side lesson-preview widget, same content plus attached resources (the YouTube embed loads for real here):

The inspector run caught a bug the static tests missed: steps rendered 1, 3, 5 because <Step> took its number from a counter bumped during render, which React's development double-invoke counts twice. Fixed in ea1e7c17 by numbering in the mdast walk. The web app's components/lesson/steps.tsx has the same shape of bug (module-level counter bumped in render) — pre-existing, worth its own issue.

Checklist

• npm run typecheck (mcp-server tsc --noEmit) and npm run test:unit pass — 478 unit tests green
• mcp-use build passes (the Next npm run build is untouched by this change)
• No new queries; the one changed select (lms_get_lesson) keeps its existing ownership check
• Tested for the student path (lms_view_lesson) and the teacher path (lms_get_lesson)
• Loading and error states handled (widget pending state, parse-failure fallback, render error boundary)
• No new app UI strings (widget copy lives in the widget, like the rest of mcp-server/resources)
• No migration

🤖 Generated with Claude Code

https://claude.ai/code/session_01QpttCAB3gFD9H5WFHG4boW