Skip to content

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

Merged
alekswebnet merged 10 commits into
mainfrom
feat/mcp-server
Nov 18, 2026
Merged

alekswebnet merged 10 commits into
mainfrom
feat/mcp-server

Conversation

@alekswebnet

@alekswebnet alekswebnet commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

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 (author: declare a source's own fields once, as a schema a model can be shown #230). Its source carries the fields of the author package's sourceSchema (feat(author): declare a source's own fields once, as a schema (#230) #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 (h5p-author: a chat with no skill text spends a round on each layer of a source's outer shape #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.

    Task First version Final version
    Question Set, three questions 1 build, passes 1 build, passes
    Course Presentation, with volcano.png from the folder 4 builds 1 build, 2 of 2 runs
    Interactive Video from clip.mp4 in the folder, two questions 4 builds 2 builds at most, 2 of 2 runs
    "a quiz", no type named asked 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 h5p-author: a ChatGPT app that plays the activity in the chat, through an MCP server that stores nothing #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):

    Server Runs that built First build wrote "authors": ["Unknown"]
    without the fields shown 3 2
    with them 9 0

    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 (feat(author): check a video's and a recording's bytes, and read an mp4's index (#218) #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.

Written for commit 9a6b184. Summary will update on new commits.

View guided diff Turn on auto-fix

…es (#226)

@missing-elements/h5p-mcp, H5P Author MCP by Missing Elements: three tools over
stdio for an app with no shell. h5p_types lists the pack's content types and
answers a type with its file from the author package, or its fields;
h5p_build builds a source into the person's folder with its .source.json,
never over a file, refuses a source with problems by path, and answers with
the outline, the verifier's summary and its screenshot; h5p_preview opens
the verifier's preview. Every answer about a type names the folders the
server may use, since a model cannot know them.

It holds no rules of its own: author exports inside(), and the verifier
previewPackage() and openBrowser(), for it. The folders are --allow, else the
app's roots, else Desktop, Documents and Downloads. The MCP SDK and zod are
bundled with esbuild, so npx installs none of the SDK's HTTP dependencies.
@socket-security

socket-security Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Added@​modelcontextprotocol/​client@​2.4.0921008295100
Added@​modelcontextprotocol/​server@​2.4.01001008396100

View full report

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 25 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/mcp/lib/folders.mjs Resolved
Comment thread packages/mcp/lib/server.mjs Resolved
Comment thread design/mcp.md Resolved
Comment thread packages/author/README.md Resolved
Comment thread packages/mcp/README.md Resolved
Comment thread packages/mcp/tests/server.test.ts Resolved
Comment thread packages/mcp/lib/folders.mjs Resolved
Comment thread packages/mcp/lib/folders.mjs Resolved
Comment thread packages/mcp/lib/server.mjs Resolved
Comment thread packages/mcp/README.md Resolved
- The source beside a package is part of choosing its name, is made
  new ('wx'), and a link at either name takes it, even one to nowhere.
- A name is held while its build runs, so builds at once get their own.
- A default folder that links to the home folder, or above it, is left
  out; one linking elsewhere, as to another drive, is kept.
- File names: cut by characters, not UTF-16 halves; `-file` after a
  name Windows keeps for a device.
- Tests: Documents covered, each server test builds what it needs, a
  link and two builds at once tested.
- Docs: publicFetch is a guard against a mistake or a planted address,
  not a hostile network; the browser the check needs; audio and other
  files downloaded; 53 hub types; `await inside`; what `closed`
  settles with; SECURITY.md's scope covers author and the server.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 9 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread SECURITY.md Resolved
Comment thread packages/mcp/README.md Resolved
Comment thread packages/mcp/tests/server.test.ts Resolved
…o stays an address (#226)

- SECURITY.md, the README and design/mcp.md: --allow and the app's
  roots are taken as given; only the default folders are never the
  home folder whole.
- The README: a video on YouTube, Vimeo, Panopto or Echo360 stays an
  address; the rest is downloaded.
- The link test is its own, skipped on Windows, where a link to a file
  takes privileges.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 4 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/mcp/README.md Resolved
…o's address is kept (#226)

publicFetch guards what a build downloads. A video on YouTube, Vimeo,
Panopto or Echo360 is never downloaded: its address is kept and the
player loads it wherever it points, Panopto often being an institution's
own server on its own network. The README, SECURITY.md and design/mcp.md
now say so.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 3 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/mcp/README.md Resolved
@modelcontextprotocol/server 2.4.0 replaces @modelcontextprotocol/sdk 1.32.2, the maintenance
line, before the first release. v2's server package brings only its core and zod, none of the
HTTP frameworks v1 installed, so the reason for the esbuild bundle is gone: the package ships
bin/ and lib/ as written, scripts/build.mjs and dist/NOTICE.txt go, and the lockfile loses 57
packages. The tools' schemas are zod objects, as v2 asks; an app sees v1's schemas but for
$schema, now JSON Schema 2020-12. It still serves the 2025 protocol every app speaks, where the
app's roots work as before.
# Conflicts:
#	packages/author/tests/package-types.ts
…cks (#230)

h5p_build's source carries the author package's sourceSchema as JSON Schema, so a model writes
the authors and the licence right before its first build. Without it, Haiku wrote
"authors": ["Unknown"] in 2 of 3 runs that built; with it, in none of 6. The field still takes
any object: the build reads a source written another way as it is meant and says every problem at
once (#174), where the SDK would refuse it unread. The tool's description no longer lists the
fields, which the shape now shows.
…thing from elsewhere (#226)

What cubic found: the README put math beside a hosted video, as loaded wherever it points. The
package carries H5P.MathDisplay with MathJax in its folder, and MathJax loads from there.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 5 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/mcp/lib/server.mjs Resolved
…230)

What cubic found: the shape put on h5p_build's source carried the schema's required fields and
additionalProperties false, so an app that holds a call to the schema could refuse a source the
build reads as it is meant (#174), and the build would never say what to write. It now carries
the fields' properties only, on a field that takes any object. Haiku built at the first build in
3 of 3 runs on it, authors written right.
@alekswebnet
alekswebnet merged commit 8d8e61e into main Nov 18, 2026
14 checks passed
@alekswebnet
alekswebnet deleted the feat/mcp-server branch November 18, 2026 11:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

h5p-mcp: a local MCP server that builds, checks and previews packages (step 2 of #219)

1 participant