pluglayer-mcp 0.1.0__py3-none-any.whl

pluglayer_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""PlugLayer MCP Server — AI-native infrastructure operator."""
+__version__ = "0.1.0"

pluglayer_mcp/client.py

@@ -0,0 +1,59 @@
+import httpx
+from typing import Optional, Any
+from pluglayer_mcp.settings import settings
+
+
+class PlugLayerClient:
+    """HTTP client for the PlugLayer API."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None):
+        self.api_key = api_key or settings.PLUGLAYER_API_KEY
+        self.base_url = (base_url or settings.resolved_api_base_url).rstrip("/")
+
+    @property
+    def headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "pluglayer-mcp/0.1.0",
+        }
+
+    async def _request(self, method: str, path: str, *, params: dict = None, data: dict = None, timeout: float = 30.0) -> Any:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=self.headers,
+                params=params,
+                json=data,
+            )
+            try:
+                resp.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                detail = resp.text[:500]
+                raise RuntimeError(f"{resp.status_code} {resp.reason_phrase}: {detail}") from exc
+            if resp.status_code == 204 or not resp.content:
+                return {}
+            data = resp.json()
+            if isinstance(data, dict) and data.get("ok") is True and "data" in data:
+                return data["data"]
+            return data
+
+    async def get(self, path: str, params: dict = None) -> Any:
+        return await self._request("GET", path, params=params, timeout=30.0)
+
+    async def post(self, path: str, data: dict = None, params: dict = None) -> Any:
+        return await self._request("POST", path, params=params, data=data or {}, timeout=60.0)
+
+    async def delete(self, path: str) -> Any:
+        return await self._request("DELETE", path, timeout=30.0)
+
+    async def patch(self, path: str, data: dict) -> Any:
+        return await self._request("PATCH", path, data=data, timeout=30.0)
+
+    async def put(self, path: str, data: dict) -> Any:
+        return await self._request("PUT", path, data=data, timeout=30.0)
+
+
+def get_client(api_key: Optional[str] = None) -> PlugLayerClient:
+    return PlugLayerClient(api_key=api_key)

pluglayer_mcp/server.py

@@ -0,0 +1,69 @@
+"""
+PlugLayer MCP Server
+
+Exposes PlugLayer project, compute, deployment, CI/CD, and admin tools to AI
+assistants through the Model Context Protocol (MCP). The MCP intentionally goes
+through the FastAPI backend endpoints so auth, roles, ownership, quotas, compute
+checks, k3s orchestration, and admin guards stay in one backend implementation.
+"""
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from pluglayer_mcp.settings import settings
+
+mcp = FastMCP(
+    "PlugLayer",
+    instructions="""You are the PlugLayer infrastructure operator.
+You help users deploy, manage, and monitor applications on PlugLayer.
+
+Current PlugLayer rules:
+- Authentik groups are exposed by PlugLayer as user.roles. Do not use groups/permissions fields.
+- Admin tools require the user to have pluglayer-admin or pluglayer-superadmin in roles.
+- Compute is account-level: personal SSH nodes and shared PlugLayer nodes can be used by all projects the user owns.
+- A project is a k3s namespace. A deployment is an app inside a project.
+- Custom domains are verified and routed by backend v1 domain endpoints; do not invent DNS or Traefik state.
+- Async operations return task IDs; always poll get_task_status until completion.
+
+Deployment workflow:
+1. Run get_current_user and get_compute_summary.
+2. List or create a project.
+3. Ensure can_deploy is true. If false, add a personal SSH node or ask an admin to assign shared compute.
+4. Deploy from image or docker-compose.
+5. Poll the returned task and report the public URL.
+
+Confirm destructive actions such as delete and rollback before executing them.
+""",
+)
+
+from pluglayer_mcp.tools.cicd_health import register_cicd_health_tools
+from pluglayer_mcp.tools.compute import register_compute_tools
+from pluglayer_mcp.tools.deployments import register_deployment_tools
+from pluglayer_mcp.tools.domains import register_domain_tools
+from pluglayer_mcp.tools.identity_projects import register_identity_project_tools
+from pluglayer_mcp.tools.tasks_admin import register_task_admin_tools
+
+register_identity_project_tools(mcp)
+register_compute_tools(mcp)
+register_deployment_tools(mcp)
+register_domain_tools(mcp)
+register_task_admin_tools(mcp)
+register_cicd_health_tools(mcp)
+
+
+def main():
+    """Entry point for `pluglayer-mcp` command."""
+    if not settings.PLUGLAYER_API_KEY:
+        print(
+            "WARNING: PLUGLAYER_API_KEY not set!\n"
+            "Set it as an environment variable:\n"
+            "  PLUGLAYER_API_KEY=your-token pluglayer-mcp\n\n"
+            "Get your token from: https://portal.pluglayer.com/settings",
+            file=sys.stderr,
+        )
+
+    mcp.run(transport="streamable-http")
+
+
+if __name__ == "__main__":
+    main()

pluglayer_mcp/settings.py

@@ -0,0 +1,27 @@
+from functools import lru_cache
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    PLUGLAYER_API_BASE_URL: str = "https://api.pluglayer.com"
+    PLUGLAYER_API_URL: str = Field(default="")  # legacy fallback
+    PLUGLAYER_API_KEY: str = ""  # Set by user via env var
+    MCP_HOST: str = "0.0.0.0"
+    MCP_PORT: int = 8001
+    DEBUG: bool = False
+
+    model_config = SettingsConfigDict(env_file=".env")
+
+    @property
+    def resolved_api_base_url(self) -> str:
+        candidate = (self.PLUGLAYER_API_BASE_URL or "").strip() or (self.PLUGLAYER_API_URL or "").strip()
+        return candidate or "https://api.pluglayer.com"
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    return Settings()
+
+
+settings = get_settings()

