feat(mcp): a local MCP server that builds, checks and previews packages

Merged
AL
10h ago
+998-17

Closes #226. Part of #219 (step 2).

A local MCP server, @missing-elements/h5p-mcp ("H5P Author MCP by Missing Elements"), so an app with no shell, Claude Desktop first, can build a package onto the person's disk, check it and open it in their browser.

What it is

  • Three tools over stdio.
    • h5p_types: the pack's 55 content types, those with a type file marked, and the skill's brief. Given a type (read loosely, as a build reads one), it answers with the type's file from the author package, or its fields for a type with none.
    • h5p_build: builds a source into the folder, with its .source.json beside it. It never writes over a file or through a link: a taken name, the package's or its source's, gets the next number, and builds at once get names of their own. A source with problems is refused, each problem by its path. Otherwise it answers with the outline, the verifier's summary and its screenshot as an image.
    • h5p_preview: the verifier's preview in the person's browser.
  • h5p_build shows a source's own fields (#230). Its source carries the fields of the author package's sourceSchema (#231) as JSON Schema properties, so a model gets the authors and the licence right before its first build. Nothing is marked required or forbidden, and the field still takes any object. The build is the check: it reads a source written another way as it is meant and reports every problem at once (#174). The SDK, or an app that enforces the schema, would refuse such a source without reading it.
  • The instructions are the skill's flow in a few lines. With the tool descriptions they come to about 570 tokens, which an app sends with every message.
  • No rules of its own. The build and its confinement are h5p-author's, the check and the preview h5p-verify's. For it, author exports inside(), and verify exports previewPackage() and openBrowser(), which it kept internal.
  • The folders: --allow, else the app's MCP roots, else Desktop, Documents and Downloads, which are never the home folder whole, nor a link to it; --allow and the roots are taken as given. This puts --allow before the roots, unlike the issue's order: a folder the person named when adding the server is their choice. Every h5p_types answer, and a refused path, names the folders, since a model cannot know them.
  • MCP SDK v2. @modelcontextprotocol/server 2.4.0 (v1 is the maintenance line). It brings only its core and zod, so the package ships bin/ and lib/ as written, with no bundle, and the lockfile loses v1's 57 packages (Express, Hono, ajv and the rest). It serves the 2025 protocol, which every app speaks. Protocol 2026-07-28 deprecates roots, so serving that revision would leave --allow and the defaults.
  • Docs: design/mcp.md, the package's README, and a row each in AGENTS.md, design/layout.md, the README and SECURITY.md. SECURITY.md also gains h5p-author, which it lacked. docs/compatibility.md names the verifier's two new functions.

Testing

  • packages/mcp, 18 tests. Those of the server start the command over stdio with the SDK's own client and call every tool, each test building what it needs:

    • the type list; a type by a loose name; one with no file;
    • a build checked in Chromium, with its image;
    • a taken name, a link at one, two builds at once; a source with a problem;
    • an output outside the folder;
    • a preview served, and one refused.
  • Types: tsc passes for the new package, and for author and verify with their new exports pinned in package-types.ts.

  • Haiku 5.5 in Claude Code 2.1.326, as an app with no shell would run it: no built-in tools, only the server's, each run in a folder of its own. Each run cost $0.003 to $0.010.

    TaskFirst versionFinal version
    Question Set, three questions1 build, passes1 build, passes
    Course Presentation, with volcano.png from the folder4 builds1 build, 2 of 2 runs
    Interactive Video from clip.mp4 in the folder, two questions4 builds2 builds at most, 2 of 2 runs
    "a quiz", no type namedasked which type, and nothing else
    • Course Presentation and Interactive Video, first version: every failed round was a path Haiku guessed from its own working folder, first for the output and then for the picture. The refusals named no folder, so it had nothing to go on. Since every type's answer names the folders, the sources build as written.

    • The remaining Interactive Video failures:

      • one run had an author with no name, fixed in the next build;
      • one run had two tool calls that Claude Code rejected as invalid JSON before they reached the server; Haiku then built.

      This answers #210's open question: Haiku does write a whole source as a tool argument.

  • On SDK v2: the tools' schemas are v1's except for two things: $schema is now JSON Schema 2020-12 (was draft-07), and v1's execution.taskSupport is gone. In Claude Code, Haiku built a Question Set with volcano.png that passed the check. It took 2 builds: the first was refused because it wrote the author as a bare name.

  • With a source's fields shown (same tasks: Question Set, Course Presentation, Interactive Video):

    ServerRuns that builtFirst build wrote "authors": ["Unknown"]
    without the fields shown32
    with them90

    The last 3 runs, with the fields shown and nothing required, each built at the first build. What an app sends with every message grew to 3,993 characters (about 1,000 tokens), under the test's 6,000.

Not verified

  • Claude Desktop itself, Windows, and a real npx -y @missing-elements/h5p-mcp: that needs the package on npm.
  • MCP roots from a real app: tested with --allow only.

Release

Order matters, because each package needs the new exports of the one before it:

  1. normalize 1.4.0, for ./mp4 (#228).
  2. author 0.12.0, for inside.
  3. verify 1.6.0, for previewPackage and openBrowser.
  4. h5p-mcp 0.1.0.

Then, the owner's:

  • the MCP registry's server.json;
  • a Claude Desktop bundle;
  • the organisation's site, which says "no MCP server" in places.

Summary by cubic

Adds @missing-elements/h5p-mcp ("H5P Author MCP by Missing Elements"), a local MCP server so an app with no shell — Claude Desktop first — can build an H5P package onto the person's disk, check it, and open it in their browser. It offers three tools over stdio: h5p_types lists the content types and answers a type with its notes or fields, h5p_build builds a package from a short JSON source with its .source.json beside it, and h5p_preview serves the check's preview in the browser.

  • The server holds no rules of its own: the build, its checks and the folder confinement are h5p-author's, the check and preview h5p-verify's. New exports: inside() from author, previewPackage() and openBrowser() from verify, with their type declarations updated. h5p_build's source carries sourceSchema as JSON Schema, so a model writes the authors and licence right; the field takes any object, with nothing required or forbidden, and the build says every problem at once.
  • A build never writes over a file: a taken name — the package's or its source's, by a file or by a link, even one to nowhere — gets the next number, a name is held while its build runs so builds at once take their own, and the source is written new, never through a link. A source with problems is refused by path, and the answer holds the outline, the verifier's summary and its screenshot.
  • Builds read and write only in --allow folders, the app's MCP roots, or Desktop, Documents and Downloads; --allow and the roots are taken as given, and only the defaults are never the home folder whole — one that links to it, or above it, is left out. The local-network refusal is the download's: a video on YouTube, Vimeo, Panopto or Echo360 is never downloaded, its address is kept and plays wherever it points (Panopto is often an institution's own server); other files the source names are downloaded. Math is drawn by the package's own copy of MathJax, which loads nothing from elsewhere.
  • The MCP SDK is now v2: @modelcontextprotocol/server 2.4.0 brings only its core and zod, so no esbuild bundle is needed and the package ships bin/ and lib/ as written, with none of the HTTP frameworks v1 pulled in.
  • Tests start the server over stdio with the SDK's own client and exercise every tool, including a link at a name and two builds at once; the link test is skipped on Windows. Instructions plus tool descriptions stay under 6,000 characters, what an app sends the model with every message.

Release order matters because the server needs the new exports: author 0.12.0, verify 1.6.0, then h5p-mcp 0.1.0. After that come the MCP registry entry, the Claude Desktop bundle, and the organisation site's "no MCP server" claims.