nginx-proxy-manager-mcp-server 0.5.1__py3-none-any.whl

nginx_proxy_manager_mcp/auth.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import secrets
+from collections.abc import Awaitable, Callable
+
+from starlette.responses import JSONResponse
+from starlette.types import Receive, Scope, Send
+
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+
+class HealthCheckMiddleware:
+    """Serve an unauthenticated liveness endpoint for SSE deployments."""
+
+    def __init__(self, app: ASGIApp, path: str = "/healthz") -> None:
+        self.app = app
+        self.path = path
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "http" and scope.get("path") == self.path:
+            response = JSONResponse({"ok": True, "service": "nginx-proxy-manager-mcp"})
+            await response(scope, receive, send)
+            return
+
+        await self.app(scope, receive, send)
+
+
+class BearerTokenAuthMiddleware:
+    """Require a static bearer token for HTTP/SSE MCP transports."""
+
+    def __init__(self, app: ASGIApp, token: str) -> None:
+        self.app = app
+        self.token = token
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = {
+            key.decode("latin-1").lower(): value.decode("latin-1")
+            for key, value in scope.get("headers", [])
+        }
+        expected = f"Bearer {self.token}"
+        provided = headers.get("authorization", "")
+        if not secrets.compare_digest(provided, expected):
+            response = JSONResponse(
+                {"error": "unauthorized", "detail": "Missing or invalid bearer token"},
+                status_code=401,
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+            await response(scope, receive, send)
+            return
+
+        await self.app(scope, receive, send)

nginx_proxy_manager_mcp/npm_client.py

@@ -0,0 +1,101 @@
+import os
+from typing import Any
+
+import httpx
+
+
+class NPMAPIError(RuntimeError):
+    """Actionable, redacted error from the Nginx Proxy Manager API."""
+
+    def __init__(self, method: str, path: str, status_code: int, detail: str) -> None:
+        self.method = method.upper()
+        self.path = path
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"NPM API {self.method} {self.path} failed: HTTP {status_code}: {detail}")
+
+
+class NPMClient:
+    def __init__(self) -> None:
+        self.base_url = os.environ["NPM_URL"].rstrip("/")
+        self._email = os.environ["NPM_EMAIL"]
+        self._password = os.environ["NPM_PASSWORD"]
+        self.token: str | None = None
+        self._http = httpx.Client(timeout=30)
+
+    def _raise_api_error(self, method: str, path: str, resp: httpx.Response) -> None:
+        detail = ""
+        if resp.content:
+            try:
+                body = resp.json()
+            except ValueError:
+                detail = resp.text.strip()
+            else:
+                if isinstance(body, dict):
+                    detail = str(
+                        body.get("message")
+                        or body.get("error")
+                        or body.get("detail")
+                        or body
+                    )
+                else:
+                    detail = str(body)
+        if not detail:
+            detail = resp.reason_phrase or "request failed"
+        raise NPMAPIError(method, path, resp.status_code, detail)
+
+    def _authenticate(self) -> None:
+        resp = self._http.post(
+            f"{self.base_url}/api/tokens",
+            json={"identity": self._email, "secret": self._password},
+        )
+        if resp.is_error:
+            self._raise_api_error("POST", "/tokens", resp)
+        self.token = resp.json()["token"]
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        if not self.token:
+            self._authenticate()
+        resp = self._http.request(
+            method,
+            f"{self.base_url}/api{path}",
+            headers=self._auth_headers(),
+            **kwargs,
+        )
+        if resp.status_code == 401:
+            self._authenticate()
+            resp = self._http.request(
+                method,
+                f"{self.base_url}/api{path}",
+                headers=self._auth_headers(),
+                **kwargs,
+            )
+        if resp.is_error:
+            self._raise_api_error(method, path, resp)
+        if not resp.content:
+            return None
+        return resp.json()
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PUT", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "NPMClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

nginx_proxy_manager_mcp/server.py

