whitecapdata-dev 0.1.1__tar.gz → 0.1.3__tar.gz

whitecapdata_dev-0.1.3/.dockerignore

@@ -0,0 +1,12 @@
+.git
+.github
+tests
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+dist
+build
+*.egg-info
+.venv
+.mypy_cache

{whitecapdata_dev-0.1.1 → whitecapdata_dev-0.1.3}/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## 0.1.3 (2026-09-23)
+
+### Fixed
+
+* Constrain MCP below version 2 so fresh installations retain the supported FastMCP API.
+
+## [0.1.2] - 2026-06-22
+
+### Added
+- `Dockerfile` and `.dockerignore` for running the server as a container (MCP over stdio).
+
+### Changed
+- Enriched every tool docstring and documented all parameters for clearer agent tool-selection.
+
 ## [0.1.0] - 2026-06-20
 
 ### Added

whitecapdata_dev-0.1.3/Dockerfile

@@ -0,0 +1,29 @@
+# syntax=docker/dockerfile:1
+# Container image for the WhiteCapData-Dev (k3s / Kubernetes) MCP server.
+#
+# The server speaks MCP (JSON-RPC) over stdio and talks to your cluster through a
+# mounted kubeconfig. Run interactively (-i), mounting your kubeconfig read-only:
+#
+#   docker build -t whitecapdata-dev .
+#   docker run --rm -i \
+#     -v "$HOME/.kube/config:/home/app/.kube/config:ro" \
+#     -e HOMELAB_MCP_READONLY=1 \
+#     whitecapdata-dev
+#
+# Set HOMELAB_MCP_READONLY=1 to disable all mutating tools (recommended for a
+# first run). See the README for the full environment-variable reference.
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    KUBECONFIG=/home/app/.kube/config
+
+WORKDIR /app
+COPY . /app
+RUN pip install . \
+    && useradd --create-home --uid 10001 app
+
+USER app
+
+ENTRYPOINT ["whitecapdata-dev"]

{whitecapdata_dev-0.1.1 → whitecapdata_dev-0.1.3}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: whitecapdata-dev
-Version: 0.1.1
-Summary: WhiteCapData-Dev — an MCP server to operate a k3s / Kubernetes cluster (health, logs, and guarded restart/scale/delete) straight from your AI agent.
+Version: 0.1.3
+Summary: WhiteCapData-Dev — an MCP server to operate a k3s / Kubernetes cluster (health, logs, and guarded restart/scale/delete) straight from your AI agent.
 Project-URL: Homepage, https://github.com/Michael-WhiteCapData/WhiteCapData-Dev
 Project-URL: Repository, https://github.com/Michael-WhiteCapData/WhiteCapData-Dev
 Project-URL: Issues, https://github.com/Michael-WhiteCapData/WhiteCapData-Dev/issues
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.11
 Requires-Dist: kubernetes>=29
-Requires-Dist: mcp>=1.2
+Requires-Dist: mcp<2,>=1.2
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=5; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
@@ -89,6 +89,19 @@ claude mcp add homelab -- uvx whitecapdata-dev
 }
 ```
 
+## Run with Docker
+
+A [`Dockerfile`](Dockerfile) is included. The server speaks MCP over stdio and reaches
+your cluster through a mounted kubeconfig. Run interactively (`-i`), starting read-only:
+
+```bash
+docker build -t whitecapdata-dev .
+docker run --rm -i \
+  -v "$HOME/.kube/config:/home/app/.kube/config:ro" \
+  -e HOMELAB_MCP_READONLY=1 \
+  whitecapdata-dev
+```
+
 ## Tools
 
 | Tool | Kind | Description |

{whitecapdata_dev-0.1.1 → whitecapdata_dev-0.1.3}/README.md

@@ -62,6 +62,19 @@ claude mcp add homelab -- uvx whitecapdata-dev
 }
 ```
 
+## Run with Docker
+
+A [`Dockerfile`](Dockerfile) is included. The server speaks MCP over stdio and reaches
+your cluster through a mounted kubeconfig. Run interactively (`-i`), starting read-only:
+
+```bash
+docker build -t whitecapdata-dev .
+docker run --rm -i \
+  -v "$HOME/.kube/config:/home/app/.kube/config:ro" \
+  -e HOMELAB_MCP_READONLY=1 \
+  whitecapdata-dev
+```
+
 ## Tools
 
 | Tool | Kind | Description |

