mcp-portainer 2.41.0__tar.gz

mcp_portainer-2.41.0/.claude/skills/portainer-mcp-hygiene/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: portainer-mcp-hygiene
+description: How to efficiently query the Portainer MCP server's tools — when to project responses with `select` (JMESPath), where the heavy fields live (snapshots, status blocks, managed fields), and how to handle non-JSON Docker/K8s proxy endpoints (logs, stats, exec). Trigger this whenever you're about to call any Portainer MCP tool — including `docker_proxy`, `kubernetes_proxy`, `EndpointList`, `GetAllKubernetes*`, `StackList`, `snapshot*`, `Helm*`, or any other `mcp__portainer__*` tool — and whenever the user asks about Portainer environments, Docker containers/images/stacks/networks managed by Portainer, Kubernetes resources via Portainer, or Helm releases. Use it even if the user doesn't mention Portainer by name, as long as the working answer requires one of these tools.
+---
+
+# Portainer MCP hygiene
+
+The Portainer MCP server returns large JSON payloads by default — a list of environments with snapshots, a list of K8s pods with full status blocks, a stack with its complete manifest. Every tool the server exposes accepts an optional `select` (JMESPath) parameter applied server-side before the response reaches you. Responses are capped at ~50,000 chars; if you exceed the cap you get a truncation hint that names `select` and shows an example.
+
+The cost of *not* projecting is real: 50K chars of dense JSON eats roughly 20K tokens out of your context for a question that usually needed a few hundred. Once truncation fires, you've wasted a round trip and the data past the cap is gone for that call. The default move on any list-shaped Portainer call is to pass `select` from the start.
+
+## The default pattern
+
+For any call that returns a list of objects, ship a JMESPath that keeps only the fields the user's question actually needs:
+
+```
+EndpointList(select="[].{id:Id,name:Name,type:Type,status:Status}")
+docker_proxy(path="/containers/json", select="[].{id:Id,name:Names[0],state:State,image:Image}")
+kubernetes_proxy(path="/api/v1/pods", select="items[].{name:metadata.name,ns:metadata.namespace,phase:status.phase,node:spec.nodeName}")
+```
+
+JMESPath syntax notes that matter for these surfaces:
+- List shape: start with `[]` to map over array elements.
+- Wrapped list (Kubernetes `{items: [...]}`): start with `items[]`.
+- Single object: `{field1:path.to.value,field2:other.path}` — no leading `[]`.
+- Nested paths use dots: `Snapshots[0].RunningContainerCount`, `metadata.labels."app.kubernetes.io/name"` (quote keys that contain dots or hyphens).
+
+## Where the noise lives
+
+These are the fields/sections that dominate Portainer payloads. Either project them out (when you don't need them) or project specifically into them (when they *are* the answer):
+
+**`EndpointList` — `.Snapshots[0]` carries the heavy payload.**
+Each environment includes a full Docker or Kubernetes snapshot — container list, image list, network list, etc. For counts and status questions you almost always want to project into specific snapshot fields rather than fetch them whole:
+
+```
+# Container counts per environment
+EndpointList(select="[].{name:Name,running:Snapshots[0].RunningContainerCount,total:Snapshots[0].ContainerCount}")
+
+# Just identity + reachability
+EndpointList(select="[].{id:Id,name:Name,type:Type,status:Status}")
+```
+
+**Kubernetes via `kubernetes_proxy` — `metadata.managedFields` and `status` are huge.**
+`metadata.managedFields` alone is routinely 30-70% of an object. The `status` block on Deployments, StatefulSets, Pods, and Nodes is similarly verbose. Project them out unless the user is asking about reconciliation state or controller history:
+
+```
+# Pod summary
+kubernetes_proxy(path="/api/v1/pods", select="items[].{name:metadata.name,ns:metadata.namespace,phase:status.phase,restarts:status.containerStatuses[0].restartCount,node:spec.nodeName}")
+
+# Deployment readiness
+kubernetes_proxy(path="/apis/apps/v1/deployments", select="items[].{name:metadata.name,ns:metadata.namespace,replicas:spec.replicas,ready:status.readyReplicas}")
+```
+
+**`GetAllKubernetes*` tools — full status blocks per object.**
+The OpenAPI-generated `GetAllKubernetesApplications`, `GetAllKubernetesConfigMaps`, `GetAllKubernetesIngresses`, etc. return arrays where each element carries its full object body. Same rules as the proxy: project to the named fields you need.
+
+**`StackList` and `StackInspect` — config and env vars.**
+Stacks carry the full compose/manifest content plus environment variable dictionaries. If the user asked "which stacks exist?", project to `{id, name, type, status}`. If they asked about a specific stack's config, fetch it directly and only then look at the body.
+
+**Snapshot inspects (`snapshotInspect`, `snapshotContainersList`, etc.) — entire snapshots.**
+These return the *whole* snapshot blob by design. Always project.
+
+**Helm endpoints — full chart values and manifests.**
+`HelmList` carries release status + chart metadata; `HelmGet` returns the rendered manifest. Project to release names and status when listing; only fetch the manifest when the user asked to see it.
+
+**`EndpointGetCharts`, `dockerDashboard`, `EndpointSummaryCounts` — already aggregated.**
+These are the lightweight "summary" tools. Prefer them over `EndpointList` + projection when the user's question is purely a count or rollup — fewer characters, less work, more accurate (server-side aggregation).
+
+## Patterns for common questions
+
+A few high-frequency questions and the projection that gets them in one call:
+
+**"How many running containers in each environment?"**
+```
+EndpointList(select="[].{name:Name,type:Type,running:Snapshots[0].RunningContainerCount,total:Snapshots[0].ContainerCount}")
+```
+
+**"List containers in environment N."**
+```
+docker_proxy(environment_id=N, path="/containers/json",
+             select="[].{id:Id,name:Names[0],state:State,image:Image,status:Status}")
+```
+
+**"Which images are in use, grouped by name?"**
+Fetch with projection, group client-side:
+```
+docker_proxy(environment_id=N, path="/containers/json", select="[].Image")
+```
+
+**"One-line pod summary in environment N."**
+```
+kubernetes_proxy(environment_id=N, path="/api/v1/pods",
+                 select="items[].{name:metadata.name,ns:metadata.namespace,phase:status.phase,node:spec.nodeName}")
+```
+
+**"Which deployments aren't fully ready?"**
+Project readiness fields, then filter in the response. (JMESPath can also filter inline with `items[?status.readyReplicas != spec.replicas]`, but expressions like that are easy to get wrong — projection + your own filter is usually safer.)
+
+**"Inspect deployment X in namespace Y."**
+A single-object fetch. Project out `metadata.managedFields` and `status.conditions` if you only need the spec; keep them if the user is asking about reconciliation:
+```
+kubernetes_proxy(environment_id=N, path="/apis/apps/v1/namespaces/Y/deployments/X",
+                 select="{name:metadata.name,replicas:spec.replicas,ready:status.readyReplicas,image:spec.template.spec.containers[0].image}")
+```
+
+## Non-JSON endpoints — `select` does not apply
+
+A handful of `docker_proxy` and `kubernetes_proxy` paths return plain text or streamed data rather than JSON. `select` is a no-op on these (the proxy detects non-JSON and passes the body through unchanged), but the response-size cap still fires, and `_select_wrapper` will raise a JSON parse error if you do pass `select`. **Narrow the upstream query parameters instead.**
+
+**Container logs** — `/containers/{id}/logs`:
+- Set `tail` to limit lines (`tail=100` for the last hundred).
+- Set `since` to limit time range (Unix timestamp).
+- Always pass `stdout=true` and/or `stderr=true` — without them the daemon returns nothing.
+- Don't set `follow=true` — it streams indefinitely and will burn your context.
+
+**Container stats** — `/containers/{id}/stats`:
+- Always pass `stream=false` to get a single snapshot. The streaming form is unbounded.
+
+**Container exec output** — chunked stream.
+- If you need command output, prefer `docker_proxy` against `/containers/{id}/top` for process listing, or run the command another way. Exec attach over HTTP returns multiplexed binary frames and won't render usefully through the cap.
+
+**Image pulls / archives / build context** — binary or streamed.
+- Don't fetch these through the proxy for inspection. Use the specific Portainer endpoints (`endpointDockerhubStatus`, `ServiceImageStatus`, `dockerImagesList`) which return parseable JSON summaries.
+
+If the cap fires on a non-JSON endpoint, the truncation hint will suggest `select` — ignore that suggestion in this case and retry with narrower upstream parameters.
+
+## When *not* to project
+
+Projecting isn't always right:
+
+- **Small single-object reads** that you already know are under a few KB — `SettingsInspect`, `MOTD`, `StatusInspect`, `systemVersion`. Projecting just adds a round of cognitive overhead for no win.
+
+- **Exploratory scans where you don't know what you're looking for** — "anything unusual in this stack's config", "is there an error somewhere in this deployment's status". Here you want the full body so you can scan for patterns. Pull the full object; if it truncates, narrow the *path* (one resource, not the whole list) rather than projecting fields.
+
+- **When the user asked for "everything"** — sometimes they really do want the raw object. Respect that, but warn them once if you're about to retrieve something that will eat their context.
+
+## Reading the truncation hint
+
+When you do hit the cap, the response ends with a bracketed `[truncated: ... Retry with a JMESPath `select` ...]` message that includes a concrete example. Your next move should almost always be: retry the *same* call with a `select` projection — not pivot to reading the spilled file with `jq`, not paginate by guessing offsets, not call a different tool. The server-side projection is cheaper (no re-fetch from Portainer if the data was already cached upstream, and far fewer tokens shipped back).
+
+The exception is non-JSON endpoints (see above) — there, ignore the `select` suggestion and re-shape the upstream query instead.
+
+## Tool selection cheatsheet
+
+- Environment-level summary (counts, status, reachability) → `EndpointList` with snapshot projection, or `EndpointSummaryCounts`/`dockerDashboard` if the question is purely aggregate.
+- Docker things on a specific environment → `docker_proxy`. The OpenAPI-generated `dockerContainerGpusInspect`, `containerImageStatus`, etc. are specific helpers; use them when they directly answer the question, otherwise the proxy is more flexible.
+- Kubernetes things on a specific environment → either the OpenAPI-generated `GetAllKubernetes*` / `GetKubernetes*` tools (Portainer-aware, often already filtered) or `kubernetes_proxy` (raw K8s API, full flexibility). Prefer the typed tool when it exists; fall back to the proxy for paths Portainer doesn't surface natively.
+- Helm releases → `HelmList`, `HelmGet`, `HelmGetHistory`. Don't try to route Helm through the K8s proxy — Portainer's Helm tools see the release metadata the K8s API alone doesn't.
+- Mutations (POST/PUT/DELETE) → only in read-write mode. If the server is in `PORTAINER_READ_ONLY=1`, non-GET calls are rejected at the tool with a clear error. Don't retry mutations as GET when this happens — surface the read-only state to the user.

mcp_portainer-2.41.0/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env and fill in. Used by `make dev`.
+
+# Required
+PORTAINER_URL=https://portainer.example.com
+PORTAINER_API_KEY=ptr_xxxxxxxxxxxxxxxx
+
+# Optional — see README for the full list
+# PORTAINER_TLS_VERIFY=0
+# PORTAINER_PROFILES=ALL
+# PORTAINER_MCP_LOG_LEVEL=DEBUG

mcp_portainer-2.41.0/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run pytest

mcp_portainer-2.41.0/.github/workflows/release-test.yml

@@ -0,0 +1,37 @@
+# Dry-run release to TestPyPI. Triggered manually from the Actions tab.
+# See docs/release.md for setup and process.
+
+name: Release (TestPyPI)
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          repository-url: https://test.pypi.org/legacy/

mcp_portainer-2.41.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+# See docs/release.md for the release process and one-time setup.
+
+name: Release
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - name: Verify tag matches pyproject version
+        run: |
+          tag="${GITHUB_REF#refs/tags/}"
+          version=$(uv run python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$tag" != "$version" ]; then
+            echo "tag $tag does not match pyproject version $version" >&2
+            exit 1
+          fi
+      - run: uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

mcp_portainer-2.41.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.egg-info/
+spec/upstream/
+logs/
+*.local.md
+.env
+dist/

mcp_portainer-2.41.0/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+The versioning policy is described in [`docs/versioning.md`](docs/versioning.md)
+— major+minor tracks the Portainer API version; the patch slot belongs to
+the MCP server.
+
+## [Unreleased]
+
+## [2.41.0] — 2026-05-19
+
+Initial release. Targets Portainer 2.41.x. Distributed
+on PyPI as `mcp-portainer`.
+
+### Added
+
+- **Tool surface from the Portainer OpenAPI spec** via
+  `FastMCP.from_openapi`. The patched spec (EE 2.41.1) ships inside the
+  wheel at `src/portainer_mcp/data/portainer-patched.yaml`, loaded via
+  `importlib.resources`. End users do not run the patcher.
+- **Profile-based tag allowlist** at
+  [`src/portainer_mcp/profiles.py`](src/portainer_mcp/profiles.py): five
+  named bundles (`BASE`, `DOCKER`, `KUBERNETES`, `EDGE`, `ADMIN`) plus an
+  `ALL` sentinel, selected via `PORTAINER_PROFILES`. Unknown profile
+  names fail loudly at startup; `PORTAINER_TAGS_EXTRA` is the escape
+  hatch for orphan tags. Default `BASE,DOCKER,KUBERNETES` covers ~180 of
+  387 spec operations. See [`docs/profiles.md`](docs/profiles.md).
+- **Orthogonal modifiers**: `PORTAINER_READ_ONLY=1` filters to `GET` /
+  `HEAD` only; `PORTAINER_NO_PROXY=1` skips proxy-tool registration.
+- **Universal response shaping**: every tool — generated OpenAPI tools
+  and hand-written proxies alike — accepts an optional JMESPath `select`
+  argument applied server-side. Implemented via
+  `shaping.SelectArgTransform` (a `fastmcp.server.transforms.Transform`
+  subclass) registered with `mcp.add_transform(...)`. Startup canary
+  (`await mcp.list_tools()`) raises if any tool is missing `select`.
+- **Response truncation hint**: `ResponseCapMiddleware` caps responses
+  at `PORTAINER_MAX_RESPONSE_CHARS` (default 50000, ~80% of Claude
+  Code's MCP ceiling) and appends a `select`-teaching hint with a
+  concrete example before the client's own cap fires.
+- **Hand-written proxy tools** for endpoints the OpenAPI spec can't
+  express cleanly: `docker_proxy` and `kubernetes_proxy`, with
+  validators rejecting `..` / `?` / `#` in paths and a blocked-header
+  list. JMESPath projection passes through non-JSON responses unchanged
+  (logs, stats, exec).
+- **HTTP transport mode** via `PORTAINER_MCP_TRANSPORT=http` plus
+  `PORTAINER_MCP_HTTP_HOST` (default `127.0.0.1`) and
+  `PORTAINER_MCP_HTTP_PORT` (default `8000`). Powers `make dev` — a
+  long-running local server connected via
+  `claude mcp add … --transport http http://127.0.0.1:8000/mcp` — and
+  the eventual remote-container deployment.
+- **Logging routed to stderr** per the MCP spec (stdio servers' logging
+  surface). FastMCP banner and its version-check call to
+  `pypi.org/pypi/fastmcp/json` are suppressed so deployed-server stderr
+  stays ours.
+- **PyPI release pipeline** at
+  [`.github/workflows/release.yml`](.github/workflows/release.yml): tag
+  push (`X.Y.Z`) builds the wheel, verifies the tag matches
+  `pyproject.version`, runs tests, and publishes to PyPI via OIDC-based
+  Trusted Publishing. No API tokens or repo secrets. Process docs:
+  [`docs/release.md`](docs/release.md).
+- **Maintainer spec-refresh pipeline**: `make specs VERSION=X.Y.Z`
+  shallow-clones `portainer/portainer-api-docs` (SSH default,
+  `UPSTREAM_REPO=` override) into `spec/upstream/` and runs
+  `spec/patch_spec.py` against the requested EE YAML.
+  [`spec/patch_spec.py`](spec/patch_spec.py) applies workarounds for
+  known upstream spec defects (excluded operations, `/websocket/*`
+  paths, malformed enums, YAML tab/`=`-tag defects).
+- **Test suite + CI**: 41 tests under [`tests/`](tests/) covering the
+  pure-data surface (spec patcher, shaping, proxy validators). CI runs
+  `uv sync --frozen` + `uv run pytest` on push to `main` and every PR.
+- **Hygiene skill** at
+  [`skills/portainer-mcp-hygiene/`](skills/portainer-mcp-hygiene/) —
+  guidance for MCP clients on when to project with `select`, where the
+  heavy fields live, and how to handle non-JSON proxy responses.
+- **FastMCP pin** at `>=3.3,<4` (the `OpenAPIProvider` import path used
+  here only exists on 3.x).
+- **Versioning policy** at [`docs/versioning.md`](docs/versioning.md):
+  major+minor pins to Portainer's API version; patch slot is the MCP
+  server's own.
+
+### Known gaps
+
+- **CE coverage** is best-effort. The embedded spec is EE; CE is a
+  subset and operations missing from CE surface as 404s at call time.
+- **Remote container deployment** (HTTP transport + auth) is not yet
+  shipped. The transport switch and `make dev` workflow lay the
+  groundwork; auth and a Dockerfile come after PyPI lands.

mcp_portainer-2.41.0/CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+MCP server for Portainer, distributed on PyPI as `mcp-portainer`. The tool
+surface is generated from Portainer's EE OpenAPI spec at startup via
+`FastMCP.from_openapi`, with a small filter + response-shaping layer applied
+uniformly. Two hand-written escape-hatch tools (`docker_proxy`,
+`kubernetes_proxy`) forward arbitrary paths the spec doesn't enumerate.
+
+Python ≥ 3.11. `uv` is the package manager — there is no `pip`/`poetry`
+workflow. Source layout: `src/portainer_mcp/`.
+
+## Commands
+
+```bash
+uv sync                              # install deps from uv.lock
+uv run pytest                        # run the full test suite
+uv run pytest tests/test_proxy.py    # one file
+uv run pytest -k select_unwraps      # one test by name
+make dev                             # local HTTP server via uv + .env (port 8000)
+make specs VERSION=2.41.1            # refresh src/portainer_mcp/data/portainer-patched.yaml
+```
+
+`make dev` requires `.env` (copy from `.env.example`). It runs the server
+over HTTP at `127.0.0.1:8000` so you can iterate without restarting an MCP
+client — the client (added with `claude mcp add portainer-dev --transport
+http http://127.0.0.1:8000/mcp`) reconnects automatically after a ctrl-c +
+`make dev`.
+
+Lint/format: none configured. CI runs only `uv sync --frozen && uv run
+pytest` (see `.github/workflows/ci.yml`).
+
+## Architecture
+
+Read [`docs/architecture.md`](docs/architecture.md) for the full picture.
+Key things to internalise before changing code:
+
+- **`server.py:build_server()` is the wiring point.** It loads the bundled
+  spec, builds the httpx client (carrying `X-API-KEY`), constructs
+  `RouteMap`s from the resolved profile tags, instantiates FastMCP, then
+  registers proxy tools, adds `SelectArgTransform`, and finally adds
+  `ResponseCapMiddleware`. Order matters — the transform must run before
+  the middleware so every tool exposes `select`.
+- **One `RouteMap` per tag.** FastMCP intersects multi-tag `RouteMap(tags=…)`
+  (it's all-of, not any-of), so we emit one `RouteMap` per allowed tag and
+  union the matches. Don't collapse them into a single multi-tag map.
+- **`select` is universal.** `SelectArgTransform` (`shaping.py`) wraps
+  every tool with an optional JMESPath `select` parameter, including the
+  two hand-written proxy tools (their existing `select` arg makes
+  `_has_select` skip re-wrapping them). After registration, `build_server`
+  asserts every tool exposes `select` and raises at startup if any are
+  missing — keep that invariant.
+- **Response cap sits below Claude Code's MCP output cap.** Default
+  `PORTAINER_MAX_RESPONSE_CHARS=50_000` is sized so our truncation hint
+  (which names `select` with examples) reaches the model before Claude
+  Code's own ~62k-char cap triggers its generic "saved to file" handling.
+  When truncation fires, `structured_content` is also cleared so the model
+  can't read around the cap.
+- **JMESPath unwrap for non-dict responses.** FastMCP wraps list/scalar
+  OpenAPI responses as `{"result": …}` to fit MCP's structured-content
+  schema. `_select_wrapper` unwraps that single-key envelope before
+  projecting, so callers write `[].Id` rather than `result[].Id`.
+
+## Spec generation
+
+The bundled spec lives at `src/portainer_mcp/data/portainer-patched.yaml`
+and is loaded via `importlib.resources` (so it's read from the wheel in
+production, not relative paths). To regenerate:
+
+1. `make specs VERSION=<portainer-version>` — clones/refreshes
+   `spec/upstream/` (sparse, single-version), then runs `spec/patch_spec.py`.
+2. `patch_spec.py` drops structurally broken operations (see
+   `EXCLUDED_OPERATION_IDS`), strips `/websocket/*` paths, normalises a
+   few malformed `enum` blocks, and rewrites stray tabs. Extend those
+   constants when the upstream spec ships new defects — don't hand-edit
+   `portainer-patched.yaml`.
+
+## Versioning
+
+Tag format `<portainer-major>.<portainer-minor>.<mcp-patch>` — major+minor
+mirrors the Portainer API target; patch is the MCP server's. **The minor
+only moves when the embedded spec moves.** Refactors, profile additions,
+new proxy tools, shaping changes — all patch. See
+[`docs/versioning.md`](docs/versioning.md) and [`docs/release.md`](docs/release.md)
+(release is OIDC-driven via PyPI Trusted Publishing on tag push).
+
+## Profiles
+
+Spec exposes ~380 operations across 40+ tags; profiles in `profiles.py`
+bundle them. `PORTAINER_PROFILES` (default `BASE,DOCKER,KUBERNETES`)
+selects which to enable; `PORTAINER_TAGS_EXTRA` appends raw tags as an
+escape hatch. `PORTAINER_PROFILES=ALL` disables the tag filter entirely.
+Unknown profile names fail at startup; unknown extras log a warning and
+pass through (they just don't match anything). Full per-profile tag list
+and orphan-tag inventory in [`docs/profiles.md`](docs/profiles.md).
+
+## Tests
+
+`pytest` with `asyncio_mode = "auto"` (see `pyproject.toml`). Tests live
+in `tests/` and import the spec patcher via `tests/conftest.py` which
+prepends `spec/` to `sys.path` (it's a script dir, not a package).
+
+## Conventions
+
+- This repo follows a YAGNI / minimal-surface style: no speculative
+  scaffolding, no literal-guard tests, no refactor-for-testability without
+  independent merit. Trust internal code, validate at boundaries.
+- Comments are sparse and exist to explain *why* (hidden constraints,
+  surprising behaviour, workarounds for spec defects). Don't add WHAT
+  comments — identifiers carry that.
+- Env-var flags are parsed via `_env_flag` in `server.py`; falsy values
+  are `0`, `false`, `False`.

mcp_portainer-2.41.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Portainer.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

mcp_portainer-2.41.0/Makefile

@@ -0,0 +1,29 @@
+UPSTREAM_REPO ?= git@github.com:portainer/portainer-api-docs.git
+UPSTREAM_DIR  := spec/upstream
+
+.PHONY: specs dev
+
+# Refresh src/portainer_mcp/data/portainer-patched.yaml from upstream
+# Usage: make specs VERSION=2.41.1
+specs:
+	@if [ -z "$(VERSION)" ]; then \
+		echo "VERSION is required, e.g. make specs VERSION=2.41.1" >&2; \
+		exit 1; \
+	fi
+	@if [ -d $(UPSTREAM_DIR)/.git ]; then \
+		git -C $(UPSTREAM_DIR) fetch --depth=1 origin HEAD && \
+		git -C $(UPSTREAM_DIR) reset --hard FETCH_HEAD; \
+	else \
+		git clone --depth=1 --filter=blob:none --no-checkout \
+			$(UPSTREAM_REPO) $(UPSTREAM_DIR); \
+	fi
+	git -C $(UPSTREAM_DIR) sparse-checkout set --no-cone /versions/ee/$(VERSION).yaml
+	git -C $(UPSTREAM_DIR) checkout
+	uv run python spec/patch_spec.py $(UPSTREAM_DIR)/versions/ee/$(VERSION).yaml
+
+# Local dev server (HTTP transport). One-time setup:
+#   1. cp .env.example .env  and fill in PORTAINER_URL + PORTAINER_API_KEY
+#   2. claude mcp add portainer-dev --transport http http://127.0.0.1:8000/mcp
+# Then iterate: edit code, ctrl-c, make dev again. Claude reconnects automatically.
+dev:
+	PORTAINER_MCP_TRANSPORT=http uv run --env-file .env portainer-mcp

mcp_portainer-2.41.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: mcp-portainer
+Version: 2.41.0
+Summary: Portainer MCP server — manage Docker, Kubernetes, stacks, and Helm via the Model Context Protocol.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastmcp<4,>=3.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: jmespath>=1.0
+Requires-Dist: pyyaml>=6.0

mcp_portainer-2.41.0/README.md

@@ -0,0 +1,78 @@
+# Portainer MCP
+
+MCP server for Portainer, generated from the Portainer OpenAPI spec via
+[FastMCP](https://github.com/PrefectHQ/fastmcp).
+
+## Overview
+
+Exposes Portainer's REST API as MCP tools — list environments, manage
+Docker containers and stacks, query Kubernetes resources, run Helm
+releases. Two escape-hatch tools (`docker_proxy`, `kubernetes_proxy`)
+forward arbitrary paths to the underlying Docker/K8s APIs for endpoints
+the spec doesn't enumerate.
+
+**Status: in development.** Tool names, env vars, and defaults can
+change between releases. Pin loosely (see
+[Version compatibility](#version-compatibility)) to pick up MCP-only
+fixes without surprise.
+
+Architecture overview: [`docs/architecture.md`](docs/architecture.md).
+
+## Getting started
+
+The server is distributed on PyPI as `mcp-portainer`. MCP clients launch it as
+a subprocess via [`uvx`](https://docs.astral.sh/uv/), so `uv` must be on
+`PATH` — see [the uv install docs](https://docs.astral.sh/uv/getting-started/installation/).
+
+Generate an API key in Portainer under **My Account → Access tokens**, then
+register the server with Claude Code:
+
+```bash
+claude mcp add portainer \
+  -e PORTAINER_URL=https://portainer.example.com \
+  -e PORTAINER_API_KEY=ptr_xxxxxxxxxxxxxxxx \
+  -- uvx --from "mcp-portainer~=2.41.0" mcp-portainer
+```
+
+`~=2.41.0` picks up MCP-only patch fixes against the same Portainer minor —
+see [Version compatibility](#version-compatibility) for the policy.
+
+For other clients, see [`docs/distribution/`](docs/distribution/). See
+[Configuration](#configuration) for optional knobs.
+
+Contribution are welcome for other client instructions !
+
+## Version compatibility
+
+**Match your server's minor to your Portainer minor.** The
+major+minor tracks the Portainer API version the embedded spec targets.
+
+| Server version | Portainer (CE / EE) |
+| -------------- | ------------------- |
+| `2.41.x`       | `2.41.x`            |
+
+- EE spec only — CE is a subset and works on a best-effort basis.
+- Full policy: [`docs/versioning.md`](docs/versioning.md).
+
+## Configuration
+
+All knobs are environment variables. Only `PORTAINER_URL` and
+`PORTAINER_API_KEY` are required.
+
+| Env var | Default | Effect |
+|---|---|---|
+| `PORTAINER_URL` | — | **Required.** Portainer base URL. |
+| `PORTAINER_API_KEY` | — | **Required.** Portainer API key. |
+| `PORTAINER_PROFILES` | `BASE,DOCKER,KUBERNETES` | Tag bundles to enable. `ALL` disables the filter. |
+| `PORTAINER_TAGS_EXTRA` | _empty_ | Extra tags appended to the profile union (escape hatch). |
+| `PORTAINER_READ_ONLY` | `0` | `1` restricts to `GET`/`HEAD` operations. |
+| `PORTAINER_NO_PROXY` | `0` | `1` skips `docker_proxy` / `kubernetes_proxy`. |
+| `PORTAINER_TLS_VERIFY` | `1` | `0` skips TLS verification (Portainer instance using self-signed certs). |
+| `PORTAINER_MAX_RESPONSE_CHARS` | `50000` | Response truncation cap. Size to ~80% of your MCP client's output ceiling. |
+| `PORTAINER_MCP_LOG_LEVEL` | `INFO` | One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Logs go to stderr. |
+| `PORTAINER_MCP_TRANSPORT` | `stdio` | `stdio` (default) or `http`. `http` binds a local server for dev / remote deployment. |
+| `PORTAINER_MCP_HTTP_HOST` | `127.0.0.1` | Bind host when `PORTAINER_MCP_TRANSPORT=http`. |
+| `PORTAINER_MCP_HTTP_PORT` | `8000` | Bind port when `PORTAINER_MCP_TRANSPORT=http`. |
+
+Advanced profile setup — per-profile tag lists, orphan tags, read-only
+semantics — see [`docs/profiles.md`](docs/profiles.md).