@@ -0,0 +1,70 @@
+import os
+import sys
+
+from fastmcp import FastMCP
+from starlette.middleware import Middleware
+
+from nginx_proxy_manager_mcp.auth import BearerTokenAuthMiddleware, HealthCheckMiddleware
+from nginx_proxy_manager_mcp.npm_client import NPMClient
+from nginx_proxy_manager_mcp.tools.access_lists import register_access_list_tools
+from nginx_proxy_manager_mcp.tools.proxy_hosts import register_proxy_host_tools
+from nginx_proxy_manager_mcp.tools.redirection_hosts import register_redirection_host_tools
+from nginx_proxy_manager_mcp.tools.ssl_certs import register_ssl_cert_tools
+from nginx_proxy_manager_mcp.tools.streams import register_stream_tools
+
+mcp = FastMCP("nginx-proxy-manager-mcp")
+
+
+def validate_env() -> None:
+    required = ["NPM_URL", "NPM_EMAIL", "NPM_PASSWORD"]
+    missing = [v for v in required if not os.environ.get(v)]
+    if missing:
+        print(f"ERROR: Missing required env vars: {', '.join(missing)}", file=sys.stderr)
+        sys.exit(1)
+
+
+def get_transport() -> str:
+    transport = os.environ.get("MCP_TRANSPORT", "sse").lower()
+    if transport not in {"sse", "stdio"}:
+        print("ERROR: MCP_TRANSPORT must be one of: sse, stdio", file=sys.stderr)
+        sys.exit(1)
+    return transport
+
+
+def get_sse_middleware() -> list[Middleware]:
+    token = os.environ.get("MCP_BEARER_TOKEN")
+    middleware = [Middleware(HealthCheckMiddleware)]
+    if not token:
+        return middleware
+    middleware.append(Middleware(BearerTokenAuthMiddleware, token=token))
+    return middleware
+
+
+def get_host() -> str:
+    return os.environ.get("MCP_HOST", "127.0.0.1")
+
+
+def build_server() -> FastMCP:
+    validate_env()
+    client = NPMClient()
+    register_proxy_host_tools(mcp, client)
+    register_ssl_cert_tools(mcp, client)
+    register_access_list_tools(mcp, client)
+    register_redirection_host_tools(mcp, client)
+    register_stream_tools(mcp, client)
+    return mcp
+
+
+def main() -> None:
+    build_server()
+    transport = get_transport()
+    if transport == "stdio":
+        mcp.run(transport="stdio")
+    else:
+        host = get_host()
+        port = int(os.environ.get("MCP_PORT", "8000"))
+        mcp.run(transport="sse", host=host, port=port, middleware=get_sse_middleware())
+
+
+if __name__ == "__main__":
+    main()

nginx_proxy_manager_mcp/tools/access_lists.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from nginx_proxy_manager_mcp.npm_client import NPMClient
+
+from nginx_proxy_manager_mcp.tools.payloads import update_payload
+from nginx_proxy_manager_mcp.tools.previews import dry_run_preview
+from nginx_proxy_manager_mcp.validation import validate_access_clients, validate_access_items, validate_positive_id
+
+
+class AccessListTools:
+    def __init__(self, client: NPMClient) -> None:
+        self.client = client
+
+    def list_access_lists(self) -> list[dict]:
+        """List all access lists."""
+        return self.client.get("/nginx/access-lists")
+
+    def get_access_list(self, id: int) -> dict:
+        """Get access list detail including IP rules and basic auth users."""
+        validate_positive_id(id)
+        return self.client.get(f"/nginx/access-lists/{id}")
+
+    def create_access_list(
+        self,
+        name: str,
+        satisfy_any: bool = False,
+        pass_auth: bool = False,
+        clients: Optional[list[dict]] = None,
+        items: Optional[list[dict]] = None,
+        dry_run: bool = False,
+    ) -> dict:
+        """
+        Create a new access list.
+        clients: [{"address": "1.2.3.4", "directive": "allow|deny"}]
+        items: [{"username": "user", "password": "pass"}]
+        """
+        validated_clients = validate_access_clients(clients)
+        validated_items = validate_access_items(items)
+        payload = {
+            "name": name,
+            "satisfy_any": satisfy_any,
+            "pass_auth": pass_auth,
+            "clients": validated_clients,
+            "items": validated_items,
+        }
+        if dry_run:
+            return dry_run_preview("POST", "/nginx/access-lists", payload)
+        return self.client.post("/nginx/access-lists", json=payload)
+
+    def update_access_list(
+        self,
+        id: int,
+        name: Optional[str] = None,
+        satisfy_any: Optional[bool] = None,
+        pass_auth: Optional[bool] = None,
+        clients: Optional[list[dict]] = None,
+        items: Optional[list[dict]] = None,
+        dry_run: bool = False,
+    ) -> dict:
+        """Update an access list. Set dry_run=True to preview the merged payload."""
+        validate_positive_id(id)
+        if clients is not None:
+            validate_access_clients(clients)
+        if items is not None:
+            validate_access_items(items)
+        existing = self.client.get(f"/nginx/access-lists/{id}")
+        updates = {
+            k: v
+            for k, v in {
+                "name": name,
+                "satisfy_any": satisfy_any,
+                "pass_auth": pass_auth,
+                "clients": clients,
+                "items": items,
+            }.items()
+            if v is not None
+        }
+        existing = update_payload("access-lists", existing, updates)
+        if dry_run:
+            return dry_run_preview("PUT", f"/nginx/access-lists/{id}", existing)
+        return self.client.put(f"/nginx/access-lists/{id}", json=existing)
+
+    def delete_access_list(self, id: int, dry_run: bool = False) -> bool | dict:
+        """Delete an access list. Set dry_run=True to preview only."""
+        validate_positive_id(id)
+        if dry_run:
+            return dry_run_preview("DELETE", f"/nginx/access-lists/{id}")
+        return self.client.delete(f"/nginx/access-lists/{id}")
+
+
+def register_access_list_tools(mcp: FastMCP, client: NPMClient) -> None:
+    tools = AccessListTools(client)
+    mcp.tool()(tools.list_access_lists)
+    mcp.tool()(tools.get_access_list)
+    mcp.tool()(tools.create_access_list)
+    mcp.tool()(tools.update_access_list)
+    mcp.tool()(tools.delete_access_list)

