{
  "markdown": "<!-- mcp-name: io.github.AIops-tools/k8s-aiops -->\n# k8s-aiops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not\n> affiliated with, endorsed by, or sponsored by the Cloud Native Computing\n> Foundation, the Kubernetes project, or k3s/Rancher.** \"Kubernetes\" and \"k3s\" are\n> trademarks of their respective owners. Source code is publicly auditable at\n> [github.com/AIops-tools/K8s-AIops](https://github.com/AIops-tools/K8s-AIops) under\n> the MIT license.\n\nGoverned Kubernetes operations for AI agents — **55 MCP tools**, every one wrapped\nwith the bundled `@governed_tool` harness: a local unified audit log under\n`~/.k8s-aiops/`, a token/runaway budget guard, undo-token recording, and a\ndescriptive risk-tier label on every audit row. Coverage spans pods, deployments, statefulsets,\ndaemonsets, replicasets, jobs/cronjobs, services, ingresses, endpoints,\nconfigmaps, secrets (names/keys only), PVCs/PVs/storageclasses, nodes, namespaces,\nevents, rollouts (status/history/undo/pause/resume/set-image), pod/node describe,\npod/node top, a cluster health summary, and read-only **diagnostics / RCA**\n(pod-health and workload-readiness) that flag the root cause worst-first.\n\n> **Standalone**: the governance harness is bundled in the package\n> (`k8s_aiops.governance`) — k8s-aiops has no external skill-family dependency.\n> Coverage focuses on common cluster operations and is not yet exhaustive.\n\n> **Verification status**: exercised end-to-end against a live kind cluster (v1.36); the\n> diagnostics/RCA tools added in this release are mock-tested only. See\n> [docs/VERIFICATION.md](docs/VERIFICATION.md).\n\n## What works\n\nAny cluster a kubeconfig can reach: standard Kubernetes, **k3s**, **EKS**, **GKE**,\n**AKS**, kind, minikube. Authentication (client certs, tokens, EKS/GKE/AKS exec\nplugins) is delegated entirely to the kubeconfig.\n\n## What this tool does, and does not, decide\n\nIt delivers Kubernetes operations — reads and writes — accurately and\nefficiently, and records every one of them. It does **not** decide whether a\nwrite is allowed to happen. That is the agent's judgement, or the permission of\nthe kubeconfig context / ServiceAccount you connect it with: point it at a\ncontext bound to a read-only RBAC role and the writes fail at the apiserver —\nthe place that actually owns the permission.\n\nSo there is no read-only switch, no policy file, no approval gate to configure.\nThe one thing the tool guarantees is that nothing is silent: **every call, over\nMCP and over the CLI alike, lands an audit row** in `~/.k8s-aiops/audit.db`, and\ndestructive writes still capture their before-state and record an inverse where\none exists. The runaway budget guard is a safety backstop, not authorization.\n\n> Each tool declares a `risk_level`, kept in agreement with its `[READ]`/`[WRITE]`\n> documentation tag by a test, and carried into the audit row as a descriptive\n> tier — so a reviewer can see at a glance that a row was a high-risk delete. It\n> is a label, not a gate.\n\nRunning a smaller / local model? See\n[agent-guardrails.md](skills/k8s-aiops/references/agent-guardrails.md) — it lists\nthe guardrails this tool now enforces for you (so you don't spend prompt budget\nrestating them) and gives a ready-made system prompt for what's left.\n\n## Quick Start\n\n### As a Claude Code plugin\n\nOne install gives an agent both the skill and the MCP server:\n\n```\n/plugin marketplace add AIops-tools/marketplace\n/plugin install k8s-aiops@aiops-tools\n```\n\nThe MCP server is fetched with [uv](https://docs.astral.sh/uv/) and pinned to the\npackage version this plugin declares, so an audit row can be traced back to the\ncode that wrote it. Credentials are still configured with `k8s-aiops init` — see below.\n\n### As a CLI or standalone MCP server\n\n```bash\nuv tool install k8s-aiops\n\n# Friendly onboarding wizard — registers your kube contexts as named targets:\nk8s-aiops init\n\n# Or skip it — uses your current kube-context out of the box:\nk8s-aiops doctor\nk8s-aiops pod list\nk8s-aiops deployment list -n default\n\n# Read-only RCA — worst-first root-cause findings, no changes made:\nk8s-aiops diagnose pod-health -n prod\nk8s-aiops diagnose workload-readiness -n prod\n```\n\nTo define named targets (multiple clusters/contexts), create\n`~/.k8s-aiops/config.yaml`:\n\n```yaml\ntargets:\n  - name: prod          # used as -t prod\n    context: prod-eks   # a context in your kubeconfig (omit for current-context)\n    namespace: default  # optional default namespace\n    # kubeconfig: /path/to/alt/kubeconfig   # optional explicit path\n  - name: lab\n    context: k3s-lab\n```\n\nNo secrets live in this file — credentials come from the kubeconfig.\n\n## MCP\n\n```jsonc\n{\n  \"command\": \"k8s-aiops\",\n  \"args\": [\"mcp\"],\n  \"env\": { \"K8S_AIOPS_CONFIG\": \"~/.k8s-aiops/config.yaml\" }\n}\n```\n\n> **Note — MCP servers get a clean environment**: most MCP clients spawn the\n> server without your shell's exports, so variables like `K8S_AIOPS_HOME`,\n> `K8S_AUDIT_APPROVED_BY`, `K8S_AUDIT_RATIONALE` (and `KUBECONFIG`, if your\n> kubeconfig is not at `~/.kube/config`) must be set in the MCP server\n> config's `env` block above — values exported only in your terminal may\n> never reach the server.\n\n## Audit & Safety\n\n- Every tool call is logged to `~/.k8s-aiops/audit.db` (local SQLite; relocate with\n  `K8S_AIOPS_HOME`).\n- Reversible writes record an inverse undo descriptor (`scale_deployment` →\n  scale-back to previous; `cordon_node` ↔ `uncordon_node`).\n- Every MCP write tool takes `dry_run=True` and returns a `{\"dryRun\": true, ...}`\n  preview without touching the cluster (no undo recorded for a preview).\n- `delete_deployment` is `risk_level=high`; destructive CLI commands require double\n  confirmation, medium-risk ones (`deployment scale`/`restart`) a single\n  confirmation, and all write commands support `--dry-run`.\n- All API text passes through `sanitize()` (output hygiene: control/format-char\n  stripping + truncation).\n\nSee `skills/k8s-aiops/SKILL.md` and `SECURITY.md` for details.\n\n## Secrets\n\nk8s-aiops deliberately has **no encrypted secret store** (no `secrets.enc`, no\n`secret` CLI): authentication is delegated entirely to your kubeconfig — client\ncertificates, bearer tokens, or exec plugins (EKS/GKE/AKS) — and the tool never\nhandles or stores cluster credentials itself. This is a documented exception to\nthe AIops-tools line-wide encrypted-secret-store pattern.\n\n## Companion Skills\n\n| If you want… | Use |\n|--------------|-----|\n| Kubernetes pods / deployments / nodes | **k8s-aiops** (this) |\n| Hypervisor VM lifecycle | a hypervisor ops skill |\n| Backup & restore | a backup ops skill |\n\n## Contributing & feature requests\n\nCoverage is intentionally focused. **Missing a device, action, or feature you need?** Open an issue or pull request at [github.com/AIops-tools/K8s-AIops](https://github.com/AIops-tools/K8s-AIops/issues) — feature requests, contributions, and comments are all welcome.\n\n## License\n\nMIT — [github.com/AIops-tools/K8s-AIops](https://github.com/AIops-tools/K8s-AIops)\n",
  "bytes": 7009,
  "sha": "146c6eddf74793bf6e8c420a2ef22822477fb1fd4c50ccfc9fd8f9c1cbd37333",
  "repo_slug": "aiops-tools/k8s-aiops",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aiops_tools_k8s_aiops_23f58142/readme"
}