claude-plugin-kubernetes 0.1.0__tar.gz

claude_plugin_kubernetes-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: claude-plugin-kubernetes
+Version: 0.1.0
+Summary: Claude MCP plugin for Kubernetes cluster awareness, diagnostics, and remediation
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

claude_plugin_kubernetes-0.1.0/README.md

@@ -0,0 +1,84 @@
+# Claude Plugin — Kubernetes
+
+An MCP server that gives Claude deep Kubernetes cluster awareness, diagnostics, and remediation capabilities via `kubectl`.
+
+## Tools (21)
+
+### Awareness
+| Tool | Description |
+|---|---|
+| `k8s_cluster_info` | Current context, server version, API endpoint |
+| `k8s_get_contexts` | List all kubeconfig contexts |
+| `k8s_list_namespaces` | List namespaces with status |
+| `k8s_list_nodes` | Nodes with roles, status, OS, IP |
+| `k8s_list_pods` | Pods with status, restarts, node (filter by ns/label) |
+| `k8s_list_deployments` | Deployments with replica counts |
+| `k8s_list_services` | Services with type, IPs, ports |
+| `k8s_list_events` | Cluster events (filterable by Warning type) |
+
+### Diagnostics
+| Tool | Description |
+|---|---|
+| `k8s_describe` | `kubectl describe` any resource |
+| `k8s_logs` | Pod logs (tail, container, previous container) |
+| `k8s_top_pods` | Pod CPU/memory (requires metrics-server) |
+| `k8s_top_nodes` | Node CPU/memory (requires metrics-server) |
+| `k8s_find_issues` | Full cluster health scan — failing pods, node pressure, bad deployments, warning events |
+| `k8s_get_yaml` | Export any resource as YAML |
+
+### Remediation
+| Tool | Risk | Description |
+|---|---|---|
+| `k8s_restart_deployment` | Low | Rolling restart a deployment |
+| `k8s_scale` | Medium | Scale deployment/statefulset replicas |
+| `k8s_delete_pod` | Low-Med | Delete pod (triggers controller recreation) |
+| `k8s_rollback_deployment` | Medium | Rollback to previous or specific revision |
+| `k8s_apply_manifest` | Medium | Apply YAML/JSON manifest via stdin |
+| `k8s_patch_resource` | Medium | JSON merge patch any resource |
+| `k8s_node_operation` | High | Cordon / uncordon / drain a node |
+
+## Setup
+
+### Claude Desktop
+
+Add the following to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/kanr/claude-plugin-kubernetes", "k8s-mcp"]
+    }
+  }
+}
+```
+
+Requires [`uv`](https://docs.astral.sh/uv/getting-started/installation/) to be installed. Once published to PyPI, the `git+https://...` can be replaced with simply `claude-plugin-kubernetes`.
+
+### Claude Code (CLI)
+
+The `.mcp.json` in this repo is already configured. Clone the repo and open it in Claude Code — the server registers automatically.
+
+To verify, run `/mcp` inside Claude Code. You should see `kubernetes` listed with 21 tools.
+
+### Local development
+
+```bash
+git clone https://github.com/kanr/claude-plugin-kubernetes
+cd claude-plugin-kubernetes
+python3 -m venv .venv && .venv/bin/pip install -e .
+```
+
+## Requirements
+
+- `kubectl` installed and on `$PATH`
+- A valid `~/.kube/config` (or `$KUBECONFIG` set)
+- Python 3.11+
+- `metrics-server` installed in the cluster for `k8s_top_pods` / `k8s_top_nodes`
+
+## Security Notes
+
+- The kubectl wrapper uses `asyncio.create_subprocess_exec` — no shell, no injection risk.
+- All resource names are passed as discrete arguments, never interpolated into shell strings.
+- Remediation tools carry risk labels. Claude will warn you before applying destructive changes.

claude_plugin_kubernetes-0.1.0/claude_plugin_kubernetes.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: claude-plugin-kubernetes
+Version: 0.1.0
+Summary: Claude MCP plugin for Kubernetes cluster awareness, diagnostics, and remediation
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

claude_plugin_kubernetes-0.1.0/claude_plugin_kubernetes.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+claude_plugin_kubernetes.egg-info/PKG-INFO
+claude_plugin_kubernetes.egg-info/SOURCES.txt
+claude_plugin_kubernetes.egg-info/dependency_links.txt
+claude_plugin_kubernetes.egg-info/entry_points.txt
+claude_plugin_kubernetes.egg-info/requires.txt
+claude_plugin_kubernetes.egg-info/top_level.txt
+k8s_mcp/__init__.py
+k8s_mcp/formatters.py
+k8s_mcp/kubectl.py
+k8s_mcp/server.py
+k8s_mcp/tools/__init__.py
+k8s_mcp/tools/awareness.py
+k8s_mcp/tools/diagnostics.py
+k8s_mcp/tools/remediation.py