nginx_proxy_manager_mcp/tools/payloads.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+# NPM backend/schema/paths/nginx/{proxy-hosts,redirection-hosts}/hostID/put.json,
+# streams/streamID/put.json, access-lists/listID/put.json requestBody properties.
+UPDATE_FIELDS = {
+    "proxy-hosts": {
+        "domain_names", "forward_scheme", "forward_host", "forward_port",
+        "certificate_id", "ssl_forced", "hsts_enabled", "hsts_subdomains",
+        "trust_forwarded_proto", "http2_support", "block_exploits", "caching_enabled",
+        "allow_websocket_upgrade", "access_list_id", "advanced_config", "enabled",
+        "meta", "locations",
+    },
+    "redirection-hosts": {
+        "domain_names", "forward_http_code", "forward_scheme", "forward_domain_name",
+        "preserve_path", "certificate_id", "ssl_forced", "hsts_enabled",
+        "hsts_subdomains", "http2_support", "block_exploits", "advanced_config", "meta",
+    },
+    "streams": {
+        "incoming_port", "forwarding_host", "forwarding_port", "tcp_forwarding",
+        "udp_forwarding", "certificate_id", "meta",
+    },
+    "access-lists": {"name", "satisfy_any", "pass_auth", "items", "clients"},
+}
+
+# NPM backend/schema/common.json: access_items/access_clients items properties.
+ACCESS_ENTRY_FIELDS = {
+    "items": {"username", "password"},
+    "clients": {"address", "directive"},
+}
+
+
+def update_payload(
+    resource: str, existing: dict[str, Any], updates: dict[str, Any],
+) -> dict[str, Any]:
+    """Merge changes while retaining only fields accepted by the NPM PUT schema."""
+    payload = {
+        key: value for key, value in {**existing, **updates}.items()
+        if key in UPDATE_FIELDS[resource]
+    }
+    if resource == "access-lists":
+        for key, fields in ACCESS_ENTRY_FIELDS.items():
+            if key in payload:
+                payload[key] = [
+                    {field: value for field, value in entry.items() if field in fields}
+                    for entry in payload[key]
+                ]
+    return payload

nginx_proxy_manager_mcp/tools/previews.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def dry_run_preview(method: str, path: str, json: Any = None) -> dict[str, Any]:
+    """Return a structured preview for a mutating NPM API request."""
+    preview: dict[str, Any] = {
+        "dry_run": True,
+        "method": method,
+        "path": path,
+    }
+    if json is not None:
+        preview["json"] = json
+    return preview