pluglayer_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool registration modules."""

pluglayer_mcp/tools/cicd_health.py

@@ -0,0 +1,42 @@
+"""Cicd Health MCP tools."""
+
+from pluglayer_mcp.tools.shared import _client, _compact_error
+
+
+def register_cicd_health_tools(mcp):
+    @mcp.tool()
+    async def generate_github_actions(project_id: str, deployment_id: str, github_org: str = "your-org") -> str:
+        """Generate a GitHub Actions workflow YAML for PlugLayer CI/CD."""
+        try:
+            data = await _client().get("/v1/plugin/cicd/generate/github-actions", params={
+                "project_id": project_id,
+                "deployment_id": deployment_id,
+                "repo": github_org,
+            })
+            workflow = data.get("workflow_yaml", "")
+            filename = data.get("filename", ".github/workflows/deploy-pluglayer.yml")
+            return (
+                f"📋 **GitHub Actions Workflow**\n"
+                f"Save as: `{filename}`\n\n"
+                f"```yaml\n{workflow}\n```\n\n"
+                "Setup steps:\n"
+                "1. Create this file in your repo.\n"
+                "2. Add `PLUGLAYER_API_KEY` as a GitHub secret.\n"
+                "3. Push to main/master to trigger deploys."
+            )
+        except Exception as e:
+            return _compact_error("Error generating pipeline", e)
+
+    @mcp.tool()
+    async def get_cluster_health() -> str:
+        """Check PlugLayer API and k3s cluster health."""
+        try:
+            health = await _client().get("/v1/plugin/health")
+            k3s = await _client().get("/v1/plugin/health/k3s")
+            return (
+                "🩺 **PlugLayer Health**\n"
+                f"API: {health.get('api', 'unknown')}\n"
+                f"k3s: {'healthy' if k3s.get('ok') else 'unavailable'} — {k3s.get('message', '')}"
+            )
+        except Exception as e:
+            return _compact_error("Error checking health", e)

pluglayer_mcp/tools/compute.py

@@ -0,0 +1,92 @@
+"""Compute MCP tools."""
+
+from pluglayer_mcp.tools.shared import _client, _compact_error, _fmt_compute, _fmt_node, _fmt_task_hint, _get_compute_summary
+
+
+def register_compute_tools(mcp):
+    # ── Compute / nodes ───────────────────────────────────────────────────────────
+
+
+    @mcp.tool()
+    async def get_compute_summary() -> str:
+        """Show accessible account-level compute: personal SSH nodes plus shared PlugLayer nodes."""
+        try:
+            data = await _get_compute_summary()
+            counts = data.get("counts", {})
+            lines = [
+                "🧮 **Compute Summary**",
+                f"Can deploy: {'yes' if data.get('can_deploy') else 'no'}",
+                f"Message: {data.get('message')}",
+                f"Accessible nodes: {counts.get('accessible', 0)} total, {counts.get('ready', 0)} ready",
+                f"Personal nodes: {counts.get('personal', 0)} total, {counts.get('personal_ready', 0)} ready",
+                f"PlugLayer shared nodes: {counts.get('pluglayer', 0)} total, {counts.get('pluglayer_ready', 0)} ready",
+                f"Total ready compute: {_fmt_compute(data.get('total_compute'))}",
+                f"Personal ready compute: {_fmt_compute(data.get('personal_compute'))}",
+                f"Shared ready compute: {_fmt_compute(data.get('pluglayer_compute'))}",
+            ]
+            purchase = data.get("purchase") or {}
+            if purchase.get("message"):
+                lines.append(f"Purchase: {purchase['message']}")
+            return "\n".join(lines)
+        except Exception as e:
+            return _compact_error("Error loading compute summary", e)
+
+
+    @mcp.tool()
+    async def list_nodes(project_id: str = "") -> str:
+        """
+        List compute nodes accessible to the authenticated user.
+        Compute is account-level; project_id is accepted only for backwards compatibility.
+        """
+        try:
+            params = {"project_id": project_id} if project_id else {}
+            data = await _client().get("/v1/plugin/compute/nodes", params=params)
+            nodes = data.get("nodes", [])
+            if not nodes:
+                return "No accessible compute nodes found. Add one with add_node_ssh(), or ask an admin to assign shared compute."
+            lines = ["Accessible compute nodes:\n"]
+            lines.extend(_fmt_node(n) for n in nodes)
+            return "\n".join(lines)
+        except Exception as e:
+            return _compact_error("Error listing compute nodes", e)
+
+
+    @mcp.tool()
+    async def add_node_ssh(
+        project_id: str,
+        name: str,
+        host: str,
+        ssh_private_key: str,
+        user: str = "root",
+        port: int = 22,
+    ) -> str:
+        """
+        Add a personal SSH node/VM as account-level compute.
+
+        project_id is optional/backwards-compatible setup context. The node belongs to the authenticated
+        user and can be used by all of that user's projects. Pass an empty string when no project context is needed.
+        """
+        if not name or not host or not ssh_private_key:
+            return "Missing required fields: name, host, and ssh_private_key are required."
+        try:
+            payload = {
+                "name": name,
+                "provider": "ssh",
+                "ssh_host": host,
+                "ssh_port": port,
+                "ssh_user": user,
+                "ssh_private_key": ssh_private_key,
+            }
+            if project_id:
+                payload["project_id"] = project_id
+            data = await _client().post("/v1/plugin/compute/nodes", payload)
+            task_id = data.get("task_id")
+            node = data.get("node", {})
+            return (
+                f"✅ SSH node queued as personal account compute.\n"
+                f"Node: **{node.get('name', name)}** (id: `{node.get('id')}`)\n"
+                f"Task ID: `{task_id}`\n\n"
+                f"⚙️ Installing k3s agent and detecting CPU/RAM/storage/GPU. {_fmt_task_hint(task_id)}"
+            )
+        except Exception as e:
+            return _compact_error("Failed to add SSH node", e)

pluglayer_mcp/tools/deployments.py

@@ -0,0 +1,180 @@
+"""Deployment/app MCP tools backed by PlugLayer v1 apps API."""
+
+from pluglayer_mcp.tools.shared import _client, _compact_error, _fmt_task_hint, _get_compute_summary, _status_emoji
+
+
+def register_deployment_tools(mcp):
+    @mcp.tool()
+    async def list_registries() -> str:
+        """List registry destinations available to the current user."""
+        try:
+            data = await _client().get("/v1/plugin/registries")
+            registries = data.get("registries", [])
+            if not registries:
+                return "No registries are available to you yet. Ask an admin to configure a system or personal registry first."
+            lines = ["Available registries:\n"]
+            for registry in registries:
+                lines.append(
+                    f"- **{registry.get('name')}** (`{registry.get('id')}`)\n"
+                    f"  Provider: {registry.get('provider')} | Scope: {registry.get('scope')} | Namespace: {registry.get('namespace')}\n"
+                    f"  Last test: {registry.get('last_test', {}).get('message') or 'unknown'}\n"
+                )
+            return "\n".join(lines)
+        except Exception as e:
+            return _compact_error("Error listing registries", e)
+
+    @mcp.tool()
+    async def list_deployments(project_id: str = "") -> str:
+        """List apps. Optionally filter by project_id."""
+        try:
+            params = {"project_id": project_id} if project_id else {}
+            data = await _client().get("/v1/plugin/apps", params=params)
+            apps = data.get("apps", [])
+            if not apps:
+                return "No apps found. Deploy one with deploy_image() or deploy_compose()."
+            lines = ["Your apps:\n"]
+            for app in apps:
+                status = app.get("status", "unknown")
+                image = app.get("image") or "compose"
+                tag = app.get("tag") or ""
+                lines.append(
+                    f"{_status_emoji(status)} **{app.get('name')}** (id: `{app.get('id')}`)\n"
+                    f"   Status: {status} | Source: {app.get('source_type', 'image')} | Image: {image}:{tag}\n"
+                    f"   URL: {app.get('primary_url') or 'not yet available'}\n"
+                )
+            return "\n".join(lines)
+        except Exception as e:
+            return _compact_error("Error listing apps", e)
+
+    @mcp.tool()
+    async def deploy_image(
+        project_id: str,
+        name: str,
+        image: str,
+        tag: str = "latest",
+        ports: list[int] | None = None,
+        env_vars: dict[str, str] | None = None,
+        replicas: int = 1,
+        route_slug: str = "",
+        cpu_limit: str = "500m",
+        memory_limit: str = "512Mi",
+        compute_placement: str = "auto",
+        push_to_pluglayer_registry: bool = True,
+        registry_id: str = "",
+    ) -> str:
+        """Deploy a Docker image into a project. By default, mirror it into PlugLayer's managed registry first."""
+        try:
+            compute = await _get_compute_summary()
+            if not compute.get("can_deploy"):
+                return f"Cannot deploy yet: {compute.get('message')}"
+            payload = {
+                "name": name,
+                "route_slug": route_slug or None,
+                "compute_placement": compute_placement,
+                "registry_id": registry_id or None,
+                "source": {
+                    "type": "image",
+                    "image": image,
+                    "tag": tag,
+                    "ports": ports or [],
+                    "env_vars": env_vars or {},
+                    "replicas": replicas,
+                    "cpu_limit": cpu_limit,
+                    "memory_limit": memory_limit,
+                },
+            }
+            endpoint = (
+                f"/v1/plugin/projects/{project_id}/apps/push-image"
+                if push_to_pluglayer_registry
+                else f"/v1/plugin/projects/{project_id}/apps"
+            )
+            data = await _client().post(endpoint, payload)
+            task_id = data.get("task_id")
+            app = data.get("app", {})
+            mirrored = data.get("mirrored_image")
+            lines = [f"🚀 App queued: **{name}** (id: `{app.get('id')}`). Task ID: `{task_id}`"]
+            if mirrored:
+                lines.append(f"Mirrored image: `{mirrored}`")
+            lines.append(_fmt_task_hint(task_id))
+            return "\n".join(lines)
+        except Exception as e:
+            return _compact_error("Deployment failed", e)
+
+    @mcp.tool()
+    async def deploy_compose(
+        project_id: str,
+        compose_yaml: str,
+        app_name: str = "",
+        route_slug: str = "",
+        compute_placement: str = "auto",
+    ) -> str:
+        """Deploy docker-compose.yml into a project."""
+        try:
+            compute = await _get_compute_summary()
+            if not compute.get("can_deploy"):
+                return f"Cannot deploy yet: {compute.get('message')}"
+            data = await _client().post(f"/v1/plugin/projects/{project_id}/apps", {
+                "name": app_name or "compose-app",
+                "route_slug": route_slug or None,
+                "compute_placement": compute_placement,
+                "source": {"type": "compose", "compose_yaml": compose_yaml},
+            })
+            task_id = data.get("task_id")
+            app = data.get("app", {})
+            return f"🚀 Compose app queued (id: `{app.get('id')}`). Task ID: `{task_id}`\n{_fmt_task_hint(task_id)}"
+        except Exception as e:
+            return _compact_error("Compose deployment failed", e)
+
+    @mcp.tool()
+    async def get_deployment_status(deployment_id: str) -> str:
+        """Get current app/deployment status and public URL."""
+        try:
+            data = await _client().get(f"/v1/plugin/apps/{deployment_id}/status")
+            app = data.get("app", {})
+            k8s = (data.get("runtime") or {}).get("k8s_status") or {}
+            status = app.get("status", "unknown")
+            result = f"{_status_emoji(status)} **App Status**\nStatus: {status}\nURL: {app.get('primary_url') or 'not yet available'}\n"
+            if k8s:
+                result += f"Replicas: {k8s.get('ready_replicas', 0)}/{k8s.get('replicas', 0)} ready\n"
+            return result
+        except Exception as e:
+            return _compact_error("Error getting app status", e)
+
+    @mcp.tool()
+    async def get_logs(deployment_id: str, lines: int = 100) -> str:
+        """Get recent logs from an app."""
+        try:
+            data = await _client().get(f"/v1/plugin/apps/{deployment_id}/logs", params={"tail": lines})
+            return f"📋 **Logs** (last {lines} lines):\n\n```\n{data.get('logs', 'No logs available')}\n```"
+        except Exception as e:
+            return _compact_error("Error getting logs", e)
+
+    @mcp.tool()
+    async def redeploy(deployment_id: str) -> str:
+        """Redeploy an existing app."""
+        try:
+            data = await _client().post(f"/v1/plugin/apps/{deployment_id}/redeploy")
+            task_id = data.get("task_id")
+            return f"🔄 Redeployment queued. Task ID: `{task_id}`\n{_fmt_task_hint(task_id)}"
+        except Exception as e:
+            return _compact_error("Error triggering redeploy", e)
+
+    @mcp.tool()
+    async def rollback(deployment_id: str, revision: int | None = None) -> str:
+        """Roll back an app to a previous revision."""
+        try:
+            params = {"revision": revision} if revision else {}
+            data = await _client().post(f"/v1/plugin/apps/{deployment_id}/rollback", params=params)
+            task_id = data.get("task_id")
+            return f"⏪ Rollback queued. Task ID: `{task_id}`\n{_fmt_task_hint(task_id)}"
+        except Exception as e:
+            return _compact_error("Error triggering rollback", e)
+
+    @mcp.tool()
+    async def delete_deployment(deployment_id: str) -> str:
+        """DESTRUCTIVE: delete an app and remove it from k3s."""
+        try:
+            await _client().delete(f"/v1/plugin/apps/{deployment_id}")
+            return f"🗑️ App `{deployment_id}` deleted and removed from cluster."
+        except Exception as e:
+            return _compact_error("Error deleting app", e)

