RFC: Plugin lifecycle management in ToolHive

[JAORMX]

Summary

Proposes adding plugin lifecycle management to ToolHive, mirroring the existing skills system (RFC-0030). A plugin is the cross-vendor "bundle of primitives" unit (slash commands, subagents, Agent Skills, hooks, MCP server configs, LSP servers) declared by .claude-plugin/plugin.json.

ToolHive will let users build a plugin directory into a reproducible OCI artifact, push it to any OCI registry, install it (from registry name / OCI ref / git://), and list/info/uninstall it — reusing the registry, OCI, groups, and SQLite entries infrastructure that already serves skills. As a bridge to native client tooling, it can also generate a marketplace.json.

Why

• Plugins are the industry-convergent bundle unit (Claude Code, Cursor, Codex, Copilot, Gemini, Kiro), but no one packages a multi-primitive plugin bundle as an immutable, content-addressable, signable OCI artifact — an open niche ToolHive is positioned to fill.
• The skills system was deliberately built on a generic foundation (entry_type discriminator, x/dev.toolhive/<type> registry namespace, shared OCI primitives) that anticipates exactly this extension.

What's genuinely new vs. skills

1. Install target — plugins normally need marketplace-cache + settings.json mutation. The RFC recommends the in-place skills-directory-plugin mechanism for v1 (pure filesystem, no settings mutation), with marketplace-cache deferred as a per-client PathResolver strategy. (Open Question Port THV-0597 #1)
2. Executable surface — unlike inert skills, plugins bundle hooks and MCP servers (code). The security section centers on this: a pre-install executable-surface inventory in thv plugin info, --require-signature via cosign + the OCI Referrers API, and install-time audit events.

Notes for reviewers

• File is named THV-XXXX-... per the RFC convention; will rename to match this PR number.
• Touches toolhive (primary), toolhive-core (new oci/plugins + shared-primitive refactor), and toolhive-registry-server (plugin catalog).
• Key product decisions to weigh: Open Question Port THV-0597 #1 (install target) and Port THV-1566 #4 (running bundled MCP servers through thv with isolation as the v2 headline).

🤖 Generated with Claude Code

[JAORMX]

So I went and did the cross-client research to sanity-check this (Claude Code, Cursor, Codex, Copilot, Gemini, Kiro, Continue, Goose, Zed, OpenCode, plus MCPB / Agent Skills / the OCI side). Two things came out of it: the factual claims mostly hold up, and a bigger structural problem that I think we got backwards. The structural one first, because it matters more.

This RFC is written through the skills lens: distribute an artifact, place the files where the client loads them, done. That works for skills because a skill is inert Markdown with no runtime. But a plugin isn't inert. Its .mcp.json is a set of MCP servers, and MCP servers are exactly the thing ToolHive exists to run... in a container, behind the proxy, with a permission profile, network isolation, secrets and audit.

So if we "install" a plugin by dropping its .mcp.json into the client's load path (skills-dir, marketplace cache, whatever materialization we land on), the client spawns those servers itself, unsandboxed, and we've bypassed the entire reason ToolHive exists. That's the opposite of what we want.

Right now the RFC files "managed MCP servers from plugins" under Non-Goals and Open Question #4, as a forward-looking v2 thing. I think that's inverted. For ToolHive specifically, running the bundled MCP servers through the runtime is the v1 thesis. It's the only part of a plugin install that a git clone + native install doesn't already give you. Everything else (commands, agents, skills, hooks-as-files) is supporting cast.

Concrete recommendation, and to be clear up front: this is an install-time thing, not a packaging one. The OCI artifact stays exactly what the RFC already says, one opaque, verbatim, single-layer, signable tree. I'm not touching that, and per-primitive layers (Alternative 2) are still the wrong call for v1. What changes is materialization: instead of placing the whole tree verbatim into the client's load path, treat components differently by their nature.

• Inert components (commands, agents, skills, hooks, LSP config): materialize into the client's load path as-is. The skills model genuinely fits here, and this is where the placement-mechanism choice lives... which is honestly the low-stakes half.
• MCP servers (.mcp.json): don't hand the raw spawn config to the client. Register each as a ToolHive workload, then rewrite the materialized client config to point at our proxy URL, exactly like pkg/client/converter.go already does for every other MCP server. The plugin's .mcp.json becomes a source of workload definitions, nothing more.

One honest consequence: this breaks the RFC's "byte-identical to a native install" compatibility goal, but only for .mcp.json. The inert components stay byte-identical to what you packaged; the MCP entries deliberately get rewritten to route through ToolHive. That's the whole point, so we should call it out as an intentional trade rather than pretend the install is a verbatim copy.

The genuinely hard v1 question, and the one the RFC should center on, is the gap between how plugins define servers and how we run them. Plugins use local command/args (node ${CLAUDE_PLUGIN_ROOT}/mcp/index.js). ToolHive runs containerized/remote workloads. So: do we run it as a proxied stdio local-process workload (middleware and audit, but weaker isolation)? Repackage into a container at build time? Offer both with a per-server policy? Plus the secrets angle (userConfig sensitive fields feeding the workload) and what default permission profile an untrusted bundled server gets.

On the materialization mechanism for the inert half: I'd drop the in-place skills-directory approach entirely. It's a discovery side-door meant for authoring (claude plugin init), it produces name@skills-dir rather than managed installs, it overlaps the skills directory, and project scope degrades in confusing ways (monitors don't load, no walk-up to the repo root, MCP needs per-server approval).

Go native instead. And the cleanest way to do that without standing up a daemon: we're already pulling and extracting the OCI artifact, so stage the bundle to a local ToolHive-managed dir and register that dir as a local-path marketplace source for the client. No URL server to keep alive, works offline, and we still own the supply chain because we verify the digest/signature before staging. The client then installs from the local path through its own native lifecycle (cache + enable). The "that's a lot of client state to own" worry doesn't really apply... registration + enabledPlugins is the same class of thing we already write for MCP servers and skills.

And note the bundle we stage isn't the raw one. The .mcp.json has already been rewritten to point at our proxy URLs (per the split above), so what the client's marketplace installs is the inert components plus MCP entries that route back through ToolHive. The local-path staging and the workload-registration aren't two separate features, they're the same install doing both halves.

Smaller factual fixes from the research, all verified against current docs:

• Copilot's manifest path is .github/plugin/plugin.json (nested under plugin/), not .github/plugin.json. It's repeated in a few spots.
• The Codex fallback to .claude-plugin/plugin.json is real, but only in the source (codex-rs/utils/plugins/src/plugin_namespace.rs), not the prose docs. Worth citing the code, otherwise a reviewer checking docs alone will mark it unverifiable.
• cagent packages agents (it can bundle multi-agent teams), not "single agents"; the official MCP Registry points at npm/PyPI/MCPB/OCI, not just container images.
• "distributed exclusively through Git/GitHub" misses npm as a native source type. The OCI-absence point still stands though, and it held up under a hard counterexample hunt: the MCP "Skills Over MCP" charter itself lists bundle-as-a-single-OCI-artifact as out of scope / not yet built.
• Tekton doesn't key layers with org.opencontainers.image.title, that's Conftest. Tekton uses dev.tekton.image.{name,kind,apiVersion}.

The central differentiation claim (nobody packages a multi-primitive bundle as a signed OCI artifact) is solid, for what it's worth.

Happy to restructure the RFC around the bundle-decomposition thesis if we agree on it. That's a bigger rewrite than the factual patches, so flagging it before I touch anything.