nginx_proxy_manager_mcp/tools/proxy_hosts.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from nginx_proxy_manager_mcp.npm_client import NPMClient
+
+from nginx_proxy_manager_mcp.tools.payloads import update_payload
+from nginx_proxy_manager_mcp.tools.previews import dry_run_preview
+from nginx_proxy_manager_mcp.validation import (
+    validate_domain_names,
+    validate_email,
+    validate_forward_scheme,
+    validate_host,
+    validate_optional_positive_id,
+    validate_port,
+    validate_positive_id,
+)
+
+
+class ProxyHostTools:
+    def __init__(self, client: NPMClient) -> None:
+        self.client = client
+
+    def list_proxy_hosts(self) -> list[dict]:
+        """List all proxy hosts with their current status."""
+        return self.client.get("/nginx/proxy-hosts")
+
+    def get_proxy_host(self, id: int) -> dict:
+        """Get a single proxy host by ID."""
+        validate_positive_id(id)
+        return self.client.get(f"/nginx/proxy-hosts/{id}")
+
+    def create_proxy_host(
+        self,
+        domain_names: list[str],
+        forward_scheme: str,
+        forward_host: str,
+        forward_port: int,
+        ssl_forced: bool = False,
+        certificate_id: Optional[int] = None,
+        access_list_id: Optional[int] = None,
+        block_exploits: bool = True,
+        caching_enabled: bool = False,
+        allow_websocket_upgrade: bool = False,
+        dry_run: bool = False,
+    ) -> dict:
+        """Create a new proxy host. Set dry_run=True to preview without changing NPM."""
+        validate_domain_names(domain_names)
+        validate_forward_scheme(forward_scheme)
+        validate_host(forward_host, "forward_host")
+        validate_port(forward_port, "forward_port")
+        validate_optional_positive_id(certificate_id, "certificate_id")
+        validate_optional_positive_id(access_list_id, "access_list_id")
+        payload = {
+            "domain_names": domain_names,
+            "forward_scheme": forward_scheme,
+            "forward_host": forward_host,
+            "forward_port": forward_port,
+            "ssl_forced": ssl_forced,
+            "certificate_id": certificate_id or 0,
+            "access_list_id": access_list_id or 0,
+            "block_exploits": block_exploits,
+            "caching_enabled": caching_enabled,
+            "allow_websocket_upgrade": allow_websocket_upgrade,
+            "advanced_config": "",
+            "meta": {},
+            "locations": [],
+        }
+        if dry_run:
+            return dry_run_preview("POST", "/nginx/proxy-hosts", payload)
+        return self.client.post("/nginx/proxy-hosts", json=payload)
+
+    def create_proxy_host_with_letsencrypt(
+        self,
+        domain_names: list[str],
+        forward_scheme: str,
+        forward_host: str,
+        forward_port: int,
+        email: str,
+        access_list_id: Optional[int] = None,
+        block_exploits: bool = True,
+        caching_enabled: bool = False,
+        allow_websocket_upgrade: bool = False,
+        dry_run: bool = False,
+    ) -> dict:
+        """Create a Let's Encrypt certificate, then create an HTTPS-forced proxy host."""
+        validate_domain_names(domain_names)
+        validate_forward_scheme(forward_scheme)
+        validate_host(forward_host, "forward_host")
+        validate_port(forward_port, "forward_port")
+        validate_email(email)
+        validate_optional_positive_id(access_list_id, "access_list_id")
+        cert_payload = {
+            "provider": "letsencrypt",
+            "domain_names": domain_names,
+            "meta": {
+                "letsencrypt_email": email,
+                "letsencrypt_agree": True,
+                "dns_challenge": False,
+            },
+        }
+        proxy_payload = {
+            "domain_names": domain_names,
+            "forward_scheme": forward_scheme,
+            "forward_host": forward_host,
+            "forward_port": forward_port,
+            "ssl_forced": True,
+            "certificate_id": "<created certificate id>",
+            "access_list_id": access_list_id or 0,
+            "block_exploits": block_exploits,
+            "caching_enabled": caching_enabled,
+            "allow_websocket_upgrade": allow_websocket_upgrade,
+            "advanced_config": "",
+            "meta": {},
+            "locations": [],
+        }
+        if dry_run:
+            return {
+                "dry_run": True,
+                "steps": [
+                    dry_run_preview("POST", "/nginx/certificates", cert_payload),
+                    dry_run_preview("POST", "/nginx/proxy-hosts", proxy_payload),
+                ],
+            }
+
+        try:
+            certificate = self.client.post("/nginx/certificates", json=cert_payload)
+        except Exception as exc:
+            return {
+                "ok": False,
+                "failed_step": "create_certificate",
+                "error": str(exc),
+                "created_certificate": None,
+                "created_proxy_host": None,
+            }
+
+        certificate_id = certificate.get("id") if isinstance(certificate, dict) else None
+        if not certificate_id:
+            return {
+                "ok": False,
+                "failed_step": "create_certificate",
+                "error": "NPM did not return a certificate id",
+                "created_certificate": certificate,
+                "created_proxy_host": None,
+            }
+
+        proxy_payload["certificate_id"] = certificate_id
+        try:
+            proxy_host = self.client.post("/nginx/proxy-hosts", json=proxy_payload)
+        except Exception as exc:
+            return {
+                "ok": False,
+                "failed_step": "create_proxy_host",
+                "error": str(exc),
+                "created_certificate": certificate,
+                "created_proxy_host": None,
+            }
+
+        return {
+            "ok": True,
+            "certificate": certificate,
+            "proxy_host": proxy_host,
+        }
+
+    def update_proxy_host(
+        self,
+        id: int,
+        domain_names: Optional[list[str]] = None,
+        forward_scheme: Optional[str] = None,
+        forward_host: Optional[str] = None,
+        forward_port: Optional[int] = None,
+        ssl_forced: Optional[bool] = None,
+        certificate_id: Optional[int] = None,
+        access_list_id: Optional[int] = None,
+        block_exploits: Optional[bool] = None,
+        caching_enabled: Optional[bool] = None,
+        allow_websocket_upgrade: Optional[bool] = None,
+        dry_run: bool = False,
+    ) -> dict:
+        """Update fields on a proxy host. Set dry_run=True to preview the merged payload."""
+        validate_positive_id(id)
+        if domain_names is not None:
+            validate_domain_names(domain_names)
+        if forward_scheme is not None:
+            validate_forward_scheme(forward_scheme)
+        if forward_host is not None:
+            validate_host(forward_host, "forward_host")
+        if forward_port is not None:
+            validate_port(forward_port, "forward_port")
+        validate_optional_positive_id(certificate_id, "certificate_id")
+        validate_optional_positive_id(access_list_id, "access_list_id")
+        existing = self.client.get(f"/nginx/proxy-hosts/{id}")
+        updates = {
+            k: v
+            for k, v in {
+                "domain_names": domain_names,
+                "forward_scheme": forward_scheme,
+                "forward_host": forward_host,
+                "forward_port": forward_port,
+                "ssl_forced": ssl_forced,
+                "certificate_id": certificate_id,
+                "access_list_id": access_list_id,
+                "block_exploits": block_exploits,
+                "caching_enabled": caching_enabled,
+                "allow_websocket_upgrade": allow_websocket_upgrade,
+            }.items()
+            if v is not None
+        }
+        existing = update_payload("proxy-hosts", existing, updates)
+        if dry_run:
+            return dry_run_preview("PUT", f"/nginx/proxy-hosts/{id}", existing)
+        return self.client.put(f"/nginx/proxy-hosts/{id}", json=existing)
+
+    def delete_proxy_host(self, id: int, dry_run: bool = False) -> bool | dict:
+        """Delete a proxy host permanently. Set dry_run=True to preview only."""
+        validate_positive_id(id)
+        if dry_run:
+            return dry_run_preview("DELETE", f"/nginx/proxy-hosts/{id}")
+        return self.client.delete(f"/nginx/proxy-hosts/{id}")
+
+    def enable_proxy_host(self, id: int, dry_run: bool = False) -> dict:
+        """Enable a previously disabled proxy host. Set dry_run=True to preview only."""
+        validate_positive_id(id)
+        if dry_run:
+            return dry_run_preview("POST", f"/nginx/proxy-hosts/{id}/enable")
+        return self.client.post(f"/nginx/proxy-hosts/{id}/enable")
+
+    def disable_proxy_host(self, id: int, dry_run: bool = False) -> dict:
+        """Disable a proxy host without deleting it. Set dry_run=True to preview only."""
+        validate_positive_id(id)
+        if dry_run:
+            return dry_run_preview("POST", f"/nginx/proxy-hosts/{id}/disable")
+        return self.client.post(f"/nginx/proxy-hosts/{id}/disable")
+
+
+def register_proxy_host_tools(mcp: FastMCP, client: NPMClient) -> None:
+    tools = ProxyHostTools(client)
+    mcp.tool()(tools.list_proxy_hosts)
+    mcp.tool()(tools.get_proxy_host)
+    mcp.tool()(tools.create_proxy_host)
+    mcp.tool()(tools.create_proxy_host_with_letsencrypt)
+    mcp.tool()(tools.update_proxy_host)
+    mcp.tool()(tools.delete_proxy_host)
+    mcp.tool()(tools.enable_proxy_host)
+    mcp.tool()(tools.disable_proxy_host)