pluglayer_mcp/tools/domains.py

@@ -0,0 +1,81 @@
+"""Custom-domain MCP tools backed by PlugLayer v1 domain APIs."""
+
+from pluglayer_mcp.tools.shared import _client, _compact_error, _status_emoji
+
+
+def _fmt_domain(domain: dict) -> str:
+    status = domain.get("status", "unknown")
+    app = domain.get("app_id") or "not attached"
+    return (
+        f"{_status_emoji(status)} **{domain.get('domain')}** (id: `{domain.get('id')}`)\n"
+        f"   Status: {status} | Mode: {domain.get('mode')} | App: {app}\n"
+        f"   TXT: {domain.get('verification', {}).get('name')} = {domain.get('verification', {}).get('value')}\n"
+        f"   DNS: {domain.get('dns', {}).get('expected_type')} -> {domain.get('dns', {}).get('expected_value')}\n"
+    )
+
+
+def register_domain_tools(mcp):
+    @mcp.tool()
+    async def list_project_domains(project_id: str) -> str:
+        """List custom domains for a project."""
+        try:
+            data = await _client().get(f"/v1/plugin/projects/{project_id}/domains")
+            domains = data.get("domains", [])
+            if not domains:
+                return "No custom domains are configured for this project."
+            return "Project domains:\n\n" + "\n".join(_fmt_domain(domain) for domain in domains)
+        except Exception as e:
+            return _compact_error("Error listing domains", e)
+
+    @mcp.tool()
+    async def add_custom_domain(project_id: str, domain: str, mode: str = "single", app_id: str = "") -> str:
+        """Add a custom domain. mode is 'single' or 'wildcard'."""
+        try:
+            data = await _client().post(f"/v1/plugin/projects/{project_id}/domains", {
+                "domain": domain,
+                "mode": mode,
+                "app_id": app_id or None,
+            })
+            item = data.get("domain", {})
+            return "Domain added. Create these DNS records, then run verify_custom_domain():\n\n" + _fmt_domain(item)
+        except Exception as e:
+            return _compact_error("Error adding domain", e)
+
+    @mcp.tool()
+    async def verify_custom_domain(domain_id: str) -> str:
+        """Verify TXT/CNAME DNS for a custom domain and activate it if attached."""
+        try:
+            data = await _client().post(f"/v1/plugin/domains/{domain_id}/verify")
+            return _fmt_domain(data.get("domain", {}))
+        except Exception as e:
+            return _compact_error("Error verifying domain", e)
+
+    @mcp.tool()
+    async def attach_custom_domain(domain_id: str, app_id: str, make_primary: bool = False) -> str:
+        """Attach a verified custom domain to an app."""
+        try:
+            data = await _client().post(f"/v1/plugin/domains/{domain_id}/attach", {
+                "app_id": app_id,
+                "make_primary": make_primary,
+            })
+            return _fmt_domain(data.get("domain", {}))
+        except Exception as e:
+            return _compact_error("Error attaching domain", e)
+
+    @mcp.tool()
+    async def detach_custom_domain(domain_id: str) -> str:
+        """Detach a custom domain from its app while keeping verification."""
+        try:
+            data = await _client().post(f"/v1/plugin/domains/{domain_id}/detach")
+            return _fmt_domain(data.get("domain", {}))
+        except Exception as e:
+            return _compact_error("Error detaching domain", e)
+
+    @mcp.tool()
+    async def remove_custom_domain(domain_id: str) -> str:
+        """Remove a custom domain and its Traefik route."""
+        try:
+            await _client().delete(f"/v1/plugin/domains/{domain_id}")
+            return f"Custom domain `{domain_id}` removed."
+        except Exception as e:
+            return _compact_error("Error removing domain", e)