{whitecapdata_dev-0.1.1 → whitecapdata_dev-0.1.3}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "whitecapdata-dev"
-version = "0.1.1"
-description = "WhiteCapData-Dev — an MCP server to operate a k3s / Kubernetes cluster (health, logs, and guarded restart/scale/delete) straight from your AI agent."
+version = "0.1.3"
+description = "WhiteCapData-Dev — an MCP server to operate a k3s / Kubernetes cluster (health, logs, and guarded restart/scale/delete) straight from your AI agent."
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.11"
@@ -21,7 +21,7 @@ classifiers = [
     "Topic :: System :: Systems Administration",
 ]
 dependencies = [
-    "mcp>=1.2",
+    "mcp>=1.2,<2",
     "kubernetes>=29",
 ]
 

{whitecapdata_dev-0.1.1 → whitecapdata_dev-0.1.3}/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "io.github.Michael-WhiteCapData/WhiteCapData-Dev",
-  "description": "Operate a k3s / Kubernetes cluster from an MCP client — health, logs, and guarded restart/scale/delete, safe by default.",
+  "description": "Operate a k3s / Kubernetes cluster from your AI agent — safe-by-default MCP server.",
   "repository": {
     "url": "https://github.com/Michael-WhiteCapData/WhiteCapData-Dev",
     "source": "github"
   },
