pluglayer-mcp 0.1.0__tar.gz

pluglayer_mcp-0.1.0/.github/workflows/deploy-uvx-main.yml

@@ -0,0 +1,70 @@
+name: Publish pluglayer-mcp
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - pyproject.toml
+      - uv.lock
+      - README.md
+      - pluglayer_mcp/**
+      - .github/workflows/deploy-uvx.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: publish-pluglayer-mcp
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    steps:
+      - name: Checkout package repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Validate package metadata
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          test -f pyproject.toml
+          test -f pluglayer_mcp/server.py
+          test -f README.md
+
+          uv sync --frozen
+          uv run python -m compileall pluglayer_mcp
+
+      - name: Build distributions
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv build
+
+      - name: Publish to PyPI
+        shell: bash
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          if [[ -n "${UV_PUBLISH_TOKEN:-}" ]]; then
+            uv publish
+          else
+            uv publish --trusted-publishing always
+          fi

pluglayer_mcp-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,130 @@
+# 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/pluglayer_mcp/__init__.py

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

pluglayer_mcp-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-0.1.0/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-0.1.0/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-0.1.0/pluglayer_mcp/tools/__init__.py

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

pluglayer_mcp-0.1.0/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-0.1.0/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)