pluglayer_mcp/tools/identity_projects.py

@@ -0,0 +1,95 @@
+"""Identity Projects MCP tools."""
+
+from pluglayer_mcp.tools.shared import _client, _compact_error, _fmt_task_hint, _status_emoji
+
+
+def register_identity_project_tools(mcp):
+    # ── Identity / roles ─────────────────────────────────────────────────────────
+
+
+    @mcp.tool()
+    async def get_current_user() -> str:
+        """Show the authenticated PlugLayer user and roles from Authentik."""
+        try:
+            payload = await _client().get("/v1/plugin/me")
+            user = payload.get("user", payload)
+            roles = user.get("roles") or []
+            return (
+                "👤 **Current PlugLayer user**\n"
+                f"Email: {user.get('email')}\n"
+                f"Username: {user.get('username')}\n"
+                f"Roles: {', '.join(roles) if roles else 'none'}\n"
+                f"Superadmin: {'yes' if user.get('is_superuser') else 'no'}"
+            )
+        except Exception as e:
+            return _compact_error("Error loading current user", e)
+
+
+    # ── Projects ──────────────────────────────────────────────────────────────────
+
+
+    @mcp.tool()
+    async def list_projects() -> str:
+        """List authenticated user's projects. Normal users see their projects; admins may see admin data via admin tools."""
+        try:
+            data = await _client().get("/v1/plugin/projects")
+            projects = data.get("projects", [])
+            if not projects:
+                return "No projects found. Create one with create_project()."
+            lines = ["Your projects:\n"]
+            for p in projects:
+                status = p.get("status", "unknown")
+                lines.append(
+                    f"{_status_emoji(status)} **{p.get('name')}** (id: `{p.get('id')}`)\n"
+                    f"   Status: {status} | Apps: {p.get('deployment_count', 0)}\n"
+                    f"   Namespace: `{p.get('namespace')}`\n"
+                    f"   URL pattern: {p.get('base_url', 'N/A')}\n"
+                )
+            return "\n".join(lines)
+        except Exception as e:
+            return _compact_error("Error listing projects", e)
+
+
+    @mcp.tool()
+    async def create_project(name: str, description: str = "", domain_type: str = "pluglayer") -> str:
+        """
+        Create a PlugLayer project namespace. Project creation only requires authentication.
+        Deployment still requires account-level compute; check get_compute_summary before deploying.
+        """
+        try:
+            data = await _client().post("/v1/plugin/projects", {
+                "name": name,
+                "description": description,
+                "domain_type": domain_type,
+            })
+            project = data.get("project", {})
+            task_id = data.get("task_id")
+            return (
+                f"✅ Project **{project.get('name', name)}** created.\n"
+                f"Project ID: `{project.get('id')}`\n"
+                f"Namespace: `{project.get('namespace')}`\n"
+                f"Task ID: `{task_id}`\n\n"
+                f"⏳ Setting up namespace. {_fmt_task_hint(task_id)}"
+            )
+        except Exception as e:
+            return _compact_error("Error creating project", e)
+
+
+    @mcp.tool()
+    async def get_project(project_id: str) -> str:
+        """Get project details. Accessible to the project owner or a PlugLayer admin role."""
+        try:
+            p = await _client().get(f"/v1/plugin/projects/{project_id}")
+            p = p.get("project", p)
+            status = p.get("status", "unknown")
+            return (
+                f"{_status_emoji(status)} **{p.get('name')}**\n"
+                f"ID: `{p.get('id')}`\n"
+                f"Status: {status}\n"
+                f"Namespace: `{p.get('namespace')}`\n"
+                f"URL pattern: {p.get('base_url', 'N/A')}\n"
+                f"Apps: {p.get('deployment_count', 0)}\n"
+                "Compute is account-level; use get_compute_summary() for available capacity."
+            )
+        except Exception as e:
+            return _compact_error("Error getting project", e)

