From e09cb77cf731b0e706ea8982f1c1100720a8f031 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Wed, 4 Nov 2026 16:24:34 +0100 Subject: [PATCH 1/4] fix(agentic-engineering): start the bundled Flux server without KUBECONFIG flux-operator-mcp refuses to start unless KUBECONFIG is set, so the bundled server never connected on a host that relies on ~/.kube/config. Start it through sh, which defaults KUBECONFIG to $HOME/.kube/config only when unset and keeps any value the user set; the command has no ${...} reference, so no client expands it differently. The server still runs --read-only. flux-troubleshooter allowlisted the Flux tools only by the hand-configured server's names. Add the names Claude Code gives the bundled server, mcp__plugin_agentic-engineering_flux-operator-mcp__. Fixes #635 Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 2 +- .github/plugin/marketplace.json | 2 +- docs/resources.md | 2 +- .../agentic-engineering/.claude-plugin/plugin.json | 2 +- plugins/agentic-engineering/.mcp.json | 6 +++--- plugins/agentic-engineering/CHANGELOG.md | 13 +++++++++++++ plugins/agentic-engineering/README.md | 8 ++++++-- .../agents/flux-troubleshooter.agent.md | 11 ++++++++++- plugins/agentic-engineering/plugin.json | 2 +- 9 files changed, 37 insertions(+), 11 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c8e2f0e9..6c94eacd 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -20,7 +20,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, security, Go, Kubernetes, Flux, Talos, frontend and engineering-practice skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "6.8.0", + "version": "6.8.1", "source": "./plugins/agentic-engineering" }, { diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index c8e2f0e9..6c94eacd 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -20,7 +20,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, security, Go, Kubernetes, Flux, Talos, frontend and engineering-practice skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "6.8.0", + "version": "6.8.1", "source": "./plugins/agentic-engineering" }, { diff --git a/docs/resources.md b/docs/resources.md index 579e0f36..671cc48d 100644 --- a/docs/resources.md +++ b/docs/resources.md @@ -39,7 +39,7 @@ A plugin may bundle [MCP](https://modelcontextprotocol.io) servers as well as sk | Server | What it connects to | Needs | |---|---|---| -| `flux-operator-mcp` | A live cluster's Flux resources, read-only (`serve --read-only`), for the `gitops-cluster-debug` skill and the `flux-troubleshooter` agent | The `flux-operator-mcp` binary and cluster access | +| `flux-operator-mcp` | A live cluster's Flux resources, read-only (`serve --read-only`), for the `gitops-cluster-debug` skill and the `flux-troubleshooter` agent | The `flux-operator-mcp` binary, a POSIX `sh`, and cluster access through `KUBECONFIG` (default `~/.kube/config`) | | `github-ghas-tools` | GitHub's security tools, read-only (`X-MCP-Readonly`): alerts, advisories and dependency vulnerability lookups | A GitHub sign-in; see below | | `siderolabs-docs` | Sidero Labs' search of the Talos Linux and Omni documentation | Nothing; it is public | diff --git a/plugins/agentic-engineering/.claude-plugin/plugin.json b/plugins/agentic-engineering/.claude-plugin/plugin.json index 43f04f4a..2f2a33dc 100644 --- a/plugins/agentic-engineering/.claude-plugin/plugin.json +++ b/plugins/agentic-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, security, Go, Kubernetes, Flux, Talos, frontend and engineering-practice skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "6.8.0", + "version": "6.8.1", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/agentic-engineering/.mcp.json b/plugins/agentic-engineering/.mcp.json index 587be24a..435dd414 100644 --- a/plugins/agentic-engineering/.mcp.json +++ b/plugins/agentic-engineering/.mcp.json @@ -1,10 +1,10 @@ { "mcpServers": { "flux-operator-mcp": { - "command": "flux-operator-mcp", + "command": "sh", "args": [ - "serve", - "--read-only" + "-c", + "[ -n \"$KUBECONFIG\" ] || KUBECONFIG=\"$HOME/.kube/config\"; export KUBECONFIG; exec flux-operator-mcp serve --read-only" ] }, "github-ghas-tools": { diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index 172fb4d1..e0775106 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog — `agentic-engineering` +## 6.8.1 — 2026-11-04 + +**Fixed** — the bundled Flux tooling now works out of the box: + +- `flux-operator-mcp` refuses to start without a `KUBECONFIG` environment variable, so on a host + that relies on the default `~/.kube/config` it never connected. The plugin now starts it through + `sh`, which sets `KUBECONFIG` to `$HOME/.kube/config` only when it is unset and keeps any value + you set, including a list of paths. The server still runs `--read-only`. It needs a POSIX `sh`. +- `flux-troubleshooter` allowlisted the Flux tools only as `mcp__flux-operator-mcp__`, which + matches a server you configured by hand, not the one this plugin bundles, which Claude Code names + `mcp__plugin_agentic-engineering_flux-operator-mcp__`. It now lists both + ([#635](https://github.com/devantler-tech/agent-plugins/issues/635)). + ## 6.8.0 — 2026-11-04 **Added** — everything the agents need, in this one plugin diff --git a/plugins/agentic-engineering/README.md b/plugins/agentic-engineering/README.md index 7639f53d..8f134559 100644 --- a/plugins/agentic-engineering/README.md +++ b/plugins/agentic-engineering/README.md @@ -123,13 +123,17 @@ recorded in [`resources/THIRD-PARTY-NOTICES.md`](resources/THIRD-PARTY-NOTICES.m | Server | What it connects to | Needs | |---|---|---| -| `flux-operator-mcp` | A live cluster's Flux resources, read-only, for `gitops-cluster-debug` and `flux-troubleshooter` | The [`flux-operator-mcp`](https://fluxcd.control-plane.io/operator/mcp/) binary and cluster access | +| `flux-operator-mcp` | A live cluster's Flux resources, read-only, for `gitops-cluster-debug` and `flux-troubleshooter` | The [`flux-operator-mcp`](https://fluxcd.control-plane.io/operator/mcp/) binary, a POSIX `sh`, and cluster access through `KUBECONFIG` or `~/.kube/config` | | `github-ghas-tools` | GitHub's read-only security tools | A GitHub sign-in, below | | `siderolabs-docs` | Sidero Labs' search of the Talos Linux and Omni documentation | Nothing; it is public | A local server whose binary is missing reports a failed connection and leaves the rest working. The Flux server starts with `--read-only`, so it can read, trace and diff but never apply, delete, -reconcile, suspend or resume; hand fixes to your GitOps delivery instead. `siderolabs-docs` also +reconcile, suspend or resume; hand fixes to your GitOps delivery instead. `flux-operator-mcp` +refuses to start unless the `KUBECONFIG` environment variable is set, so the plugin starts it +through `sh`, which sets `KUBECONFIG` to `$HOME/.kube/config` when your environment leaves it +unset and passes any value you set unchanged. It reads whichever cluster that kubeconfig's current +context names. `siderolabs-docs` also offers `submit_feedback`, which sends a report to Sidero Labs; it is the only tool among these servers that writes anywhere, so deny it in your tool permissions if your agents must not contact third parties. diff --git a/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md b/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md index af78cfb7..3ea69de6 100644 --- a/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md +++ b/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md @@ -12,7 +12,11 @@ description: >- # Every tool is listed in BOTH spellings on purpose: Claude Code names the built-ins # Read/Grep/Glob and allowlists MCP tools as mcp____, while VS Code / # Copilot CLI use lower-case built-in identifiers (read, search) and / -# for MCP. Each loader tolerates allowlist entries it does not recognise (Claude Code +# for MCP. Claude Code names the tools of a server a plugin bundles +# mcp__plugin____, so the bundled server needs the +# mcp__plugin_agentic-engineering_flux-operator-mcp__ entries; the plain mcp__ entries +# keep serving a server the user configured by hand (#635). Each loader tolerates +# allowlist entries it does not recognise (Claude Code # fails only if NO entry resolves) — so one file serves all three surfaces, and # dropping either spelling would leave the agent unable to read or search the # repository on the surface that uses it. The YAML LIST form is what the VS Code / @@ -25,6 +29,11 @@ tools: - Glob - read - search + - mcp__plugin_agentic-engineering_flux-operator-mcp__get_flux_instance + - mcp__plugin_agentic-engineering_flux-operator-mcp__get_kubeconfig_contexts + - mcp__plugin_agentic-engineering_flux-operator-mcp__get_kubernetes_api_versions + - mcp__plugin_agentic-engineering_flux-operator-mcp__get_kubernetes_resources + - mcp__plugin_agentic-engineering_flux-operator-mcp__get_kubernetes_logs - mcp__flux-operator-mcp__get_flux_instance - mcp__flux-operator-mcp__get_kubeconfig_contexts - mcp__flux-operator-mcp__get_kubernetes_api_versions diff --git a/plugins/agentic-engineering/plugin.json b/plugins/agentic-engineering/plugin.json index 43f04f4a..2f2a33dc 100644 --- a/plugins/agentic-engineering/plugin.json +++ b/plugins/agentic-engineering/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, security, Go, Kubernetes, Flux, Talos, frontend and engineering-practice skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "6.8.0", + "version": "6.8.1", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" From 7d728d444e03f3fb3ebd56fbd15ba26a300e4c3e Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Wed, 4 Nov 2026 16:45:10 +0100 Subject: [PATCH 2/4] docs(agentic-engineering): say an empty KUBECONFIG also gets the default The wrapper treats an empty KUBECONFIG like an unset one; the README and the 6.8.1 changelog now say so. Co-Authored-By: Claude Opus 5.5 --- plugins/agentic-engineering/CHANGELOG.md | 4 ++-- plugins/agentic-engineering/README.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index e0775106..9280fec2 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -6,8 +6,8 @@ - `flux-operator-mcp` refuses to start without a `KUBECONFIG` environment variable, so on a host that relies on the default `~/.kube/config` it never connected. The plugin now starts it through - `sh`, which sets `KUBECONFIG` to `$HOME/.kube/config` only when it is unset and keeps any value - you set, including a list of paths. The server still runs `--read-only`. It needs a POSIX `sh`. + `sh`, which sets `KUBECONFIG` to `$HOME/.kube/config` only when it is unset or empty and keeps + any non-empty value, including a list of paths. The server still runs `--read-only`. It needs a POSIX `sh`. - `flux-troubleshooter` allowlisted the Flux tools only as `mcp__flux-operator-mcp__`, which matches a server you configured by hand, not the one this plugin bundles, which Claude Code names `mcp__plugin_agentic-engineering_flux-operator-mcp__`. It now lists both diff --git a/plugins/agentic-engineering/README.md b/plugins/agentic-engineering/README.md index 8f134559..8bf795ca 100644 --- a/plugins/agentic-engineering/README.md +++ b/plugins/agentic-engineering/README.md @@ -132,7 +132,7 @@ The Flux server starts with `--read-only`, so it can read, trace and diff but ne reconcile, suspend or resume; hand fixes to your GitOps delivery instead. `flux-operator-mcp` refuses to start unless the `KUBECONFIG` environment variable is set, so the plugin starts it through `sh`, which sets `KUBECONFIG` to `$HOME/.kube/config` when your environment leaves it -unset and passes any value you set unchanged. It reads whichever cluster that kubeconfig's current +unset or empty and passes any non-empty value unchanged. It reads whichever cluster that kubeconfig's current context names. `siderolabs-docs` also offers `submit_feedback`, which sends a report to Sidero Labs; it is the only tool among these servers that writes anywhere, so deny it in your tool permissions if your agents must not contact From fcd0c84d35d032ff5523a6e1cd1f4e5685a0796b Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Wed, 4 Nov 2026 17:34:11 +0100 Subject: [PATCH 3/4] docs(agentic-engineering): state the Flux server's full read reach Address the local review of #636: - The read-only server can switch to and read every context in the kubeconfig, not only the current one, and now connects in every session that loads the plugin. Say so in the README and the 6.8.1 changelog, with how to narrow it. - Exit with a message when neither KUBECONFIG nor HOME is set, instead of defaulting to /.kube/config. - Name the Windows-without-sh regression, give the hand-written VS Code example KUBECONFIG and --read-only, and describe the allowlist's three spellings. Co-Authored-By: Claude Opus 5.5 --- docs/resources.md | 20 +++++++++++++------ plugins/agentic-engineering/.mcp.json | 2 +- plugins/agentic-engineering/CHANGELOG.md | 10 +++++++++- plugins/agentic-engineering/README.md | 8 ++++++-- .../agents/flux-troubleshooter.agent.md | 2 +- 5 files changed, 31 insertions(+), 11 deletions(-) diff --git a/docs/resources.md b/docs/resources.md index 671cc48d..ff75c810 100644 --- a/docs/resources.md +++ b/docs/resources.md @@ -59,15 +59,22 @@ server to your workspace `.vscode/mcp.json` (note the key there is `servers`, no ```json { "servers": { - "flux-operator-mcp": { "command": "flux-operator-mcp", "args": ["serve"] } + "flux-operator-mcp": { + "command": "flux-operator-mcp", + "args": ["serve", "--read-only"], + "env": { "KUBECONFIG": "${env:HOME}/.kube/config" } + } } } ``` Every path invokes the same `flux-operator-mcp` binary, so install it first — e.g. `brew install controlplaneio-fluxcd/tap/flux-operator-mcp` or `go install -github.com/controlplaneio-fluxcd/flux-operator/cmd/mcp@latest` (it reads your kubeconfig from -`KUBECONFIG` / `~/.kube/config`). See the +github.com/controlplaneio-fluxcd/flux-operator/cmd/mcp@latest`. It refuses to start unless the +`KUBECONFIG` environment variable is set, which is why the hand-written entry sets it; the bundled +plugin's `sh` wrapper sets it to `$HOME/.kube/config` when it is unset or empty. It can read every +context in that kubeconfig, starting at the current one, because its read-only +`set_kubeconfig_context` tool switches between them. See the [Flux MCP docs](https://fluxcd.control-plane.io/operator/mcp/) for read-only mode and remote transport. @@ -91,9 +98,10 @@ The agent is authored once as `agents/.agent.md` (Markdown + YAML frontmat `name`/`description`/`tools`/`model` core). The `.agent.md` filename is what VS Code and Copilot discover inside a plugin's `agents/` directory; Claude Code is filename-agnostic (it reads any Markdown in `agents/` and takes the agent's name from frontmatter), so one file serves all three -tools. The same goes for the `tools:` allowlist: MCP tools are listed in both spellings — Claude -Code's `mcp____` and VS Code / Copilot's `/` — because each tool -ignores entries it does not recognise (per +tools. The same goes for the `tools:` allowlist: MCP tools are listed in three spellings — Claude +Code's `mcp__plugin____` for the server this plugin bundles, its +`mcp____` for a server you configure by hand, and VS Code / Copilot's +`/` — because each tool ignores entries it does not recognise (per [ADR 0001](../docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)): - **Claude Code**, **Copilot CLI**, and **VS Code** — the bundled `agents/` directory is loaded diff --git a/plugins/agentic-engineering/.mcp.json b/plugins/agentic-engineering/.mcp.json index 435dd414..e8c4b60b 100644 --- a/plugins/agentic-engineering/.mcp.json +++ b/plugins/agentic-engineering/.mcp.json @@ -4,7 +4,7 @@ "command": "sh", "args": [ "-c", - "[ -n \"$KUBECONFIG\" ] || KUBECONFIG=\"$HOME/.kube/config\"; export KUBECONFIG; exec flux-operator-mcp serve --read-only" + "[ -n \"$KUBECONFIG\" ] || { [ -n \"$HOME\" ] || { echo 'flux-operator-mcp: set KUBECONFIG or HOME' >&2; exit 1; }; KUBECONFIG=\"$HOME/.kube/config\"; }; export KUBECONFIG; exec flux-operator-mcp serve --read-only" ] }, "github-ghas-tools": { diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index 9280fec2..98f1880a 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -7,7 +7,15 @@ - `flux-operator-mcp` refuses to start without a `KUBECONFIG` environment variable, so on a host that relies on the default `~/.kube/config` it never connected. The plugin now starts it through `sh`, which sets `KUBECONFIG` to `$HOME/.kube/config` only when it is unset or empty and keeps - any non-empty value, including a list of paths. The server still runs `--read-only`. It needs a POSIX `sh`. + any non-empty value, including a list of paths. With neither `KUBECONFIG` nor `HOME` set it + exits with a message. The server still runs `--read-only`. +- **This widens what such a host's sessions can read.** Where the server used to fail to start, + every session that loads the plugin, unattended runs included, can now read every cluster in + `~/.kube/config`: the read-only `set_kubeconfig_context` tool switches between its contexts, and + workload logs are readable (Secret values are masked by default). To narrow it, set `KUBECONFIG` + to a file holding only the contexts the agents may read, or deny or disable the server. +- **Windows regression:** the server now needs a POSIX `sh` on `PATH`. A Windows host without one, + which could start the server before when `KUBECONFIG` was set, no longer can. - `flux-troubleshooter` allowlisted the Flux tools only as `mcp__flux-operator-mcp__`, which matches a server you configured by hand, not the one this plugin bundles, which Claude Code names `mcp__plugin_agentic-engineering_flux-operator-mcp__`. It now lists both diff --git a/plugins/agentic-engineering/README.md b/plugins/agentic-engineering/README.md index 8bf795ca..2e25e5bc 100644 --- a/plugins/agentic-engineering/README.md +++ b/plugins/agentic-engineering/README.md @@ -132,8 +132,12 @@ The Flux server starts with `--read-only`, so it can read, trace and diff but ne reconcile, suspend or resume; hand fixes to your GitOps delivery instead. `flux-operator-mcp` refuses to start unless the `KUBECONFIG` environment variable is set, so the plugin starts it through `sh`, which sets `KUBECONFIG` to `$HOME/.kube/config` when your environment leaves it -unset or empty and passes any non-empty value unchanged. It reads whichever cluster that kubeconfig's current -context names. `siderolabs-docs` also +unset or empty and passes any non-empty value unchanged. It can read every cluster in that +kubeconfig, not only the current context: its read-only `set_kubeconfig_context` tool switches +between them, and it can read workload logs (Secret values are masked by default). Every session +that loads this plugin gets that read access, including unattended runs. To narrow it, point +`KUBECONFIG` at a file holding only the contexts the agents may read, or deny or disable the +server in your tool permissions. `siderolabs-docs` also offers `submit_feedback`, which sends a report to Sidero Labs; it is the only tool among these servers that writes anywhere, so deny it in your tool permissions if your agents must not contact third parties. diff --git a/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md b/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md index 3ea69de6..e8b4d8f8 100644 --- a/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md +++ b/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md @@ -9,7 +9,7 @@ description: >- against the Git manifests, and returns a structured diagnosis plus the exact human-applied fix. It never applies, reconciles, suspends, resumes, or deletes — hand any remediation back to the caller. -# Every tool is listed in BOTH spellings on purpose: Claude Code names the built-ins +# Every tool is listed in each surface's spelling on purpose: Claude Code names the built-ins # Read/Grep/Glob and allowlists MCP tools as mcp____, while VS Code / # Copilot CLI use lower-case built-in identifiers (read, search) and / # for MCP. Claude Code names the tools of a server a plugin bundles From 1ae7c7473d2f91936a3922aa27ed4374b49c0d70 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Wed, 4 Nov 2026 17:36:46 +0100 Subject: [PATCH 4/4] docs: use VS Code's cross-platform home variable in the Flux example ${env:HOME} is normally empty in VS Code on Windows; ${userHome} works on every platform. Co-Authored-By: Claude Opus 5.5 --- docs/resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources.md b/docs/resources.md index ff75c810..d6492a30 100644 --- a/docs/resources.md +++ b/docs/resources.md @@ -62,7 +62,7 @@ server to your workspace `.vscode/mcp.json` (note the key there is `servers`, no "flux-operator-mcp": { "command": "flux-operator-mcp", "args": ["serve", "--read-only"], - "env": { "KUBECONFIG": "${env:HOME}/.kube/config" } + "env": { "KUBECONFIG": "${userHome}/.kube/config" } } } }