claude_plugin_kubernetes-0.1.0/claude_plugin_kubernetes.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

claude_plugin_kubernetes-0.1.0/claude_plugin_kubernetes.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+k8s-mcp = k8s_mcp.server:main

claude_plugin_kubernetes-0.1.0/claude_plugin_kubernetes.egg-info/requires.txt

@@ -0,0 +1,6 @@
+mcp>=1.0
+pyyaml>=6.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23

claude_plugin_kubernetes-0.1.0/claude_plugin_kubernetes.egg-info/top_level.txt

@@ -0,0 +1 @@
+k8s_mcp

claude_plugin_kubernetes-0.1.0/k8s_mcp/formatters.py

@@ -0,0 +1,56 @@
+"""Shared output formatting helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def section(title: str, body: str) -> str:
+    """Format a titled section."""
+    bar = "─" * len(title)
+    return f"{title}\n{bar}\n{body}"
+
+
+def bullet_list(items: list[str]) -> str:
+    return "\n".join(f"  • {item}" for item in items)
+
+
+def kv_table(pairs: list[tuple[str, Any]], indent: int = 0) -> str:
+    if not pairs:
+        return ""
+    max_key = max(len(str(k)) for k, _ in pairs)
+    pad = " " * indent
+    lines = [f"{pad}{str(k).ljust(max_key)}  {v}" for k, v in pairs]
+    return "\n".join(lines)
+
+
+def severity_icon(level: str) -> str:
+    return {"critical": "🔴", "warning": "🟡", "info": "🔵"}.get(level, "⚪")
+
+
+def node_conditions_summary(conditions: list[dict]) -> str:
+    """Summarise node conditions from the JSON .status.conditions list."""
+    issues = []
+    healthy = []
+    for c in conditions:
+        ctype = c.get("type", "")
+        status = c.get("status", "")
+        reason = c.get("reason", "")
+        msg = c.get("message", "")
+
+        # Ready=True is good; all others False/Unknown is good
+        if ctype == "Ready":
+            if status != "True":
+                issues.append(f"NotReady ({reason}): {msg}")
+            else:
+                healthy.append("Ready")
+        else:
+            if status == "True":
+                issues.append(f"{ctype} ({reason}): {msg}")
+
+    result_parts = []
+    if healthy:
+        result_parts.append(", ".join(healthy))
+    if issues:
+        result_parts.append("ISSUES: " + " | ".join(issues))
+    return " | ".join(result_parts) if result_parts else "Unknown"

claude_plugin_kubernetes-0.1.0/k8s_mcp/kubectl.py

@@ -0,0 +1,127 @@
+"""
+Async kubectl wrapper.
+
+Uses asyncio.create_subprocess_exec — no shell involved, immune to injection.
+All callers must pass resource names/values as explicit list elements, never
+interpolated into a shell string.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Sequence
+
+
+KUBECTL_TIMEOUT = 60  # seconds
+MAX_OUTPUT_BYTES = 10 * 1024 * 1024  # 10 MB
+
+
+class KubectlError(Exception):
+    """Raised when kubectl exits with a non-zero status."""
+
+
+def _build_args(
+    args: Sequence[str],
+    context: str | None = None,
+    namespace: str | None = None,
+    all_namespaces: bool = False,
+) -> list[str]:
+    prefix: list[str] = []
+    suffix: list[str] = []
+    if context:
+        prefix += ["--context", context]
+    if all_namespaces:
+        suffix += ["--all-namespaces"]
+    elif namespace:
+        prefix += ["--namespace", namespace]
+    return prefix + list(args) + suffix
+
+
+async def kubectl(
+    args: Sequence[str],
+    *,
+    context: str | None = None,
+    namespace: str | None = None,
+    all_namespaces: bool = False,
+) -> str:
+    """Run kubectl and return stdout as a string."""
+    full_args = _build_args(args, context=context, namespace=namespace, all_namespaces=all_namespaces)
+
+    proc = await asyncio.create_subprocess_exec(
+        "kubectl",
+        *full_args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    try:
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=KUBECTL_TIMEOUT)
+    except asyncio.TimeoutError:
+        proc.kill()
+        raise KubectlError(f"kubectl timed out after {KUBECTL_TIMEOUT}s: kubectl {' '.join(full_args)}")
+
+    if len(stdout) > MAX_OUTPUT_BYTES:
+        stdout = stdout[:MAX_OUTPUT_BYTES] + b"\n[... output truncated at 10 MB ...]"
+
+    if proc.returncode != 0:
+        err = stderr.decode(errors="replace").strip()
+        raise KubectlError(err or f"kubectl exited with code {proc.returncode}")
+
+    return stdout.decode(errors="replace").strip()
+
+
+async def kubectl_json(
+    args: Sequence[str],
+    *,
+    context: str | None = None,
+    namespace: str | None = None,
+    all_namespaces: bool = False,
+) -> dict | list:
+    """Run kubectl with -o json and parse the result."""
+    output = await kubectl(
+        list(args) + ["-o", "json"],
+        context=context,
+        namespace=namespace,
+        all_namespaces=all_namespaces,
+    )
+    return json.loads(output)
+
+
+async def kubectl_stdin(
+    args: Sequence[str],
+    stdin_data: str,
+    *,
+    context: str | None = None,
+    namespace: str | None = None,
+) -> str:
+    """Run kubectl with data piped to stdin (e.g. apply -f -)."""
+    full_args = _build_args(args, context=context, namespace=namespace)
+
+    proc = await asyncio.create_subprocess_exec(
+        "kubectl",
+        *full_args,
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    try:
+        stdout, stderr = await asyncio.wait_for(
+            proc.communicate(input=stdin_data.encode()),
+            timeout=KUBECTL_TIMEOUT,
+        )
+    except asyncio.TimeoutError:
+        proc.kill()
+        raise KubectlError(f"kubectl timed out after {KUBECTL_TIMEOUT}s")
+
+    if proc.returncode != 0:
+        err = stderr.decode(errors="replace").strip()
+        raise KubectlError(err or f"kubectl exited with code {proc.returncode}")
+
+    out = stdout.decode(errors="replace").strip()
+    err_out = stderr.decode(errors="replace").strip()
+    # kubectl apply prints useful info to stderr on success too
+    if err_out:
+        return f"{out}\n{err_out}".strip()
+    return out

claude_plugin_kubernetes-0.1.0/k8s_mcp/server.py

@@ -0,0 +1,93 @@
+"""
+Claude MCP Plugin — Kubernetes
+
+Exposes 21 tools across three categories:
+  • Awareness   (8) — cluster state, contexts, nodes, pods, services, events
+  • Diagnostics (6) — describe, logs, metrics, health scan, YAML export
+  • Remediation (7) — restart, scale, delete, rollback, apply, patch, node ops
+
+Run with:
+    python -m src.server
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+    CallToolResult,
+    ListToolsResult,
+    TextContent,
+)
+
+from k8s_mcp.tools.awareness import AWARENESS_HANDLERS, AWARENESS_TOOLS
+from k8s_mcp.tools.diagnostics import DIAGNOSTIC_HANDLERS, DIAGNOSTIC_TOOLS
+from k8s_mcp.tools.remediation import REMEDIATION_HANDLERS, REMEDIATION_TOOLS
+
+# ---------------------------------------------------------------------------
+# Server setup
+# ---------------------------------------------------------------------------
+
+server = Server("kubernetes")
+
+ALL_TOOLS = AWARENESS_TOOLS + DIAGNOSTIC_TOOLS + REMEDIATION_TOOLS
+
+ALL_HANDLERS: dict = {
+    **AWARENESS_HANDLERS,
+    **DIAGNOSTIC_HANDLERS,
+    **REMEDIATION_HANDLERS,
+}
+
+
+@server.list_tools()
+async def list_tools() -> ListToolsResult:
+    return ListToolsResult(tools=ALL_TOOLS)
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> CallToolResult:
+    args = arguments
+
+    handler = ALL_HANDLERS.get(name)
+    if handler is None:
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Unknown tool: {name}")],
+            isError=True,
+        )
+
+    try:
+        content = await handler(args)
+        return CallToolResult(content=content)
+    except Exception as exc:  # noqa: BLE001
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Unexpected error: {exc}")],
+            isError=True,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+async def _run() -> None:
+    print(
+        f"kubernetes MCP server starting — {len(ALL_TOOLS)} tools registered",
+        file=sys.stderr,
+    )
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options(),
+        )
+
+
+def main() -> None:
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()