pluglayer_mcp/tools/shared.py

@@ -0,0 +1,53 @@
+"""Shared helpers for PlugLayer MCP tools."""
+
+from typing import Any
+
+from pluglayer_mcp.client import PlugLayerClient
+from pluglayer_mcp.settings import settings
+
+
+def _client() -> PlugLayerClient:
+    return PlugLayerClient(api_key=settings.PLUGLAYER_API_KEY)
+
+
+def _status_emoji(status: str) -> str:
+    return {
+        "active": "✅", "ready": "✅", "running": "🕺", "completed": "✅",
+        "provisioning": "⏳", "pending": "😴", "queued": "⏳", "deploying": "🚀", "joining": "🔗",
+        "in_progress": "⚙️", "scaling": "⚙️",
+        "error": "❌", "failed": "💀", "crash_loop": "🥴", "offline": "💤",
+        "terminated": "🪦", "terminating": "👻", "cancelled": "🚫", "suspended": "⏸️",
+        "deleting": "🧹",
+    }.get(str(status or ""), "❓")
+
+
+def _fmt_compute(compute: dict[str, Any] | None) -> str:
+    c = compute or {}
+    return (
+        f"{c.get('cpu_cores', 0)} CPU, "
+        f"{c.get('ram_gb', 0)}GB RAM, "
+        f"{c.get('storage_gb', 0)}GB disk, "
+        f"{c.get('gpu_gb', 0)}GB GPU"
+    )
+
+
+def _fmt_node(node: dict[str, Any]) -> str:
+    status = node.get("status", "unknown")
+    owner = "shared PlugLayer" if node.get("is_shared") else "personal"
+    return (
+        f"{_status_emoji(status)} **{node.get('name', 'unnamed')}** (id: `{node.get('id')}`)\n"
+        f"   Provider: {node.get('provider')} | Status: {status} | Scope: {owner}\n"
+        f"   Compute: {_fmt_compute(node.get('hardware'))}\n"
+    )
+
+
+def _fmt_task_hint(task_id: str | None) -> str:
+    return f"Poll: `get_task_status('{task_id}')`" if task_id else "No task id returned."
+
+
+def _compact_error(prefix: str, exc: Exception) -> str:
+    return f"{prefix}: {exc}"
+
+
+async def _get_compute_summary() -> dict[str, Any]:
+    return await _client().get("/v1/plugin/compute")

