Skip to content

Package the MCP server as a plugin - #10

Merged
afternoon merged 3 commits into
mainfrom
worktree-mcp-plugin
Sep 1, 2026
Merged

afternoon merged 3 commits into
mainfrom
worktree-mcp-plugin

Conversation

@afternoon

Copy link
Copy Markdown
Owner

Packages /api/mcp as an installable Claude Code plugin, so connecting is
/plugin marketplace add afternoon/htmlcsspdf rather than a URL somebody has to
know and type into claude mcp add.

What's here

.claude-plugin/marketplace.json          makes the repo installable
plugins/htmlcsspdf/
  .claude-plugin/plugin.json             name, version, homepage
  .mcp.json                              type: http, and the URL
  skills/writing-documents/SKILL.md      how to write a document that renders
  README.md                              install, and what the plugin is for

No credentials in the config

.mcp.json is four lines: type: "http" and the production URL. The endpoint
answers an unauthenticated call with an RFC 9728 WWW-Authenticate challenge
advertising documents:read documents:write, and the client discovers
registration, consent and token exchange from there — so a config carrying a
client id would be describing a handshake that already works without one.
Verified against production; the challenge is live and names both scopes.

The skill is the part worth having

Two facts decide whether a document comes out right and neither fits in a tool
description:

  • Page setup is an @page rule and nothing else. A stylesheet without one
    gets the renderer's default rather than the page you meant.
  • Saving runs an element allowlist. It drops rather than escapes, and it has
    no <svg> — so a document that draws its logo in markup saves without it and
    nothing says why. The full element and attribute lists are written down, along
    with the allowed URL schemes.

It also records that update_document replaces both panes, so an edit needs a
get_document first, and that rendering is deliberately not a tool.

Checks

  • claude plugin validate passes on both the plugin and the marketplace
  • Loads in a real session via --plugin-dir; the skill registers as
    htmlcsspdf:writing-documents
  • Production POST /api/mcp returns the expected 401 challenge

No application code is touched — this is additive packaging only.

🤖 Generated with Claude Code

The endpoint has been reachable by `claude mcp add` for a while, but that is a
URL somebody has to know and type. A plugin makes it installable, and gives the
tools somewhere to carry the things their descriptions cannot.

`plugins/htmlcsspdf/.mcp.json` is the whole of the connection: `type: "http"`
and the URL. No key, no client id, nothing to fill in — the endpoint answers an
unauthenticated call with an RFC 9728 challenge and the client discovers the
rest from there, so a config that carried credentials would be describing a
handshake that already works without them.

The bundled skill is the part worth having. Two facts decide whether a document
comes out right, and neither fits in a tool description: page size and margins
come from an `@page` rule and nowhere else, and saving runs an element
allowlist. The allowlist is the one that bites — it drops rather than escapes,
and it has no `<svg>`, so a document that draws its logo in markup saves
without it and nothing says why. Both are written down, along with the fact
that `update_document` replaces both panes and needs a read first.

`.claude-plugin/marketplace.json` makes it installable from this repo, so
`/plugin marketplace add afternoon/htmlcsspdf` is the whole of the setup.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 1, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
htmlcsspdf 1a14653 Commit Preview URL

Branch Preview URL
Sep 01 2026, 10:15 AM

afternoon and others added 2 commits September 1, 2026 11:06
The plugin existed but the README did not mention it, so the documented way to
connect an agent was still to read the MCP section and work out a URL. The
install goes above Running, because connecting an agent to the deployed app is
not the same errand as building the thing locally, and most people wanting the
former never need the latter.

It says what there is to configure — nothing — since a reader who has met other
MCP servers will go looking for the API key that this one does not have. The
MCP section links back to it, so the protocol detail and the packaged path are
reachable from each other.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The install section covered Claude Code and stopped there, which reads as
though a plugin were the only way in. It is not: a plugin is a Claude Code
packaging format, and what it wraps is an ordinary remote MCP endpoint that
claude.ai can be pointed at directly.

The instruction is to paste the URL and leave the credentials blank, which is
worth saying rather than implying — someone who has added other connectors will
go looking for the client id this one does not need. That it works at all is a
property of the server: registration is open and the token endpoint accepts
`none`, so Claude can register itself as a public client and consent stays the
boundary. Verified against production with an `https://claude.ai/...` callback.

Two things do not carry over, so both are stated. The skill is part of the
plugin, not the endpoint, so a connector gets the six tools and none of the
guidance about `@page` and the allowlist. And a connector must be https on a
public hostname, so the loopback trick above is Claude Code's alone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@afternoon
afternoon marked this pull request as ready for review September 1, 2026 20:48
@afternoon
afternoon merged commit b83b4c0 into main Sep 1, 2026
2 checks passed
@afternoon
afternoon deleted the worktree-mcp-plugin branch September 1, 2026 21:03
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.

1 participant