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..d6492a30 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 | @@ -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": "${userHome}/.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/.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..e8c4b60b 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\" ] || { [ -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 172fb4d1..98f1880a 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -1,5 +1,26 @@ # 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 or empty and keeps + 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 + ([#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..2e25e5bc 100644 --- a/plugins/agentic-engineering/README.md +++ b/plugins/agentic-engineering/README.md @@ -123,13 +123,21 @@ 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 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 af78cfb7..e8b4d8f8 100644 --- a/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md +++ b/plugins/agentic-engineering/agents/flux-troubleshooter.agent.md @@ -9,10 +9,14 @@ 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. 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"