pluglayer_mcp/tools/tasks_admin.py

@@ -0,0 +1,122 @@
+"""Tasks Admin MCP tools."""
+
+from pluglayer_mcp.tools.shared import _client, _compact_error, _fmt_compute, _fmt_task_hint, _status_emoji
+
+
+def register_task_admin_tools(mcp):
+    # ── Tasks ─────────────────────────────────────────────────────────────────────
+
+
+    @mcp.tool()
+    async def get_task_status(task_id: str) -> str:
+        """Check async operation status, progress, result URL, or error."""
+        try:
+            data = await _client().get(f"/v1/plugin/tasks/{task_id}")
+            t = data.get("task", data)
+            status = t.get("status", "unknown")
+            progress = t.get("progress", {}) or {}
+            result = t.get("result") or {}
+            result_str = ""
+            if result.get("primary_url"):
+                result_str = f"\n🌐 App URL: {result['primary_url']}"
+            elif result.get("k3s_node_name"):
+                result_str = f"\n🖥️ Node joined as: {result['k3s_node_name']}"
+            elif result:
+                result_str = f"\nResult: {result}"
+            error = t.get("error_message") or t.get("error")
+            error_str = f"\n❌ Error: {error}" if error else ""
+            return (
+                f"{_status_emoji(status)} **Task {t.get('type', '')}**\n"
+                f"Status: {status}\n"
+                f"Progress: {round(progress.get('percentage', 0))}% — {progress.get('message', '')}\n"
+                f"Steps: {progress.get('step', 0)}/{progress.get('total_steps', 0)}"
+                f"{result_str}{error_str}"
+            )
+        except Exception as e:
+            return _compact_error("Error getting task", e)
+
+
+    # ── Admin tools ────────────────────────────────────────────────────────────────
+
+
+    @mcp.tool()
+    async def admin_get_overview() -> str:
+        """Admin only: summarize platform tasks, capacity events, nodes, and compute defaults."""
+        try:
+            overview = await _client().get("/v1/plugin/admin/overview")
+            compute = await _client().get("/v1/plugin/admin/compute/settings")
+            stats = overview.get("stats", {})
+            return (
+                "🛡️ **Admin Overview**\n"
+                f"Projects: {stats.get('projects', 0)} | Deployments: {stats.get('deployments', 0)} | Nodes: {stats.get('nodes', 0)} | Tasks today: {stats.get('tasks_today', 0)}\n"
+                f"Registered nodes: {stats.get('nodes', 0)}\n"
+                f"Default quota: {_fmt_compute(compute.get('default_quota'))}\n"
+            )
+        except Exception as e:
+            return _compact_error("Admin overview failed (requires pluglayer-admin or pluglayer-superadmin role)", e)
+
+
+    @mcp.tool()
+    async def admin_set_compute_defaults(
+        cpu_cores: float,
+        ram_gb: float,
+        storage_gb: int,
+        gpu_gb: float = 0,
+        allow_shared_compute: bool = True,
+    ) -> str:
+        """Admin only: update default compute quota metadata shown to new users."""
+        try:
+            await _client().put("/v1/plugin/admin/compute/settings", {
+                "allow_shared_compute": allow_shared_compute,
+                "default_quota": {
+                    "cpu_cores": cpu_cores,
+                    "ram_gb": ram_gb,
+                    "storage_gb": storage_gb,
+                    "gpu_gb": gpu_gb,
+                },
+            })
+            return f"✅ Default compute saved: {_fmt_compute({'cpu_cores': cpu_cores, 'ram_gb': ram_gb, 'storage_gb': storage_gb, 'gpu_gb': gpu_gb})}"
+        except Exception as e:
+            return _compact_error("Failed to update admin compute defaults", e)
+
+
+    @mcp.tool()
+    async def admin_set_node_shared(node_id: str, is_shared: bool = True) -> str:
+        """Admin only: mark an existing node as shared PlugLayer compute or private."""
+        try:
+            data = await _client().patch(f"/v1/plugin/admin/nodes/{node_id}/sharing", {"is_shared": is_shared})
+            warning = f"\nWarning: {data['warning']}" if data.get("warning") else ""
+            return f"✅ Node `{node_id}` shared={data.get('is_shared', is_shared)}.{warning}"
+        except Exception as e:
+            return _compact_error("Failed to update node sharing", e)
+
+
+    @mcp.tool()
+    async def admin_add_shared_ssh_node(
+        name: str,
+        host: str,
+        ssh_private_key: str,
+        user: str = "root",
+        port: int = 22,
+    ) -> str:
+        """Admin only: add an SSH node as PlugLayer-owned shared compute for all users."""
+        if not name or not host or not ssh_private_key:
+            return "Missing required fields: name, host, and ssh_private_key are required."
+        try:
+            data = await _client().post("/v1/plugin/admin/nodes/ssh", {
+                "name": name,
+                "provider": "ssh",
+                "ssh_host": host,
+                "ssh_port": port,
+                "ssh_user": user,
+                "ssh_private_key": ssh_private_key,
+            })
+            task_id = data.get("task_id")
+            node = data.get("node", {})
+            return (
+                f"✅ Shared PlugLayer SSH node queued.\n"
+                f"Node: **{node.get('name', name)}** (id: `{node.get('id')}`)\n"
+                f"Task ID: `{task_id}`\n{_fmt_task_hint(task_id)}"
+            )
+        except Exception as e:
+            return _compact_error("Failed to add shared SSH node", e)