-  "version": "0.1.1",
+  "version": "0.1.3",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "whitecapdata-dev",
-      "version": "0.1.1",
+      "version": "0.1.3",
       "transport": { "type": "stdio" },
       "environmentVariables": [
         {

whitecapdata_dev-0.1.3/src/homelab_mcp/__init__.py

@@ -0,0 +1,12 @@
+"""homelab-mcp — operate a k3s / Kubernetes cluster from an MCP client.
+
+Exposes read and (guarded) write tools over the Kubernetes API so an agent
+(Claude Code, Claude Desktop, Cursor, …) can inspect cluster health and perform
+safe, allowlisted operations — without shelling out to kubectl.
+"""
+
+from .config import Config
+from .kube import HomelabMCPError, KubeClient
+
+__all__ = ["Config", "KubeClient", "HomelabMCPError", "__version__"]
+__version__ = "0.1.3"

whitecapdata_dev-0.1.3/src/homelab_mcp/server.py

@@ -0,0 +1,227 @@
+"""The homelab-mcp MCP server.
+
+Tools return JSON strings so the calling agent gets structured, compact data.
+Reads are always available; mutations are gated by the operator's config
+(read-only switch + namespace allowlist) enforced in :class:`KubeClient`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated, Any
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+from .config import Config
+from .kube import KubeClient
+
+mcp = FastMCP("homelab")
+
+_client: KubeClient | None = None
+
+
+def get_client() -> KubeClient:
+    """Lazily build the cluster client (so import never touches a cluster)."""
+    global _client
+    if _client is None:
+        _client = KubeClient(Config.from_env())
+    return _client
+
+
+def set_client(client: KubeClient) -> None:
+    """Replace the module-level client (used by tests)."""
+    global _client
+    _client = client
+
+
+def _json(data: Any) -> str:
+    return json.dumps(data, indent=2, default=str)
+
+
+# -- reads -------------------------------------------------------------------
+
+
+@mcp.tool()
+def cluster_summary() -> str:
+    """Summarize overall cluster health in a single call.
+
+    Start here when triaging a cluster: it returns node and pod totals plus the
+    full list of unhealthy pods, giving the fastest picture of what is wrong
+    before drilling in with `list_pods`, `pod_logs`, or `node_health`. Read-only.
+    Returns a JSON object with node counts, pod phase totals, and unhealthy-pod
+    details (name, namespace, phase, restart count).
+    """
+    return _json(get_client().cluster_summary())
+
+
+@mcp.tool()
+def list_pods(
+    namespace: Annotated[
+        str,
+        Field(
+            description="Restrict the listing to this namespace. Empty string "
+            "(the default) lists pods across all namespaces."
+        ),
+    ] = "",
+) -> str:
+    """List pods with phase, restart count, and node, unhealthy pods sorted first.
+
+    Use after `cluster_summary` to enumerate pods, optionally scoped to one
+    namespace, then feed a pod name into `pod_logs`. Read-only. Returns a JSON
+    array of pod objects.
+    """
+    return _json(get_client().list_pods(namespace))
+
+
+@mcp.tool()
+def list_deployments(
+    namespace: Annotated[
+        str,
+        Field(
+            description="Restrict the listing to this namespace. Empty string "
+            "(the default) lists deployments across all namespaces."
+        ),
+    ] = "",
+) -> str:
+    """List deployments with their ready/desired replica counts and namespace.
+
+    Use to check rollout health or to find a deployment to `restart_deployment`
+    or `scale_deployment`. A deployment whose ready count is below its desired
+    count is still rolling out or degraded. Read-only. Returns a JSON array.
+    """
+    return _json(get_client().list_deployments(namespace))
+
+
+@mcp.tool()
+def list_events(
+    limit: Annotated[
+        int,
+        Field(description="Maximum number of recent events to return, newest first."),
+    ] = 30,
+) -> str:
+    """Return recent cluster events, most relevant first (Warnings before Normal).
+
+    Use to find out *why* something is unhealthy: scheduling failures, image-pull
+    errors, failed probes, and OOM kills all surface here. Pair this with
+    `cluster_summary` when a pod is failing but the reason is not obvious.
+    Read-only. Returns a JSON array of up to `limit` events.
+    """
+    return _json(get_client().list_events(limit))
+
+
+@mcp.tool()
+def pod_logs(
+    namespace: Annotated[str, Field(description="Namespace the pod runs in, e.g. 'kube-system'.")],
+    pod: Annotated[str, Field(description="Exact pod name, as shown by `list_pods`.")],
+    tail: Annotated[
+        int,
+        Field(description="Number of log lines to return from the end of the stream."),
+    ] = 200,
+) -> str:
+    """Return the last `tail` lines of a single pod's logs as plain text.
+
+    Use this to investigate a specific pod after `cluster_summary` or `list_pods`
+    flags it as unhealthy (CrashLoopBackOff, restarts, errors). Reads the current
+    container's stdout/stderr only — it does not follow/stream or fetch
+    previous-container logs. Returns the raw log text, or an error message if the
+    pod or namespace does not exist.
+    """
+    return get_client().pod_logs(namespace, pod, tail)
+
+
+@mcp.tool()
+def node_health() -> str:
+    """Report per-node readiness, kubelet version, capacity, and pressure conditions.
+
+    Use to diagnose node-level problems — NotReady nodes, or memory/disk/PID
+    pressure — when pods are stuck Pending or being evicted. Read-only. Returns a
+    JSON array with one object per node.
+    """
+    return _json(get_client().node_health())
+
+
+# -- mutations (guarded by read-only + namespace allowlist) ------------------
+
+
+@mcp.tool()
+def restart_deployment(
+    namespace: Annotated[
+        str,
+        Field(
+            description="Namespace of the deployment; must be in the operator's mutable-namespace allowlist."
+        ),
+    ],
+    name: Annotated[str, Field(description="Name of the deployment to restart.")],
+) -> str:
+    """Trigger a rolling restart of a deployment (like `kubectl rollout restart`).
+
+    Use to recycle a deployment's pods after a config/secret change or to clear a
+    stuck state, without changing the replica count. Mutating: rejected unless
+    read-only mode is off and the namespace is in the mutable-namespace allowlist.
+    Returns a JSON status object describing the triggered rollout.
+    """
+    return get_client().restart_deployment(namespace, name)
+
+
+@mcp.tool()
+def scale_deployment(
+    namespace: Annotated[
+        str,
+        Field(
+            description="Namespace of the deployment; must be in the operator's mutable-namespace allowlist."
+        ),
+    ],
+    name: Annotated[str, Field(description="Name of the deployment to scale.")],
+    replicas: Annotated[
+        int,
+        Field(description="Target replica count, from 0 up to the operator's configured maximum."),
+    ],
+) -> str:
+    """Scale a deployment to a specific replica count.
+
+    Use to manually scale a workload up or down. Mutating: rejected unless
+    read-only mode is off, the namespace is allowlisted, and `replicas` is within
+    the operator's configured 0..max bound. Returns a JSON status object with the
+    applied replica count.
+    """
+    return get_client().scale_deployment(namespace, name, replicas)
+
+
+@mcp.tool()
+def delete_pod(
+    namespace: Annotated[
+        str,
+        Field(description="Namespace of the pod; must be in the operator's mutable-namespace allowlist."),
+    ],
+    name: Annotated[str, Field(description="Name of the pod to delete.")],
+) -> str:
+    """Delete a single pod so its controller recreates it.
+
+    Use to force-recreate a wedged pod (managed by a Deployment, StatefulSet,
+    etc.) without restarting the whole deployment. Mutating: rejected unless
+    read-only mode is off and the namespace is allowlisted. Returns a JSON status
+    object.
+    """
+    return get_client().delete_pod(namespace, name)
+
+
+@mcp.tool()
+def server_info() -> str:
+    """Report the server's effective configuration.
+
+    Returns the target kube context, the read-only flag, the mutable-namespace
+    allowlist, and the maximum replica bound. Use this to confirm what the server
+    is permitted to do before attempting a mutation, or to understand why a
+    mutating call was rejected. Read-only. Returns a JSON object.
+    """
+    return _json(get_client().config.as_dict())
+
+
+def main() -> None:
+    """Console-script entry point: run the server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

whitecapdata_dev-0.1.1/src/homelab_mcp/__init__.py

@@ -1,12 +0,0 @@
-"""homelab-mcp — operate a k3s / Kubernetes cluster from an MCP client.
-
-Exposes read and (guarded) write tools over the Kubernetes API so an agent
-(Claude Code, Claude Desktop, Cursor, …) can inspect cluster health and perform
-safe, allowlisted operations — without shelling out to kubectl.
-"""
-
-from .config import Config
-from .kube import HomelabMCPError, KubeClient
-
-__all__ = ["Config", "KubeClient", "HomelabMCPError", "__version__"]
-__version__ = "0.1.1"

whitecapdata_dev-0.1.1/src/homelab_mcp/server.py

@@ -1,113 +0,0 @@
-"""The homelab-mcp MCP server.
-
-Tools return JSON strings so the calling agent gets structured, compact data.
-Reads are always available; mutations are gated by the operator's config
-(read-only switch + namespace allowlist) enforced in :class:`KubeClient`.
-"""
-
-from __future__ import annotations
-
-import json
-from typing import Any
-
-from mcp.server.fastmcp import FastMCP
-
-from .config import Config
-from .kube import KubeClient
-
-mcp = FastMCP("homelab")
-
-_client: KubeClient | None = None
-
-
-def get_client() -> KubeClient:
-    """Lazily build the cluster client (so import never touches a cluster)."""
-    global _client
-    if _client is None:
-        _client = KubeClient(Config.from_env())
-    return _client
-
-
-def set_client(client: KubeClient) -> None:
-    """Replace the module-level client (used by tests)."""
-    global _client
-    _client = client
-
-
-def _json(data: Any) -> str:
-    return json.dumps(data, indent=2, default=str)
-
-
-# -- reads -------------------------------------------------------------------
-
-
-@mcp.tool()
-def cluster_summary() -> str:
-    """Node and pod health totals plus the list of unhealthy pods. Start here."""
-    return _json(get_client().cluster_summary())
-
-
-@mcp.tool()
-def list_pods(namespace: str = "") -> str:
-    """List pods (optionally one namespace). Unhealthy pods sort first."""
-    return _json(get_client().list_pods(namespace))
-
-
-@mcp.tool()
-def list_deployments(namespace: str = "") -> str:
-    """List deployments with ready/desired replica counts."""
-    return _json(get_client().list_deployments(namespace))
-
-
-@mcp.tool()
-def list_events(limit: int = 30) -> str:
-    """Recent cluster events; Warning-type events sort first."""
-    return _json(get_client().list_events(limit))
-
-
-@mcp.tool()
-def pod_logs(namespace: str, pod: str, tail: int = 200) -> str:
-    """Tail a pod's logs."""
-    return get_client().pod_logs(namespace, pod, tail)
-
-
-@mcp.tool()
-def node_health() -> str:
-    """Per-node readiness, kubelet version, capacity, and pressure conditions."""
-    return _json(get_client().node_health())
-
-
-# -- mutations (guarded by read-only + namespace allowlist) ------------------
-
-
-@mcp.tool()
-def restart_deployment(namespace: str, name: str) -> str:
-    """Rollout-restart a deployment (subject to the mutable-namespace allowlist)."""
-    return get_client().restart_deployment(namespace, name)
-
-
-@mcp.tool()
-def scale_deployment(namespace: str, name: str, replicas: int) -> str:
-    """Scale a deployment to N replicas (0..max), subject to the allowlist."""
-    return get_client().scale_deployment(namespace, name, replicas)
-
-
-@mcp.tool()
-def delete_pod(namespace: str, name: str) -> str:
-    """Delete a pod so its controller recreates it (subject to the allowlist)."""
-    return get_client().delete_pod(namespace, name)
-
-
-@mcp.tool()
-def server_info() -> str:
-    """Report the effective configuration (context, read-only, allowlist)."""
-    return _json(get_client().config.as_dict())
-
-
-def main() -> None:
-    """Console-script entry point: run the server over stdio."""
-    mcp.run()
-
-
-if __name__ == "__main__":
-    main()