Skip to content

talkops-ai/talkops-helm-plugin

v0.5.0Apache-2.0

Production Helm chart deployment, upgrade, rollback, troubleshooting, and security review skills paired with the TalkOps Helm MCP execution server.

Built on the Two-Layer Separation Principle:

  • Skill Layer (skills/ + plugin.json): Procedural runbooks, values-authoring standards, error-recovery decision trees, security review checklists, and zero-network local Python validation scripts (SKILL.md progressive disclosure).
  • Execution Layer (helm_mcp_server/): Deterministic, context-isolated, secret-redacted Helm CLI and Kubernetes API execution primitives (13 Tools, 10 URI-addressed Resources, 0 Prompts).

Architecture Overview

src/helm-mcp-server/
├── plugin.json                                     # Agent Plugin v1.0.0 manifest
├── mcp.json                                        # Portable MCP server launch configuration
├── skills/                                         # Copy-pasteable Agent Skills (Progressive Disclosure)
│   ├── deploying-helm-charts/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   │   ├── known-repositories.md
│   │   │   └── values-authoring.md
│   │   └── scripts/
│   │       ├── validate_values.py
│   │       └── validate_manifests.py
│   ├── upgrading-and-rolling-back-helm-releases/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── upgrade-checklist.md
│   │       └── rollback-sop.md
│   ├── troubleshooting-helm-releases/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── error-catalog.md
│   └── reviewing-helm-release-security/
│       ├── SKILL.md
│       ├── references/
│       │   └── security-checklist.md
│       └── scripts/
│           └── scan_manifest_security.py
└── helm_mcp_server/                                # FastMCP Execution Server
    ├── config.py                                   # Read-only default, toolsets, env/CLI overrides
    ├── main.py                                     # CLI entrypoint (--transport, --allow-write, --toolsets)
    ├── server/                                     # FastMCP core, middleware, bootstrap
    ├── services/                                   # HelmService & KubernetesService (session context isolated)
    ├── tools/                                      # 13 focused MCP tools (Read, Mutate, Session tiers)
    ├── resources/                                  # 10 URI-addressed MCP resources
    └── utils/                                      # Secret redaction, semver comparison, manifest diffing

Bundled Agent Skills (skills/)

The skills/ directory is self-contained and can be installed directly via the root plugin.json or copied into any agent skill directory (e.g., .claude/skills/, .gemini/skills/, .cursor/skills/):

Skill NamePurposeLocal Scripts & References
deploying-helm-chartsEnd-to-end discovery, values authoring, pre-flight planning, and chart installationscripts/validate_values.py, scripts/validate_manifests.py, references/known-repositories.md, references/values-authoring.md
upgrading-and-rolling-back-helm-releasesSafe live diffing (helm_plan_release), values-merge strategy selection, upgrades, and rollbacksreferences/upgrade-checklist.md, references/rollback-sop.md
troubleshooting-helm-releasesRoot-cause diagnosis and remediation for CrashLoopBackOff, ImagePullBackOff, OOMKilledRecurring, ProgressDeadlineExceeded, and CRD conflictsreferences/error-catalog.md
reviewing-helm-release-securityPre-deployment Kubernetes manifest security auditing (privileged containers, host namespaces, RBAC wildcards, mutable tags)scripts/scan_manifest_security.py, references/security-checklist.md

MCP Execution Surface

1. Tools (13 Total — All $\le 8$ Parameters)

Mutating tools (mutate tag) are hidden by default when MCP_ALLOW_WRITE=false (the default). Enable them with MCP_ALLOW_WRITE=true or --allow-write.

Tier / TagTool NameDescription
readhelm_search_chartsSearch configured Helm chart repositories by keyword (query, repository, versions, limit)
readhelm_list_releasesList Helm releases across or within namespaces with status filter and pagination (limit, offset)
readhelm_get_release_statusSingle-call release status summary with resource counts and links to /history, /values, and /manifest resources
readhelm_render_manifestsRender Kubernetes manifests (helm template) with automatic Secret and sensitive env redaction
readhelm_plan_releaseN-to-1 release planner: computes install preview for new releases or live manifest diff (added/removed/modified resources, image & replica changes) for existing releases
readhelm_monitor_deploymentMulti-layer rollout health monitor checking Helm status, Deployment/StatefulSet rollout conditions, and container failure states
readkubernetes_check_prerequisitesVerify cluster semantic version and API resource/CRD availability via Kubernetes Discovery APIs
sessionkubernetes_set_contextSwitch active Kubernetes context for the current MCP session (propagates --kube-context to all Helm CLI and Kubernetes API calls)
mutatehelm_ensure_repositoryRegister and index a Helm chart repository (helm repo add + helm repo update)
mutatehelm_install_chartInstall a new Helm release with explicit typed parameters (chart_ref, release_name, namespace, values, version, create_namespace, skip_crds, wait_timeout)
mutatehelm_upgrade_releaseUpgrade an existing Helm release (release_name, chart_ref, namespace, values, version, values_strategy, wait_timeout, atomic)
mutatehelm_rollback_releaseRoll back a release to a previous revision (release_name, namespace, revision, wait_timeout, dry_run)
mutatehelm_uninstall_releaseUninstall a Helm release (release_name, namespace, keep_history)

2. URI-Addressed Resources (10 Total)

Resource URIMIME TypeDescription
helm://repositoriesapplication/jsonConfigured Helm chart repositories (helm repo list)
helm://charts/{repository}/{chart_name}application/jsonChart metadata, kubeVersion constraint, and dependencies (Chart.yaml)
helm://charts/{repository}/{chart_name}/valuesapplication/x-yamlDefault values.yaml for a chart
helm://charts/{repository}/{chart_name}/readmetext/markdownChart README.md documentation
helm://releases/{namespace}/{release_name}/historyapplication/jsonRevision history for a deployed release
helm://releases/{namespace}/{release_name}/valuesapplication/jsonRedacted user-supplied values for a deployed release
helm://releases/{namespace}/{release_name}/manifestapplication/x-yamlSecret-redacted Kubernetes YAML manifest for a deployed release
kubernetes://cluster-infoapplication/jsonActive cluster version, node summary, and namespace summary
kubernetes://namespacesapplication/jsonList of Kubernetes namespaces in the active cluster
kubernetes://contextsapplication/jsonAvailable kubeconfig contexts and active session context

Configuration & Running

Environment Variables

VariableDefaultDescription
MCP_TRANSPORTstdioTransport mode: stdio or http (Streamable HTTP)
MCP_ALLOW_WRITEfalseEnable mutating tools (helm_install_chart, helm_upgrade_release, etc.)
MCP_TOOLSETSallComma-separated toolsets to expose: all, read, mutate
MCP_READ_ONLYfalseForce read-only mode (allow_write=False, toolsets=["read"])
KUBECONFIG~/.kube/configPath to Kubernetes configuration file
HELM_TIMEOUT300Timeout in seconds for Helm CLI subprocesses
MCP_HOST / MCP_PORT0.0.0.0 / 8765Bind host and port when MCP_TRANSPORT=http

CLI Usage

# Default: Read-only mode over stdio
uv run helm-mcp-server

# Write-enabled mode over stdio
uv run helm-mcp-server --allow-write

# Streamable HTTP mode on port 8765 with write enabled
uv run helm-mcp-server --transport http --port 8765 --allow-write

Development & Testing

# Install dependencies including dev test suite
uv sync --dev

# Run unit and in-memory FastMCP integration tests
uv run pytest tests/ -v --tb=short

# Run static type checking
uv run pyright .

# Build wheel and sdist
uv build