pluglayer_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: pluglayer-mcp
+Version: 0.1.0
+Summary: PlugLayer MCP server — deploy and manage infrastructure via AI
+License: MIT
+Keywords: deployment,infrastructure,kubernetes,mcp,pluglayer
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.3.0
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Description-Content-Type: text/markdown
+
+# PlugLayer MCP Server
+
+Deploy and manage your infrastructure through natural language with any MCP-compatible AI assistant.
+
+## Installation
+
+### Option 1: uvx (recommended — no install needed)
+```bash
+PLUGLAYER_API_KEY=your-pluglayer-api-token uvx pluglayer-mcp
+```
+
+Optional:
+```bash
+PLUGLAYER_API_BASE_URL=https://api.pluglayer.com
+```
+
+### Option 2: pip
+```bash
+pip install pluglayer-mcp
+PLUGLAYER_API_KEY=your-pluglayer-api-token pluglayer-mcp
+```
+
+## Configuration
+
+### Claude Desktop
+Add to `~/.config/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pluglayer": {
+      "command": "uvx",
+      "args": ["pluglayer-mcp"],
+      "env": {
+        "PLUGLAYER_API_KEY": "your-pluglayer-api-token",
+        "PLUGLAYER_API_BASE_URL": "https://api.pluglayer.com"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+Add to `~/.cursor/mcp.json`:
+```json
+{
+  "pluglayer": {
+    "command": "uvx",
+    "args": ["pluglayer-mcp"],
+    "env": {
+      "PLUGLAYER_API_KEY": "your-pluglayer-api-token",
+      "PLUGLAYER_API_BASE_URL": "https://api.pluglayer.com"
+    }
+  }
+}
+```
+
+### Remote HTTP (hosted)
+The remote MCP server runs at `mcp.pluglayer.com`. Pass your token as:
+```
+Authorization: Bearer your-pluglayer-api-token
+```
+
+### API base URL behavior
+
+- `PLUGLAYER_API_BASE_URL` is the preferred environment variable for the backend API origin.
+- If it is unset or empty, the MCP defaults to `https://api.pluglayer.com`.
+- `PLUGLAYER_API_URL` is still accepted as a legacy fallback during migration.
+
+## Available Tools
+
+The MCP calls the PlugLayer FastAPI backend instead of re-implementing backend business logic. Auth, roles, ownership, compute guards, k3s orchestration, and admin checks remain in the backend. MCP and editor plugins should authenticate with a **PlugLayer API token** created in the PlugLayer Settings page, not the browser/session auth token.
+
+Managed registries are configured by PlugLayer admins in the platform UI/API. When `deploy_image` uses mirroring, the backend picks a registry the current user is allowed to use and keeps Kubernetes pull secrets in sync automatically.
+
+| Tool | Description |
+|------|-------------|
+| `get_current_user` | Show the Authentik-backed user and `roles` |
+| `list_projects` | List authenticated user's projects |
+| `create_project` | Create a new project namespace |
+| `get_project` | Get project details |
+| `get_compute_summary` | Show account-level personal + shared compute capacity |
+| `list_nodes` | List accessible compute nodes |
+| `add_node_ssh` | Add a personal SSH node usable by all of the user's projects |
+| `list_registries` | List the registries currently available to the user |
+| `deploy_image` | Mirror a Docker image into PlugLayer's managed Docker Hub namespace, then deploy it after backend compute checks |
+| `deploy_compose` | Deploy from docker-compose.yml after backend compute checks |
+| `list_deployments` | List running apps/deployments |
+| `get_deployment_status` | Check app status and URL |
+| `get_logs` | Get app logs |
+| `redeploy` | Redeploy an app |
+| `rollback` | Roll back to previous version |
+| `delete_deployment` | Delete an app |
+| `list_project_domains` | List custom domains for a project |
+| `add_custom_domain` | Add a single or wildcard custom domain and return DNS records |
+| `verify_custom_domain` | Verify TXT/CNAME DNS and activate if attached |
+| `attach_custom_domain` | Attach a verified custom domain to an app |
+| `detach_custom_domain` | Detach a domain while keeping verification |
+| `remove_custom_domain` | Remove a domain and its route |
+| `get_task_status` | Poll async operation progress |
+| `admin_get_overview` | Admin-only platform summary |
+| `admin_set_compute_defaults` | Admin-only default compute quota metadata |
+| `admin_set_node_shared` | Admin-only mark node shared/private |
+| `admin_add_shared_ssh_node` | Admin-only add shared PlugLayer SSH compute |
+| `generate_github_actions` | Get CI/CD pipeline YAML |
+| `get_cluster_health` | Check cluster status |
+
+## Example Conversations
+
+**Deploy your first app:**
+> "I have a FastAPI app at `ghcr.io/myorg/api:latest` that runs on port 8000. Deploy it to my `production` project."
+
+**Convert docker-compose:**
+> "Here's my docker-compose.yml: [paste]. Deploy this to PlugLayer."
+
+**Add a node:**
+> "Add my server at 192.168.1.100 as personal compute. Here's my SSH key: [paste]"
+
+**CI/CD setup:**
+> "Generate a GitHub Actions workflow for my `api` deployment so it auto-deploys on push to main."
+
+**Add a custom domain:**
+> "Add `api.example.com` to my production project, show me the DNS records, then verify it and attach it to my API app."
+
+## Getting Your API Key
+
+1. Go to PlugLayer Settings
+2. Create a **PlugLayer API token**
+3. Copy it once and store it safely
+4. Use it as `PLUGLAYER_API_KEY` for MCP, editor plugins, and CI/CD webhook deploys

