From 43987c623b1cd9471bc2917f2102fffadc3e5d9b Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 31 May 2026 20:16:57 +0200 Subject: [PATCH] docs: record MCP-server-bundling decision (skills only) via ADR-0001 Resolves the open MCP-broadening question from #7: the marketplace stays a thin, single-source bundler of agent skills and does not bundle or manage MCP servers. MCP servers are product runtime interfaces (e.g. ksail's is part of the ksail binary; Flux's is upstream) with a different lifecycle and source, and plugin-level MCP bundling is not portable across all three hosts via the two parity-checked manifests. Skills that need a server declare it in their own SKILL.md. Records the decision as a MADR ADR (docs/adr/0001) and reflects the scope in AGENTS.md (new Scope section + rescope task-menu) and README (Scope section). Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 18 +++++- README.md | 4 ++ docs/adr/0001-mcp-server-bundling.md | 92 ++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+), 3 deletions(-) create mode 100644 docs/adr/0001-mcp-server-bundling.md diff --git a/AGENTS.md b/AGENTS.md index 3755aad..0c3c714 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,6 +61,17 @@ metadata.** Never hand-edit a bundled `SKILL.md` to diverge from its upstream; f `devantler-tech/skills` and let the update workflow pull it through. Only the marketplace structure (manifests, `plugin.json`, plugin membership) is authored here. +## Scope — skills only (MCP servers are out of scope) + +The marketplace bundles **agent skills and nothing else.** It does **not** bundle, ship, or manage +**MCP servers** — those are product runtime interfaces with their own release cadence and live with +the product that ships them (e.g. ksail's MCP server is part of the ksail binary; the Flux MCP server +is an upstream `fluxcd` artifact). A skill that *needs* an MCP server declares that dependency in its +own `SKILL.md`; the user installs the server from the product's own channel. This keeps the repo a +thin, single-source, tool-neutral skill bundler with the two manifests in parity. The full rationale +and the revisit triggers are recorded in [ADR-0001](docs/adr/0001-mcp-server-bundling.md) +(resolves the MCP question from [#7](https://github.com/devantler-tech/plugins/issues/7)). + ## Conventions 1. **Two manifests in parity.** Every plugin appears in **both** `marketplace.json` files with the same @@ -147,9 +158,10 @@ are the gate. Never weaken a security control or a check to pass. - **Keep bundled skills fresh:** let the daily `update-agent-skills` PR flow through; fix it when CI fails. Never hand-edit a bundled `SKILL.md` to diverge from its upstream — fix it in `devantler-tech/skills`. -- **Tool-neutral rescope** ([#7](https://github.com/devantler-tech/plugins/issues/7)): de-Copilot-brand - remaining surface; keep manifests/README cross-tool; evaluate broadening to additional standards - (e.g. MCP) and record the decision as an ADR if non-trivial. +- **Tool-neutral rescope** ([#7](https://github.com/devantler-tech/plugins/issues/7)): keep the + remaining surface de-Copilot-branded and manifests/README cross-tool. The MCP-broadening question is + **decided** — skills only, MCP out of scope ([ADR-0001](docs/adr/0001-mcp-server-bundling.md)); honour + that scope and only reopen it against the ADR's revisit triggers. - **Workflow & action hygiene:** keep third-party actions pinned & aligned with the sibling CI repos; bundle Dependabot `github_actions` PRs; flag majors; keep CI `actionlint`-clean. - **Consistency** with [devantler-tech/skills](https://github.com/devantler-tech/skills) (the single diff --git a/README.md b/README.md index 0d96c44..f76d74b 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,10 @@ Each plugin directory is self-contained with a `plugin.json` manifest and a `ski See [`devantler-tech/skills`](https://github.com/devantler-tech/skills) for the curated skill index and upstream links. +## Scope + +This marketplace bundles **agent skills only**. It does not bundle or manage **MCP servers** — those ship with the product that provides them (e.g. ksail's MCP server is part of the ksail binary), and a skill that needs one declares that dependency in its own `SKILL.md`. See [ADR-0001](docs/adr/0001-mcp-server-bundling.md) for the rationale and revisit triggers. + ## Contributing See the [devantler-tech organisation guidelines](https://github.com/devantler-tech/.github) for PR/issue templates and contribution rules. diff --git a/docs/adr/0001-mcp-server-bundling.md b/docs/adr/0001-mcp-server-bundling.md new file mode 100644 index 0000000..ef832a4 --- /dev/null +++ b/docs/adr/0001-mcp-server-bundling.md @@ -0,0 +1,92 @@ +> 🤖 Generated by the Daily AI Assistant + +# ADR-0001: The marketplace bundles skills only — MCP servers are out of scope + +- Status: accepted +- Date: 2026-05-31 +- Deciders: devantler-tech maintainer (gate), Daily AI Assistant (proposal) +- Tracking: [#7 — Rescope from Copilot-branded to a tool-neutral marketplace](https://github.com/devantler-tech/plugins/issues/7) + +## Context and problem statement + +`devantler-tech/plugins` is a tool-neutral **agent-plugin marketplace** that bundles the curated +agent skills from [`devantler-tech/skills`](https://github.com/devantler-tech/skills) into +category-based plugins, offered identically to **VS Code**, **GitHub Copilot CLI**, and **Claude +Code** via two parity-checked manifests. + +The tool-neutral rescope ([#7](https://github.com/devantler-tech/plugins/issues/7)) asks us to decide +whether the marketplace should broaden beyond skills to additional cross-tool standards — most +notably the **Model Context Protocol (MCP)**, the emerging standard for exposing tools/resources to +agents — by **bundling MCP servers** alongside skill bundles. + +This ADR records that decision. + +## Decision drivers + +- **Single source of truth.** The marketplace's entire content derives from `devantler-tech/skills` + via `gh skill install`, with upstream provenance in each `SKILL.md`'s `metadata.github-*` + frontmatter and *no lockfile* — a deliberately thin, additive bundler (see `AGENTS.md` → *Skills + come from upstream*). +- **Tool-neutrality / manifest parity.** A cross-tool install must offer the *same* thing to every + host; CI diffs the two manifests and fails on drift. Anything bundled must be expressible + identically across VS Code, Copilot CLI, and Claude Code. +- **Artifact lifecycle.** A skill is a static, version-pinned Markdown document. An MCP server is a + running process/binary with its own release cadence, transport, auth, and runtime configuration. +- **Where devantler-tech's MCP servers actually live.** They ship *with their product*: the **ksail** + MCP server is part of the ksail binary (released and versioned with ksail); the **Flux** MCP server + is an upstream `fluxcd` artifact. Neither originates in `devantler-tech/skills`. + +## Considered options + +1. **Skills only (status quo).** Keep the marketplace a thin bundler of skills; MCP servers stay out + of scope. Skills that require a server declare that dependency in their own `SKILL.md`. +2. **Bundle MCP servers in the marketplace** alongside skills (e.g. an `.mcp.json` per plugin). +3. **A separate MCP registry repo** under devantler-tech, distinct from this skills marketplace. + +## Decision + +**Chosen: Option 1 — skills only. The marketplace does not bundle, ship, or manage MCP servers.** + +A skill that depends on an MCP server (e.g. the GitOps skills expect the Flux MCP server; the ksail +skill expects the ksail MCP server) **declares that dependency in its own `SKILL.md`**, and the user +installs the server from the product's own channel. The marketplace remains a pure skill bundler. + +## Rationale + +- **Keeps the single-source-of-truth invariant intact.** MCP servers are not skills and do not live + in `devantler-tech/skills`. Bundling them would require a second, differently-shaped source and a + way to pin/update it — breaking the "thin, additive bundler over `devantler-tech/skills`, no + lockfile" contract that makes this repo simple and the daily `update-agent-skills` flow sufficient. +- **Preserves tool-neutrality.** Plugin-level MCP bundling is **not** uniformly available across the + three hosts through the *agent-plugin marketplace manifest*: Claude Code plugins can declare an + `.mcp.json`, but VS Code and Copilot CLI configure MCP servers through their own separate + mechanisms, not this marketplace. Bundling MCP would be portable to at most one host and would break + manifest parity (a cross-tool install could no longer offer the same thing to every tool). +- **Respects artifact boundaries.** An MCP server's lifecycle (binary releases, runtime config, auth) + belongs with the product that ships it, not coupled into a curated documentation bundle on a + different cadence. +- **The skill layer is the correct seam.** Skills already express "I need server X" in their own docs; + that keeps the *what-to-install* with the *what-uses-it*, while the marketplace stays a clean catalogue. + +## Consequences + +- **Positive.** The repo stays a simple, portable, single-source skill bundler; manifest parity and + the no-lockfile model are preserved; no new release/runtime surface to maintain. +- **Negative / trade-off.** Users who want a devantler-tech MCP server install it separately from its + product; the marketplace does not one-shot install "skill + its server". This is acceptable because + the servers are few and product-bound today. +- **Reversibility.** This is a scope decision, not a code lock-in — it can be revisited cheaply. + +## Revisit when + +Reconsider (superseding ADR) once **all** of the following hold: + +1. devantler-tech ships a **standalone, product-independent** MCP server worth distributing on its own + (not bundled into a single product binary), **and** +2. the agent-plugin marketplace spec gains a **common, cross-tool** way to declare bundled MCP servers + so two-manifest parity is preservable across VS Code, Copilot CLI, and Claude Code, **and** +3. there is demonstrated user demand for one-shot "skill + server" install from this marketplace. + +Until then, the marketplace is **skills only**, and a separate MCP registry (Option 3) — not bundling +into this skills marketplace (Option 2) — would be the first structure to evaluate if (1) alone +materialises.