helm-mcp 0.1.3__tar.gz

helm_mcp-0.1.3/.gitignore

@@ -0,0 +1,38 @@
+# Go build output (root-level binary only)
+/helm-mcp
+/helm-mcp-*
+coverage.out
+coverage.html
+*.exe
+vendor/
+
+# Coverage reports
+python_coverage*.xml
+python/.coverage
+
+# Python
+python/.venv/
+python/dist/
+python/build/
+python/*.egg-info/
+python/src/*.egg-info/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+
+# IDE / Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# OS
+Thumbs.db
+
+# Environment
+.env
+.env.local

helm_mcp-0.1.3/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: helm-mcp
+Version: 0.1.3
+Summary: MCP server exposing all Helm CLI capabilities via the Model Context Protocol
+Project-URL: Homepage, https://github.com/SCGIS-Wales/helm-mcp
+Project-URL: Repository, https://github.com/SCGIS-Wales/helm-mcp
+Project-URL: Issues, https://github.com/SCGIS-Wales/helm-mcp/issues
+Project-URL: Documentation, https://github.com/SCGIS-Wales/helm-mcp#python-package
+Project-URL: Changelog, https://github.com/SCGIS-Wales/helm-mcp/releases
+Author: sreengineer
+License-Expression: MIT
+Keywords: ai-tools,fastmcp,helm,kubernetes,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: fastmcp>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# helm-mcp (Python)
+
+A Python MCP wrapper for the [helm-mcp](https://github.com/ssddgreg/helm-mcp) Go server.
+
+Uses [FastMCP](https://github.com/PrefectHQ/fastmcp) to create a transparent proxy around the helm-mcp Go binary, exposing all Helm tools via the Model Context Protocol. **New tools added to the Go binary are automatically available without any Python code changes.**
+
+## Requirements
+
+- Python 3.14+
+- The `helm-mcp` Go binary on your `PATH` or pointed to via `HELM_MCP_BINARY`
+
+## Installation
+
+```bash
+pip install helm-mcp
+```
+
+## Quick Start
+
+### As a server
+
+```python
+from helm_mcp import create_server
+
+server = create_server()
+server.run()  # stdio mode (default)
+```
+
+### As a client
+
+```python
+import asyncio
+from helm_mcp import create_client
+
+async def main():
+    async with create_client() as client:
+        tools = await client.list_tools()
+        print(f"Available tools: {len(tools)}")
+
+        result = await client.call_tool("helm_list", {"namespace": "default"})
+        print(result)
+
+asyncio.run(main())
+```
+
+### CLI
+
+```bash
+# stdio mode (default, for MCP clients like Claude Code)
+helm-mcp-python
+
+# HTTP mode
+helm-mcp-python --transport http --host 0.0.0.0 --port 8080
+
+# Explicit binary path
+helm-mcp-python --binary /usr/local/bin/helm-mcp
+```
+
+## Binary Discovery
+
+The package locates the `helm-mcp` Go binary in this order:
+
+1. `HELM_MCP_BINARY` environment variable
+2. Bundled binary in the package `bin/` directory
+3. `helm-mcp` on `PATH`
+
+## Environment Variables
+
+The proxy forwards these environment variables to the Go binary:
+
+| Category | Variables |
+|----------|-----------|
+| Proxy | `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` (and lowercase variants) |
+| Kubernetes | `KUBECONFIG`, `KUBERNETES_SERVICE_HOST`, `KUBERNETES_SERVICE_PORT` |
+| Helm | `HELM_CACHE_HOME`, `HELM_CONFIG_HOME`, `HELM_DATA_HOME`, `HELM_PLUGINS`, `HELM_DEBUG` |
+| AWS | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`, `AWS_PROFILE` |
+| GCP | `GOOGLE_APPLICATION_CREDENTIALS`, `CLOUDSDK_COMPUTE_ZONE` |
+| Azure | `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID` |
+| TLS | `SSL_CERT_FILE`, `SSL_CERT_DIR` |
+
+## Scalability
+
+This package uses the MCP proxy pattern: the Python layer never needs to know about individual Helm tools. All tool discovery, input schemas, and invocations are forwarded to the Go binary via the MCP protocol at runtime. When new capabilities are added to the Go server, they are immediately available through the Python wrapper.
+
+## License
+
+MIT

helm_mcp-0.1.3/README.md

@@ -0,0 +1,87 @@
+# helm-mcp (Python)
+
+A Python MCP wrapper for the [helm-mcp](https://github.com/ssddgreg/helm-mcp) Go server.
+
+Uses [FastMCP](https://github.com/PrefectHQ/fastmcp) to create a transparent proxy around the helm-mcp Go binary, exposing all Helm tools via the Model Context Protocol. **New tools added to the Go binary are automatically available without any Python code changes.**
+
+## Requirements
+
+- Python 3.14+
+- The `helm-mcp` Go binary on your `PATH` or pointed to via `HELM_MCP_BINARY`
+
+## Installation
+
+```bash
+pip install helm-mcp
+```
+
+## Quick Start
+
+### As a server
+
+```python
+from helm_mcp import create_server
+
+server = create_server()
+server.run()  # stdio mode (default)
+```
+
+### As a client
+
+```python
+import asyncio
+from helm_mcp import create_client
+
+async def main():
+    async with create_client() as client:
+        tools = await client.list_tools()
+        print(f"Available tools: {len(tools)}")
+
+        result = await client.call_tool("helm_list", {"namespace": "default"})
+        print(result)
+
+asyncio.run(main())
+```
+
+### CLI
+
+```bash
+# stdio mode (default, for MCP clients like Claude Code)
+helm-mcp-python
+
+# HTTP mode
+helm-mcp-python --transport http --host 0.0.0.0 --port 8080
+
+# Explicit binary path
+helm-mcp-python --binary /usr/local/bin/helm-mcp
+```
+
+## Binary Discovery
+
+The package locates the `helm-mcp` Go binary in this order:
+
+1. `HELM_MCP_BINARY` environment variable
+2. Bundled binary in the package `bin/` directory
+3. `helm-mcp` on `PATH`
+
+## Environment Variables
+
+The proxy forwards these environment variables to the Go binary:
+
+| Category | Variables |
+|----------|-----------|
+| Proxy | `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` (and lowercase variants) |
+| Kubernetes | `KUBECONFIG`, `KUBERNETES_SERVICE_HOST`, `KUBERNETES_SERVICE_PORT` |
+| Helm | `HELM_CACHE_HOME`, `HELM_CONFIG_HOME`, `HELM_DATA_HOME`, `HELM_PLUGINS`, `HELM_DEBUG` |
+| AWS | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`, `AWS_PROFILE` |
+| GCP | `GOOGLE_APPLICATION_CREDENTIALS`, `CLOUDSDK_COMPUTE_ZONE` |
+| Azure | `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID` |
+| TLS | `SSL_CERT_FILE`, `SSL_CERT_DIR` |
+
+## Scalability
+
+This package uses the MCP proxy pattern: the Python layer never needs to know about individual Helm tools. All tool discovery, input schemas, and invocations are forwarded to the Go binary via the MCP protocol at runtime. When new capabilities are added to the Go server, they are immediately available through the Python wrapper.
+
+## License
+
+MIT

helm_mcp-0.1.3/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "helm-mcp"
+version = "0.1.3"
+description = "MCP server exposing all Helm CLI capabilities via the Model Context Protocol"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+authors = [
+    { name = "sreengineer" },
+]
+keywords = ["helm", "kubernetes", "mcp", "model-context-protocol", "fastmcp", "ai-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Systems Administration",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastmcp>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/SCGIS-Wales/helm-mcp"
+Repository = "https://github.com/SCGIS-Wales/helm-mcp"
+Issues = "https://github.com/SCGIS-Wales/helm-mcp/issues"
+Documentation = "https://github.com/SCGIS-Wales/helm-mcp#python-package"
+Changelog = "https://github.com/SCGIS-Wales/helm-mcp/releases"
+
+[project.scripts]
+helm-mcp-python = "helm_mcp.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/helm_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/helm_mcp/",
+    "tests/",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B", "SIM"]

helm_mcp-0.1.3/src/helm_mcp/__init__.py

@@ -0,0 +1,27 @@
+"""helm-mcp: A Python MCP wrapper for the Helm MCP server.
+
+This package provides a FastMCP proxy that wraps the helm-mcp Go binary,
+automatically exposing all Helm tools via the Model Context Protocol.
+
+The proxy pattern means this package requires zero code changes when new
+tools are added to the Go binary — they are discovered and forwarded
+automatically at runtime via the MCP protocol.
+
+Usage as a server:
+    from helm_mcp import create_server
+    server = create_server()
+    server.run()
+
+Usage as a client:
+    from helm_mcp import create_client
+    async with create_client() as client:
+        tools = await client.list_tools()
+        result = await client.call_tool("helm_list", {"namespace": "default"})
+"""
+
+__version__ = "0.1.3"
+
+from helm_mcp.client import create_client
+from helm_mcp.server import create_server
+
+__all__ = ["create_server", "create_client", "__version__"]

helm_mcp-0.1.3/src/helm_mcp/cli.py

@@ -0,0 +1,51 @@
+"""CLI entry point for helm-mcp-python."""
+
+import argparse
+import sys
+
+
+def main() -> None:
+    """Run the helm-mcp proxy server."""
+    parser = argparse.ArgumentParser(
+        description="helm-mcp: MCP server for Helm operations",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "http", "sse"],
+        default="stdio",
+        help="Transport mode (default: stdio)",
+    )
+    parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="Host for HTTP/SSE mode (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        help="Port for HTTP/SSE mode (default: 8080)",
+    )
+    parser.add_argument(
+        "--binary",
+        default=None,
+        help="Path to helm-mcp Go binary (auto-detected if not set)",
+    )
+    args = parser.parse_args()
+
+    from helm_mcp.server import create_server
+
+    try:
+        server = create_server(binary_path=args.binary)
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.transport == "stdio":
+        server.run()
+    else:
+        server.run(transport=args.transport, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

helm_mcp-0.1.3/src/helm_mcp/client.py

@@ -0,0 +1,40 @@
+"""FastMCP client for connecting to the helm-mcp Go binary.
+
+Provides a thin client wrapper that connects to the Go binary via stdio
+transport. All tool discovery is handled by the MCP protocol at runtime,
+so new tools added to the binary are automatically available.
+"""
+
+from fastmcp import Client
+from fastmcp.client.transports import StdioTransport
+
+from helm_mcp.server import _build_subprocess_env, _find_binary
+
+
+def create_client(
+    binary_path: str | None = None,
+    env: dict[str, str] | None = None,
+) -> Client:
+    """Create a FastMCP client connected to the helm-mcp Go binary via stdio.
+
+    Args:
+        binary_path: Explicit path to the helm-mcp binary. Auto-detected if ``None``.
+        env: Additional environment variables to pass to the subprocess.
+
+    Returns:
+        A FastMCP ``Client`` instance. Use as an async context manager.
+
+    Example::
+
+        async with create_client() as client:
+            tools = await client.list_tools()
+            result = await client.call_tool("helm_list", {"namespace": "default"})
+    """
+    binary = binary_path or _find_binary()
+    subprocess_env = _build_subprocess_env(extra_env=env)
+    transport = StdioTransport(
+        command=binary,
+        args=["--mode", "stdio"],
+        env=subprocess_env or None,
+    )
+    return Client(transport)

helm_mcp-0.1.3/src/helm_mcp/server.py

@@ -0,0 +1,187 @@
+"""FastMCP proxy server wrapping the helm-mcp Go binary.
+
+The proxy pattern ensures forward-compatibility: when new tools are added
+to the Go binary, they are automatically discovered and exposed by the
+proxy without any Python code changes. The MCP protocol handles tool
+discovery at runtime via the ``tools/list`` method.
+"""
+
+import os
+import platform
+import shutil
+from pathlib import Path
+
+from fastmcp.client.transports import StdioTransport
+from fastmcp.server import create_proxy
+
+# Environment variables forwarded to the Go subprocess.
+# Extend this list to pass additional variables — the proxy itself
+# never needs to know about individual Helm tools.
+PASSTHROUGH_ENV_VARS: list[str] = [
+    # Core system
+    "HOME",
+    "USER",
+    "PATH",
+    # Kubernetes
+    "KUBECONFIG",
+    "KUBERNETES_SERVICE_HOST",
+    "KUBERNETES_SERVICE_PORT",
+    # Forward proxy
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+    # Helm-specific
+    "HELM_CACHE_HOME",
+    "HELM_CONFIG_HOME",
+    "HELM_DATA_HOME",
+    "HELM_DRIVER",
+    "HELM_REGISTRY_CONFIG",
+    "HELM_REPOSITORY_CACHE",
+    "HELM_REPOSITORY_CONFIG",
+    "HELM_PLUGINS",
+    "HELM_DEBUG",
+    # AWS (EKS)
+    "AWS_ACCESS_KEY_ID",
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "AWS_DEFAULT_REGION",
+    "AWS_REGION",
+    "AWS_PROFILE",
+    "AWS_SHARED_CREDENTIALS_FILE",
+    "AWS_CONFIG_FILE",
+    # Google Cloud (GKE)
+    "GOOGLE_APPLICATION_CREDENTIALS",
+    "CLOUDSDK_COMPUTE_ZONE",
+    "CLOUDSDK_COMPUTE_REGION",
+    "CLOUDSDK_CORE_PROJECT",
+    # Azure (AKS)
+    "AZURE_TENANT_ID",
+    "AZURE_CLIENT_ID",
+    "AZURE_CLIENT_SECRET",
+    "AZURE_SUBSCRIPTION_ID",
+    "AZURE_AUTHORITY_HOST",
+    # TLS / CA
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+    "REQUESTS_CA_BUNDLE",
+]
+
+
+def _find_binary() -> str:
+    """Locate the helm-mcp binary.
+
+    Search order:
+      1. ``HELM_MCP_BINARY`` environment variable
+      2. Bundled binary in the package ``bin/`` directory
+      3. ``helm-mcp`` on ``PATH``
+
+    Returns:
+        Absolute path to the helm-mcp executable.
+
+    Raises:
+        FileNotFoundError: If the binary cannot be located.
+    """
+    # 1. Explicit env var
+    env_path = os.environ.get("HELM_MCP_BINARY")
+    if env_path:
+        p = Path(env_path)
+        if p.is_file() and os.access(str(p), os.X_OK):
+            return str(p)
+        raise FileNotFoundError(f"HELM_MCP_BINARY={env_path} does not exist or is not executable")
+
+    # 2. Bundled binary in package data
+    pkg_dir = Path(__file__).parent
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    arch_map = {"x86_64": "amd64", "aarch64": "arm64", "arm64": "arm64", "amd64": "amd64"}
+    arch = arch_map.get(machine, machine)
+    binary_name = f"helm-mcp-{system}-{arch}"
+    if system == "windows":
+        binary_name += ".exe"
+    bundled = pkg_dir / "bin" / binary_name
+    if bundled.is_file() and os.access(str(bundled), os.X_OK):
+        return str(bundled)
+
+    # Also check for plain "helm-mcp" in bin/
+    plain = pkg_dir / "bin" / "helm-mcp"
+    if plain.is_file() and os.access(str(plain), os.X_OK):
+        return str(plain)
+
+    # 3. PATH lookup
+    found = shutil.which("helm-mcp")
+    if found:
+        return found
+
+    raise FileNotFoundError(
+        "helm-mcp binary not found. Either:\n"
+        "  1. Set HELM_MCP_BINARY=/path/to/helm-mcp\n"
+        "  2. Install helm-mcp and ensure it's on your PATH\n"
+        "  3. Install the platform-specific wheel (pip install helm-mcp[binary])"
+    )
+
+
+def _build_subprocess_env(
+    extra_env: dict[str, str] | None = None,
+    passthrough: list[str] | None = None,
+) -> dict[str, str]:
+    """Build the environment dict for the Go subprocess.
+
+    Collects variables from ``PASSTHROUGH_ENV_VARS`` (or a custom list)
+    and merges in any extra overrides.
+
+    Args:
+        extra_env: Additional variables that take precedence.
+        passthrough: Override the default passthrough list.
+
+    Returns:
+        Environment dict for subprocess execution.
+    """
+    vars_to_pass = passthrough or PASSTHROUGH_ENV_VARS
+    env: dict[str, str] = {}
+    for var in vars_to_pass:
+        val = os.environ.get(var)
+        if val is not None:
+            env[var] = val
+    if extra_env:
+        env.update(extra_env)
+    return env
+
+
+def create_server(
+    binary_path: str | None = None,
+    name: str = "helm-mcp",
+    env: dict[str, str] | None = None,
+):
+    """Create a FastMCP proxy server wrapping the helm-mcp Go binary.
+
+    The proxy transparently forwards all MCP requests to the Go binary,
+    which means any new tools added to the binary are automatically
+    available without changing this Python code.
+
+    Args:
+        binary_path: Explicit path to the helm-mcp binary. Auto-detected if ``None``.
+        name: Server name advertised via MCP.
+        env: Additional environment variables to pass to the subprocess.
+            These are merged on top of the default passthrough list
+            (``PASSTHROUGH_ENV_VARS``).
+
+    Returns:
+        A FastMCP server instance ready to run.
+
+    Example::
+
+        server = create_server()
+        server.run()                                       # stdio
+        server.run(transport="http", host="0.0.0.0", port=8080)  # HTTP
+    """
+    binary = binary_path or _find_binary()
+    subprocess_env = _build_subprocess_env(extra_env=env)
+    transport = StdioTransport(
+        command=binary,
+        args=["--mode", "stdio"],
+        env=subprocess_env or None,
+    )
+    return create_proxy(transport, name=name)

helm_mcp-0.1.3/tests/test_server.py

@@ -0,0 +1,505 @@
+"""Tests for helm_mcp server and client modules."""
+
+import os
+import platform
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Package metadata
+# ---------------------------------------------------------------------------
+
+
+def test_version():
+    """Test package version is set."""
+    from helm_mcp import __version__
+
+    assert __version__  # version is set (value managed by auto-tag)
+
+
+def test_exports():
+    """Test that public API is properly exported."""
+    import helm_mcp
+
+    assert hasattr(helm_mcp, "create_server")
+    assert hasattr(helm_mcp, "create_client")
+    assert hasattr(helm_mcp, "__version__")
+    assert callable(helm_mcp.create_server)
+    assert callable(helm_mcp.create_client)
+
+
+def test_all_exports():
+    """Test __all__ matches expected exports."""
+    import helm_mcp
+
+    assert set(helm_mcp.__all__) == {"create_server", "create_client", "__version__"}
+
+
+def test_py_typed_marker():
+    """Test PEP 561 py.typed marker exists."""
+    import helm_mcp
+
+    pkg_dir = Path(helm_mcp.__file__).parent
+    assert (pkg_dir / "py.typed").exists()
+
+
+# ---------------------------------------------------------------------------
+# Binary discovery
+# ---------------------------------------------------------------------------
+
+
+def test_find_binary_env_var(tmp_path):
+    """Test binary discovery via HELM_MCP_BINARY env var."""
+    from helm_mcp.server import _find_binary
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("#!/bin/sh\necho hello")
+    fake_binary.chmod(0o755)
+
+    with patch.dict(os.environ, {"HELM_MCP_BINARY": str(fake_binary)}):
+        result = _find_binary()
+        assert result == str(fake_binary)
+
+
+def test_find_binary_env_var_not_found():
+    """Test error when HELM_MCP_BINARY points to nonexistent file."""
+    from helm_mcp.server import _find_binary
+
+    with (
+        patch.dict(os.environ, {"HELM_MCP_BINARY": "/nonexistent/helm-mcp"}),
+        pytest.raises(FileNotFoundError, match="HELM_MCP_BINARY"),
+    ):
+        _find_binary()
+
+
+def test_find_binary_env_var_not_executable(tmp_path):
+    """Test error when HELM_MCP_BINARY exists but is not executable."""
+    from helm_mcp.server import _find_binary
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("not executable")
+    fake_binary.chmod(0o644)
+
+    with (
+        patch.dict(os.environ, {"HELM_MCP_BINARY": str(fake_binary)}),
+        pytest.raises(FileNotFoundError, match="HELM_MCP_BINARY"),
+    ):
+        _find_binary()
+
+
+def test_find_binary_path_lookup(tmp_path):
+    """Test binary discovery via PATH."""
+    from helm_mcp.server import _find_binary
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("#!/bin/sh\necho hello")
+    fake_binary.chmod(0o755)
+
+    env = {k: v for k, v in os.environ.items() if k != "HELM_MCP_BINARY"}
+    env["PATH"] = f"{tmp_path}:{env.get('PATH', '')}"
+
+    with patch.dict(os.environ, env, clear=True):
+        result = _find_binary()
+        assert result == str(fake_binary)
+
+
+def test_find_binary_not_found():
+    """Test error when binary cannot be found."""
+    from helm_mcp.server import _find_binary
+
+    env = {k: v for k, v in os.environ.items() if k != "HELM_MCP_BINARY"}
+    env["PATH"] = "/nonexistent"
+
+    with (
+        patch.dict(os.environ, env, clear=True),
+        pytest.raises(FileNotFoundError, match="helm-mcp binary not found"),
+    ):
+        _find_binary()
+
+
+def test_find_binary_bundled(tmp_path):
+    """Test binary discovery from bundled bin/ directory."""
+    import helm_mcp.server as server_mod
+    from helm_mcp.server import _find_binary
+
+    pkg_dir = Path(server_mod.__file__).parent
+    bin_dir = pkg_dir / "bin"
+    bin_dir.mkdir(exist_ok=True)
+    bundled = bin_dir / "helm-mcp"
+    bundled.write_text("#!/bin/sh\necho hello")
+    bundled.chmod(0o755)
+
+    try:
+        env = {k: v for k, v in os.environ.items() if k != "HELM_MCP_BINARY"}
+        env["PATH"] = "/nonexistent"
+        with patch.dict(os.environ, env, clear=True):
+            result = _find_binary()
+            assert result == str(bundled)
+    finally:
+        bundled.unlink()
+        bin_dir.rmdir()
+
+
+def test_find_binary_bundled_platform_specific(tmp_path):
+    """Test platform-specific bundled binary discovery."""
+    import helm_mcp.server as server_mod
+    from helm_mcp.server import _find_binary
+
+    pkg_dir = Path(server_mod.__file__).parent
+    bin_dir = pkg_dir / "bin"
+    bin_dir.mkdir(exist_ok=True)
+
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    arch_map = {"x86_64": "amd64", "aarch64": "arm64", "arm64": "arm64", "amd64": "amd64"}
+    arch = arch_map.get(machine, machine)
+    binary_name = f"helm-mcp-{system}-{arch}"
+
+    bundled = bin_dir / binary_name
+    bundled.write_text("#!/bin/sh\necho hello")
+    bundled.chmod(0o755)
+
+    try:
+        env = {k: v for k, v in os.environ.items() if k != "HELM_MCP_BINARY"}
+        env["PATH"] = "/nonexistent"
+        with patch.dict(os.environ, env, clear=True):
+            result = _find_binary()
+            assert result == str(bundled)
+    finally:
+        bundled.unlink()
+        bin_dir.rmdir()
+
+
+# ---------------------------------------------------------------------------
+# Environment building
+# ---------------------------------------------------------------------------
+
+
+def test_build_subprocess_env_passthrough():
+    """Test that _build_subprocess_env forwards expected variables."""
+    from helm_mcp.server import _build_subprocess_env
+
+    test_vars = {
+        "HTTP_PROXY": "http://proxy:8080",
+        "HTTPS_PROXY": "http://proxy:8443",
+        "NO_PROXY": "localhost,.internal",
+        "KUBECONFIG": "/home/user/.kube/config",
+        "HOME": "/home/user",
+    }
+
+    with patch.dict(os.environ, test_vars, clear=True):
+        result = _build_subprocess_env()
+        assert result["HTTP_PROXY"] == "http://proxy:8080"
+        assert result["HTTPS_PROXY"] == "http://proxy:8443"
+        assert result["NO_PROXY"] == "localhost,.internal"
+        assert result["KUBECONFIG"] == "/home/user/.kube/config"
+        assert result["HOME"] == "/home/user"
+
+
+def test_build_subprocess_env_extra_overrides():
+    """Test that extra_env overrides passthrough values."""
+    from helm_mcp.server import _build_subprocess_env
+
+    with patch.dict(os.environ, {"HOME": "/home/user"}, clear=True):
+        result = _build_subprocess_env(extra_env={"HOME": "/override", "CUSTOM": "value"})
+        assert result["HOME"] == "/override"
+        assert result["CUSTOM"] == "value"
+
+
+def test_build_subprocess_env_custom_passthrough():
+    """Test _build_subprocess_env with a custom passthrough list."""
+    from helm_mcp.server import _build_subprocess_env
+
+    with patch.dict(os.environ, {"FOO": "bar", "HOME": "/home/user"}, clear=True):
+        result = _build_subprocess_env(passthrough=["FOO"])
+        assert result == {"FOO": "bar"}
+        assert "HOME" not in result
+
+
+def test_build_subprocess_env_skips_unset():
+    """Test that unset variables are not included."""
+    from helm_mcp.server import _build_subprocess_env
+
+    with patch.dict(os.environ, {}, clear=True):
+        result = _build_subprocess_env()
+        assert result == {}
+
+
+def test_build_subprocess_env_empty_extra():
+    """Test passing empty extra_env dict."""
+    from helm_mcp.server import _build_subprocess_env
+
+    with patch.dict(os.environ, {"HOME": "/home/user"}, clear=True):
+        result = _build_subprocess_env(extra_env={})
+        assert result["HOME"] == "/home/user"
+
+
+# ---------------------------------------------------------------------------
+# PASSTHROUGH_ENV_VARS completeness
+# ---------------------------------------------------------------------------
+
+
+def test_passthrough_env_vars_includes_proxy():
+    """Test that PASSTHROUGH_ENV_VARS includes all proxy variants."""
+    from helm_mcp.server import PASSTHROUGH_ENV_VARS
+
+    for var in ["HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy"]:
+        assert var in PASSTHROUGH_ENV_VARS, f"{var} missing from PASSTHROUGH_ENV_VARS"
+
+
+def test_passthrough_env_vars_includes_kubernetes():
+    """Test that PASSTHROUGH_ENV_VARS includes Kubernetes variables."""
+    from helm_mcp.server import PASSTHROUGH_ENV_VARS
+
+    for var in ["KUBECONFIG", "KUBERNETES_SERVICE_HOST", "KUBERNETES_SERVICE_PORT"]:
+        assert var in PASSTHROUGH_ENV_VARS, f"{var} missing from PASSTHROUGH_ENV_VARS"
+
+
+def test_passthrough_env_vars_includes_helm():
+    """Test that PASSTHROUGH_ENV_VARS includes Helm variables."""
+    from helm_mcp.server import PASSTHROUGH_ENV_VARS
+
+    for var in [
+        "HELM_CACHE_HOME",
+        "HELM_CONFIG_HOME",
+        "HELM_DATA_HOME",
+        "HELM_DRIVER",
+        "HELM_PLUGINS",
+        "HELM_DEBUG",
+    ]:
+        assert var in PASSTHROUGH_ENV_VARS, f"{var} missing from PASSTHROUGH_ENV_VARS"
+
+
+def test_passthrough_env_vars_includes_aws():
+    """Test that PASSTHROUGH_ENV_VARS includes AWS variables."""
+    from helm_mcp.server import PASSTHROUGH_ENV_VARS
+
+    for var in ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION", "AWS_PROFILE"]:
+        assert var in PASSTHROUGH_ENV_VARS, f"{var} missing from PASSTHROUGH_ENV_VARS"
+
+
+def test_passthrough_env_vars_includes_gcp():
+    """Test that PASSTHROUGH_ENV_VARS includes GCP variables."""
+    from helm_mcp.server import PASSTHROUGH_ENV_VARS
+
+    assert "GOOGLE_APPLICATION_CREDENTIALS" in PASSTHROUGH_ENV_VARS
+
+
+def test_passthrough_env_vars_includes_azure():
+    """Test that PASSTHROUGH_ENV_VARS includes Azure variables."""
+    from helm_mcp.server import PASSTHROUGH_ENV_VARS
+
+    for var in ["AZURE_TENANT_ID", "AZURE_CLIENT_ID", "AZURE_CLIENT_SECRET"]:
+        assert var in PASSTHROUGH_ENV_VARS, f"{var} missing from PASSTHROUGH_ENV_VARS"
+
+
+def test_passthrough_env_vars_includes_tls():
+    """Test that PASSTHROUGH_ENV_VARS includes TLS CA variables."""
+    from helm_mcp.server import PASSTHROUGH_ENV_VARS
+
+    for var in ["SSL_CERT_FILE", "SSL_CERT_DIR"]:
+        assert var in PASSTHROUGH_ENV_VARS, f"{var} missing from PASSTHROUGH_ENV_VARS"
+
+
+# ---------------------------------------------------------------------------
+# Server / Client creation
+# ---------------------------------------------------------------------------
+
+
+def test_create_server_with_binary(tmp_path):
+    """Test create_server with explicit binary path."""
+    from helm_mcp.server import create_server
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("#!/bin/sh\necho hello")
+    fake_binary.chmod(0o755)
+
+    server = create_server(binary_path=str(fake_binary))
+    assert server is not None
+
+
+def test_create_server_custom_name(tmp_path):
+    """Test create_server with a custom server name."""
+    from helm_mcp.server import create_server
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("#!/bin/sh\necho hello")
+    fake_binary.chmod(0o755)
+
+    server = create_server(binary_path=str(fake_binary), name="my-helm-mcp")
+    assert server is not None
+
+
+def test_create_server_with_extra_env(tmp_path):
+    """Test create_server with extra environment variables."""
+    from helm_mcp.server import create_server
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("#!/bin/sh\necho hello")
+    fake_binary.chmod(0o755)
+
+    server = create_server(
+        binary_path=str(fake_binary),
+        env={"CUSTOM_VAR": "custom_value"},
+    )
+    assert server is not None
+
+
+def test_create_server_binary_not_found():
+    """Test create_server raises when binary not found."""
+    from helm_mcp.server import create_server
+
+    env = {k: v for k, v in os.environ.items() if k != "HELM_MCP_BINARY"}
+    env["PATH"] = "/nonexistent"
+
+    with patch.dict(os.environ, env, clear=True), pytest.raises(FileNotFoundError):
+        create_server()
+
+
+def test_create_client_with_binary(tmp_path):
+    """Test create_client with explicit binary path."""
+    from helm_mcp.client import create_client
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("#!/bin/sh\necho hello")
+    fake_binary.chmod(0o755)
+
+    client = create_client(binary_path=str(fake_binary))
+    assert client is not None
+
+
+def test_create_client_with_extra_env(tmp_path):
+    """Test create_client with extra environment variables."""
+    from helm_mcp.client import create_client
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("#!/bin/sh\necho hello")
+    fake_binary.chmod(0o755)
+
+    client = create_client(
+        binary_path=str(fake_binary),
+        env={"EXTRA_VAR": "extra"},
+    )
+    assert client is not None
+
+
+def test_create_client_binary_not_found():
+    """Test create_client raises when binary not found."""
+    from helm_mcp.client import create_client
+
+    env = {k: v for k, v in os.environ.items() if k != "HELM_MCP_BINARY"}
+    env["PATH"] = "/nonexistent"
+
+    with patch.dict(os.environ, env, clear=True), pytest.raises(FileNotFoundError):
+        create_client()
+
+
+# ---------------------------------------------------------------------------
+# CLI module
+# ---------------------------------------------------------------------------
+
+
+def test_cli_module_exists():
+    """Test that CLI entry point module exists."""
+    from helm_mcp import cli
+
+    assert hasattr(cli, "main")
+    assert callable(cli.main)
+
+
+def test_cli_help(capsys):
+    """Test CLI --help exits cleanly."""
+    from helm_mcp.cli import main
+
+    with (
+        pytest.raises(SystemExit) as exc_info,
+        patch("sys.argv", ["helm-mcp-python", "--help"]),
+    ):
+        main()
+    assert exc_info.value.code == 0
+
+
+def test_cli_invalid_transport(capsys):
+    """Test CLI rejects invalid transport."""
+    from helm_mcp.cli import main
+
+    with (
+        pytest.raises(SystemExit) as exc_info,
+        patch("sys.argv", ["helm-mcp-python", "--transport", "invalid"]),
+    ):
+        main()
+    assert exc_info.value.code != 0
+
+
+def test_cli_binary_not_found(capsys):
+    """Test CLI exits with error when binary not found."""
+    from helm_mcp.cli import main
+
+    env = {k: v for k, v in os.environ.items() if k != "HELM_MCP_BINARY"}
+    env["PATH"] = "/nonexistent"
+
+    with (
+        patch.dict(os.environ, env, clear=True),
+        patch("sys.argv", ["helm-mcp-python"]),
+        pytest.raises(SystemExit) as exc_info,
+    ):
+        main()
+    assert exc_info.value.code == 1
+
+
+def test_cli_stdio_transport(tmp_path):
+    """Test CLI with stdio transport calls server.run()."""
+    from unittest.mock import MagicMock
+
+    from helm_mcp.cli import main
+
+    mock_server = MagicMock()
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("#!/bin/sh\necho hello")
+    fake_binary.chmod(0o755)
+
+    with (
+        patch("sys.argv", ["helm-mcp-python", "--binary", str(fake_binary)]),
+        patch("helm_mcp.server.create_server", return_value=mock_server) as mock_create,
+    ):
+        main()
+
+    mock_create.assert_called_once_with(binary_path=str(fake_binary))
+    mock_server.run.assert_called_once_with()
+
+
+def test_cli_http_transport(tmp_path):
+    """Test CLI with http transport passes host and port."""
+    from unittest.mock import MagicMock
+
+    from helm_mcp.cli import main
+
+    mock_server = MagicMock()
+
+    fake_binary = tmp_path / "helm-mcp"
+    fake_binary.write_text("#!/bin/sh\necho hello")
+    fake_binary.chmod(0o755)
+
+    with (
+        patch(
+            "sys.argv",
+            [
+                "helm-mcp-python",
+                "--binary",
+                str(fake_binary),
+                "--transport",
+                "http",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                "9090",
+            ],
+        ),
+        patch("helm_mcp.server.create_server", return_value=mock_server),
+    ):
+        main()
+
+    mock_server.run.assert_called_once_with(transport="http", host="127.0.0.1", port=9090)