pluglayer_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pluglayer_mcp/__init__.py,sha256=i-UC56Dp9hMpJ8y0JBpoaVdI_1NkS2FMfrKwe4QXURU,88
+pluglayer_mcp/client.py,sha256=yGaxDoIbvmP4W60oKDERZhuU8pag1kS1NY8bL43yhvQ,2339
+pluglayer_mcp/server.py,sha256=3_QJWNOBTZw6vKuedCX7CN8LZNfctX1Z-js1nCD_5zc,2679
+pluglayer_mcp/settings.py,sha256=sQahmaggkZjlELkm9qo9t0_4tEdxnUKUgzLGp5yA25Q,794
+pluglayer_mcp/tools/__init__.py,sha256=lZq6Dz0fyb8gnvUcEoKyjdYR11lCMLypgQFh3v0ykIA,37
+pluglayer_mcp/tools/cicd_health.py,sha256=oGOVOzOURlmnx9JPUI0wh28UASVcGhVgXPjRbuE5SZc,1802
+pluglayer_mcp/tools/compute.py,sha256=feY6EggpMOQThq_PHPyP-gAVQLiMt_qCaCVLoxzUj_g,4217
+pluglayer_mcp/tools/deployments.py,sha256=8DKjx9l6wh0dibEhCrYb_0yn0mOoQqdR8H7HDf6ib54,8204
+pluglayer_mcp/tools/domains.py,sha256=ugZ2JpfaGmrCbEzFUUk3UHWTWP3zrgGPO6r4zpwqR9Y,3643
+pluglayer_mcp/tools/identity_projects.py,sha256=e2vPdbG13jiJKlAgVg2coq_EGJ7Cipa1MMLPAiOM3sA,4296
+pluglayer_mcp/tools/shared.py,sha256=MnvmxKSiDzpo8cdydzXpQHT1_FT1H8XVTr34bEdEajk,1824
+pluglayer_mcp/tools/tasks_admin.py,sha256=wm8a9wAE0RNfXNKQZhZY6NiZuUR573CxjRG0-J2Do1w,5618
+pluglayer_mcp-0.1.0.dist-info/METADATA,sha256=DJsr9jhivB4PTSpOGs4-ZtRWwU4er6tHVFsCs5SDRLc,5284
+pluglayer_mcp-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pluglayer_mcp-0.1.0.dist-info/entry_points.txt,sha256=YpPpYKkwCdSPqJ2VH4I58_0YJQHUPXosNoc4YfFzaCQ,60
+pluglayer_mcp-0.1.0.dist-info/RECORD,,

pluglayer_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pluglayer_mcp-0.1.0.dist-info/entry_points.txt

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