feat(v3.12.0): media pipeline, AI image generation, capability probe, companion v2.9.0

Three-month batch sync from internal repo (~80 commits) covering Tracks F.5a, F.7e, F.8, F.17, F.18, F.X.

WordPress media pipeline
- Pillow-based optimization, AI image generation (OpenAI / Stability / Replicate / Google Nano Banana / OpenRouter), chunked + resumable uploads, bulk delete/reassign, idempotent retries.

Capability discovery (F.7e)
- Per-site credential probe + adapters for WordPress / WooCommerce / Gitea, tier-fit unions granted ∪ roles, capability badge UI with HTMX partial re-check, install hint in every companion-unreachable error.

Companion plugin overhaul
- Renamed wordpress-plugin/airano-mcp-seo-bridge → wordpress-plugin/airano-mcp-bridge.
- Eight new endpoints: /capabilities, /bulk-meta, /export, /cache-purge, /transient-flush, /site-health, /audit-hook, /upload-and-attach.
- wp.org Plugin Check pass: i18n, WP_Filesystem, scheme allowlist on audit-hook URL.

Other
- Gitea ergonomics (F.17): batch files, tree, search, compare, releases, fork.
- Opportunistic bcrypt upgrade for legacy SHA-256 admin keys (F.8).
- n8n refactor: structured errors, capability probe, missing tools backfilled.
- Idempotency-Key dedup for AI media upload retries; WP client fast-fails on unreachable sites.

Docs
- README + CLAUDE.md drop the fixed "633 tools" claim. The total grows with each release; per-plugin approximations + dashboard-surfaced counts replace it.
- Tools/Tests badges removed in favour of "Plugins: 10".

Deployment
- PyPI mirror chain, optional BUILD_HTTP_PROXY, Alpine→Yandex apk mirror, Debian-slim Plan-B Dockerfile, mirror.gcr.io variant.

CI
- Black + Ruff clean on Python 3.12; pytest tests/ green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

plugins/n8n/client.py

@@ -1,5 +1,4 @@
-"""
-n8n REST API Client
+"""n8n REST API Client.
 
 Handles all HTTP communication with n8n REST API.
 Separates API communication from business logic.
@@ -11,6 +10,64 @@ from typing import Any
 import aiohttp
 
 
+class N8nApiError(Exception):
+    """Base exception for n8n API errors with structured error info."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        error_code: str = "API_ERROR",
+        status_code: int = 0,
+        hint: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+        self.status_code = status_code
+        self.hint = hint
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"error_code": self.error_code, "message": str(self)}
+        if self.status_code:
+            d["status_code"] = self.status_code
+        if self.hint:
+            d["hint"] = self.hint
+        return d
+
+
+class N8nAuthError(N8nApiError):
+    """Raised on 401/403 — invalid or under-scoped API key."""
+
+    def __init__(self, message: str, *, status_code: int = 401, hint: str = "") -> None:
+        super().__init__(
+            message,
+            error_code="AUTH_FAILED",
+            status_code=status_code,
+            hint=hint or "Check the API key in n8n → Settings → API → API Keys.",
+        )
+
+
+class N8nNotFoundError(N8nApiError):
+    """Raised on 404 — resource doesn't exist."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, error_code="NOT_FOUND", status_code=404)
+
+
+class N8nValidationError(N8nApiError):
+    """Raised on 400/422 — bad payload."""
+
+    def __init__(self, message: str, *, status_code: int = 400) -> None:
+        super().__init__(message, error_code="VALIDATION_ERROR", status_code=status_code)
+
+
+class N8nConnectionError(N8nApiError):
+    """Raised on network-level failures."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, error_code="CONNECTION_ERROR")
+
+
 class N8nClient:
     """
     n8n REST API client for HTTP communication.
@@ -66,69 +123,63 @@ class N8nClient:
         json_data: dict | None = None,
         headers_override: dict | None = None,
     ) -> Any:
-        """
-        Make authenticated request to n8n REST API.
-
-        Args:
-            method: HTTP method (GET, POST, PUT, DELETE, PATCH)
-            endpoint: API endpoint (without base URL)
-            params: Query parameters
-            json_data: JSON body data
-            headers_override: Override default headers
-
-        Returns:
-            API response (dict, list, or None)
+        """Make authenticated request to n8n REST API.
 
         Raises:
-            Exception: On API errors with status code and message
+            N8nAuthError: On 401/403.
+            N8nNotFoundError: On 404.
+            N8nValidationError: On 400/422.
+            N8nApiError: On other 4xx/5xx.
+            N8nConnectionError: On network-level failure.
         """
-        # Build full URL
         url = f"{self.api_base}/{endpoint.lstrip('/')}"
-
-        # Setup headers
         headers = self._get_headers(headers_override)
 
-        # Filter out None values from params
         if params:
             params = {k: v for k, v in params.items() if v is not None}
-
-        # Filter None values from JSON data
         if json_data:
             json_data = {k: v for k, v in json_data.items() if v is not None}
 
-        # Make request
-        self.logger.debug(f"{method} {url}")
-        self.logger.debug(f"Params: {params}")
-        self.logger.debug(f"Data: {json_data}")
+        self.logger.debug("%s %s", method, url)
 
-        async with (
-            aiohttp.ClientSession() as session,
-            session.request(
-                method=method, url=url, params=params, json=json_data, headers=headers
-            ) as response,
-        ):
-            # Log response
-            self.logger.debug(f"Response status: {response.status}")
+        try:
+            async with (
+                aiohttp.ClientSession() as session,
+                session.request(
+                    method=method, url=url, params=params, json=json_data, headers=headers
+                ) as response,
+            ):
+                self.logger.debug("Response status: %d", response.status)
 
-            # Handle empty responses (e.g., 204 No Content)
-            if response.status == 204:
-                return {"success": True, "message": "Operation completed successfully"}
+                if response.status == 204:
+                    return {"success": True, "message": "Operation completed successfully"}
+
+                try:
+                    response_data = await response.json()
+                except Exception:
+                    response_text = await response.text()
+                    if response.status >= 400:
+                        self._raise_for_status(response.status, response_text)
+                    return {"success": True, "message": response_text}
 
-            # Try to parse JSON response
-            try:
-                response_data = await response.json()
-            except Exception:
-                response_text = await response.text()
                 if response.status >= 400:
-                    raise Exception(f"n8n API error (status {response.status}): {response_text}")
-                return {"success": True, "message": response_text}
+                    error_msg = response_data.get("message", str(response_data))
+                    self._raise_for_status(response.status, error_msg)
 
-            # Check for errors
-            if response.status >= 400:
-                error_msg = response_data.get("message", str(response_data))
-                raise Exception(f"n8n API error (status {response.status}): {error_msg}")
+                return response_data
 
-            return response_data
+        except (aiohttp.ClientError, OSError) as exc:
+            raise N8nConnectionError(f"Cannot reach n8n at {self.site_url}: {exc}") from exc
+
+    @staticmethod
+    def _raise_for_status(status: int, message: str) -> None:
+        if status in (401, 403):
+            raise N8nAuthError(message, status_code=status)
+        if status == 404:
+            raise N8nNotFoundError(message)
+        if status in (400, 422):
+            raise N8nValidationError(message, status_code=status)
+        raise N8nApiError(message, error_code="API_ERROR", status_code=status)
 
     # =====================
     # WORKFLOW ENDPOINTS
@@ -176,8 +227,18 @@ class N8nClient:
         """Execute a workflow manually"""
         return await self.request("POST", f"workflows/{workflow_id}/run", json_data=data or {})
 
+    async def transfer_workflow(
+        self, workflow_id: str, destination_project_id: str
+    ) -> dict[str, Any]:
+        """Transfer workflow to another project (Enterprise)."""
+        return await self.request(
+            "PUT",
+            f"workflows/{workflow_id}/transfer",
+            json_data={"destinationProjectId": destination_project_id},
+        )
+
     async def get_workflow_tags(self, workflow_id: str) -> list[dict[str, Any]]:
-        """Get tags assigned to a workflow"""
+        """Get tags assigned to a workflow."""
         workflow = await self.get_workflow(workflow_id)
         return workflow.get("tags", [])
 
@@ -189,14 +250,16 @@ class N8nClient:
         self,
         workflow_id: str | None = None,
         status: str | None = None,
+        project_id: str | None = None,
         include_data: bool = False,
         limit: int = 20,
         cursor: str | None = None,
     ) -> dict[str, Any]:
-        """List workflow executions with filters"""
+        """List workflow executions with filters."""
         params = {
             "workflowId": workflow_id,
             "status": status,
+            "projectId": project_id,
             "includeData": str(include_data).lower(),
             "limit": limit,
             "cursor": cursor,
@@ -391,12 +454,17 @@ class N8nClient:
             data["variables"] = variables
         return await self.request("POST", "source-control/pull", json_data=data)
 
+    async def get_current_user(self) -> dict[str, Any]:
+        """Get current authenticated user info (for capability probe)."""
+        return await self.request("GET", "user")
+
     async def health_check(self) -> dict[str, Any]:
-        """Check n8n instance health"""
-        # Use direct URL, not API base
+        """Check n8n instance health."""
         url = f"{self.site_url}/healthz"
-        async with aiohttp.ClientSession() as session, session.get(url) as response:
-            if response.status == 200:
-                return {"healthy": True, "status": "ok"}
-            else:
+        try:
+            async with aiohttp.ClientSession() as session, session.get(url) as response:
+                if response.status == 200:
+                    return {"healthy": True, "status": "ok"}
                 return {"healthy": False, "status": f"unhealthy (status {response.status})"}
+        except (aiohttp.ClientError, OSError) as exc:
+            raise N8nConnectionError(f"Cannot reach n8n health endpoint at {url}: {exc}") from exc

plugins/n8n/handlers/credentials.py

@@ -1,9 +1,15 @@
-"""Credentials Handler - manages n8n credentials"""
+"""Credentials Handler - manages n8n credentials."""
 
 import json
 from typing import Any
 
-from plugins.n8n.client import N8nClient
+from plugins.n8n.client import N8nApiError, N8nClient
+
+
+def _error_json(exc: Exception) -> str:
+    if isinstance(exc, N8nApiError):
+        return json.dumps({"success": False, **exc.to_dict()}, indent=2)
+    return json.dumps({"success": False, "error": str(exc)}, indent=2)
 
 
 def get_tool_specifications() -> list[dict[str, Any]]:
@@ -107,7 +113,7 @@ async def get_credential(client: N8nClient, credential_id: str) -> str:
         }
         return json.dumps(result, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def create_credential(client: N8nClient, name: str, type: str, data: dict[str, Any]) -> str:
@@ -126,7 +132,7 @@ async def create_credential(client: N8nClient, name: str, type: str, data: dict[
         }
         return json.dumps(result, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def delete_credential(client: N8nClient, credential_id: str) -> str:
@@ -137,7 +143,7 @@ async def delete_credential(client: N8nClient, credential_id: str) -> str:
             {"success": True, "message": f"Credential {credential_id} deleted"}, indent=2
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_credential_schema(client: N8nClient, credential_type: str) -> str:
@@ -148,7 +154,7 @@ async def get_credential_schema(client: N8nClient, credential_type: str) -> str:
             {"success": True, "credential_type": credential_type, "schema": schema}, indent=2
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def transfer_credential(
@@ -165,4 +171,4 @@ async def transfer_credential(
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)

plugins/n8n/handlers/executions.py

@@ -1,10 +1,16 @@
-"""Execution Handler - manages n8n workflow executions"""
+"""Execution Handler - manages n8n workflow executions."""
 
 import asyncio
 import json
 from typing import Any
 
-from plugins.n8n.client import N8nClient
+from plugins.n8n.client import N8nApiError, N8nClient
+
+
+def _error_json(exc: Exception) -> str:
+    if isinstance(exc, N8nApiError):
+        return json.dumps({"success": False, **exc.to_dict()}, indent=2)
+    return json.dumps({"success": False, "error": str(exc)}, indent=2)
 
 
 def get_tool_specifications() -> list[dict[str, Any]]:
@@ -27,6 +33,10 @@ def get_tool_specifications() -> list[dict[str, Any]]:
                         "enum": ["success", "error", "waiting", "running", "new"],
                         "description": "OPTIONAL: Filter by execution status. Omit for all statuses.",
                     },
+                    "project_id": {
+                        "type": "string",
+                        "description": "OPTIONAL: Filter by project ID (Enterprise). Omit for all projects.",
+                    },
                     "include_data": {
                         "type": "boolean",
                         "description": "Include full execution data",
@@ -200,15 +210,17 @@ async def list_executions(
     client: N8nClient,
     workflow_id: str | None = None,
     status: str | None = None,
+    project_id: str | None = None,
     include_data: bool = False,
     limit: int = 20,
     cursor: str | None = None,
 ) -> str:
-    """List workflow executions"""
+    """List workflow executions."""
     try:
         response = await client.list_executions(
             workflow_id=workflow_id,
             status=status,
+            project_id=project_id,
             include_data=include_data,
             limit=limit,
             cursor=cursor,
@@ -239,7 +251,7 @@ async def list_executions(
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_execution(client: N8nClient, execution_id: str, include_data: bool = True) -> str:
@@ -270,7 +282,7 @@ async def get_execution(client: N8nClient, execution_id: str, include_data: bool
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def delete_execution(client: N8nClient, execution_id: str) -> str:
@@ -283,7 +295,7 @@ async def delete_execution(client: N8nClient, execution_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def delete_executions(client: N8nClient, execution_ids: list[str]) -> str:
@@ -309,7 +321,7 @@ async def delete_executions(client: N8nClient, execution_ids: list[str]) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def stop_execution(client: N8nClient, execution_id: str) -> str:
@@ -322,7 +334,7 @@ async def stop_execution(client: N8nClient, execution_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def retry_execution(client: N8nClient, execution_id: str) -> str:
@@ -366,7 +378,7 @@ async def retry_execution(client: N8nClient, execution_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_execution_data(client: N8nClient, execution_id: str) -> str:
@@ -390,7 +402,7 @@ async def get_execution_data(client: N8nClient, execution_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def wait_for_execution(
@@ -444,4 +456,4 @@ async def wait_for_execution(
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)

plugins/n8n/handlers/projects.py

@@ -1,9 +1,15 @@
-"""Projects Handler - manages n8n projects (Enterprise/Pro)"""
+"""Projects Handler - manages n8n projects (Enterprise/Pro)."""
 
 import json
 from typing import Any
 
-from plugins.n8n.client import N8nClient
+from plugins.n8n.client import N8nApiError, N8nClient
+
+
+def _error_json(exc: Exception) -> str:
+    if isinstance(exc, N8nApiError):
+        return json.dumps({"success": False, **exc.to_dict()}, indent=2)
+    return json.dumps({"success": False, "error": str(exc)}, indent=2)
 
 
 def get_tool_specifications() -> list[dict[str, Any]]:
@@ -146,7 +152,7 @@ async def list_projects(client: N8nClient, limit: int = 100, cursor: str | None
         }
         return json.dumps(result, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_project(client: N8nClient, project_id: str) -> str:
@@ -157,7 +163,7 @@ async def get_project(client: N8nClient, project_id: str) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def create_project(client: N8nClient, name: str) -> str:
@@ -172,7 +178,7 @@ async def create_project(client: N8nClient, name: str) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def update_project(client: N8nClient, project_id: str, name: str) -> str:
@@ -187,7 +193,7 @@ async def update_project(client: N8nClient, project_id: str, name: str) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def delete_project(client: N8nClient, project_id: str) -> str:
@@ -195,7 +201,7 @@ async def delete_project(client: N8nClient, project_id: str) -> str:
         await client.delete_project(project_id)
         return json.dumps({"success": True, "message": f"Project {project_id} deleted"}, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def add_project_users(client: N8nClient, project_id: str, users: list[dict[str, str]]) -> str:
@@ -207,7 +213,7 @@ async def add_project_users(client: N8nClient, project_id: str, users: list[dict
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def change_project_user_role(
@@ -223,7 +229,7 @@ async def change_project_user_role(
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def remove_project_user(client: N8nClient, project_id: str, user_id: str) -> str:
@@ -234,4 +240,4 @@ async def remove_project_user(client: N8nClient, project_id: str, user_id: str)
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)

plugins/n8n/handlers/system.py

@@ -1,9 +1,15 @@
-"""System Handler - manages n8n system operations (audit, source control, health)"""
+"""System Handler - manages n8n system operations (audit, source control, health)."""
 
 import json
 from typing import Any
 
-from plugins.n8n.client import N8nClient
+from plugins.n8n.client import N8nApiError, N8nClient
+
+
+def _error_json(exc: Exception) -> str:
+    if isinstance(exc, N8nApiError):
+        return json.dumps({"success": False, **exc.to_dict()}, indent=2)
+    return json.dumps({"success": False, "error": str(exc)}, indent=2)
 
 
 def get_tool_specifications() -> list[dict[str, Any]]:
@@ -84,7 +90,7 @@ async def run_security_audit(client: N8nClient, categories: list[str] | None = N
 
         return json.dumps(audit_data, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def source_control_pull(
@@ -99,7 +105,7 @@ async def source_control_pull(
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_instance_info(client: N8nClient) -> str:
@@ -115,13 +121,12 @@ async def get_instance_info(client: N8nClient) -> str:
         except Exception:
             pass
 
-        # Get current user to verify connectivity
         try:
-            user = await client.request("GET", "user")
+            user = await client.get_current_user()
             info["current_user"] = {
                 "id": user.get("id"),
                 "email": user.get("email"),
-                "role": user.get("role"),
+                "role": user.get("role") or user.get("globalRole"),
             }
         except Exception:
             pass
@@ -131,7 +136,7 @@ async def get_instance_info(client: N8nClient) -> str:
 
         return json.dumps({"success": True, "instance_info": info}, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def health_check(client: N8nClient) -> str:

plugins/n8n/handlers/tags.py

@@ -1,9 +1,15 @@
-"""Tags Handler - manages n8n tags"""
+"""Tags Handler - manages n8n tags."""
 
 import json
 from typing import Any
 
-from plugins.n8n.client import N8nClient
+from plugins.n8n.client import N8nApiError, N8nClient
+
+
+def _error_json(exc: Exception) -> str:
+    if isinstance(exc, N8nApiError):
+        return json.dumps({"success": False, **exc.to_dict()}, indent=2)
+    return json.dumps({"success": False, "error": str(exc)}, indent=2)
 
 
 def get_tool_specifications() -> list[dict[str, Any]]:
@@ -99,7 +105,7 @@ async def list_tags(client: N8nClient, limit: int = 100, cursor: str | None = No
         }
         return json.dumps(result, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_tag(client: N8nClient, tag_id: str) -> str:
@@ -109,7 +115,7 @@ async def get_tag(client: N8nClient, tag_id: str) -> str:
             {"success": True, "tag": {"id": tag.get("id"), "name": tag.get("name")}}, indent=2
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def create_tag(client: N8nClient, name: str) -> str:
@@ -124,7 +130,7 @@ async def create_tag(client: N8nClient, name: str) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def update_tag(client: N8nClient, tag_id: str, name: str) -> str:
@@ -139,7 +145,7 @@ async def update_tag(client: N8nClient, tag_id: str, name: str) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def delete_tag(client: N8nClient, tag_id: str) -> str:
@@ -147,7 +153,7 @@ async def delete_tag(client: N8nClient, tag_id: str) -> str:
         await client.delete_tag(tag_id)
         return json.dumps({"success": True, "message": f"Tag {tag_id} deleted"}, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def delete_tags(client: N8nClient, tag_ids: list[str]) -> str:
@@ -164,4 +170,4 @@ async def delete_tags(client: N8nClient, tag_ids: list[str]) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)

plugins/n8n/handlers/users.py

@@ -1,9 +1,15 @@
-"""Users Handler - manages n8n users"""
+"""Users Handler - manages n8n users."""
 
 import json
 from typing import Any
 
-from plugins.n8n.client import N8nClient
+from plugins.n8n.client import N8nApiError, N8nClient
+
+
+def _error_json(exc: Exception) -> str:
+    if isinstance(exc, N8nApiError):
+        return json.dumps({"success": False, **exc.to_dict()}, indent=2)
+    return json.dumps({"success": False, "error": str(exc)}, indent=2)
 
 
 def get_tool_specifications() -> list[dict[str, Any]]:
@@ -115,7 +121,7 @@ async def list_users(
         }
         return json.dumps(result, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_user(client: N8nClient, user_id: str, include_role: bool = True) -> str:
@@ -136,7 +142,7 @@ async def get_user(client: N8nClient, user_id: str, include_role: bool = True) -
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def create_user(client: N8nClient, email: str, role: str = "global:member") -> str:
@@ -152,7 +158,7 @@ async def create_user(client: N8nClient, email: str, role: str = "global:member"
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def delete_user(client: N8nClient, user_id: str) -> str:
@@ -160,7 +166,7 @@ async def delete_user(client: N8nClient, user_id: str) -> str:
         await client.delete_user(user_id)
         return json.dumps({"success": True, "message": f"User {user_id} deleted"}, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def change_user_role(client: N8nClient, user_id: str, new_role: str) -> str:
@@ -170,4 +176,4 @@ async def change_user_role(client: N8nClient, user_id: str, new_role: str) -> st
             {"success": True, "message": f"User {user_id} role changed to {new_role}"}, indent=2
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)

plugins/n8n/handlers/variables.py

@@ -1,9 +1,15 @@
-"""Variables Handler - manages n8n environment variables"""
+"""Variables Handler - manages n8n environment variables."""
 
 import json
 from typing import Any
 
-from plugins.n8n.client import N8nClient
+from plugins.n8n.client import N8nApiError, N8nClient
+
+
+def _error_json(exc: Exception) -> str:
+    if isinstance(exc, N8nApiError):
+        return json.dumps({"success": False, **exc.to_dict()}, indent=2)
+    return json.dumps({"success": False, "error": str(exc)}, indent=2)
 
 
 def get_tool_specifications() -> list[dict[str, Any]]:
@@ -106,7 +112,7 @@ async def list_variables(client: N8nClient, limit: int = 100, cursor: str | None
         }
         return json.dumps(result, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_variable(client: N8nClient, key: str) -> str:
@@ -120,7 +126,7 @@ async def get_variable(client: N8nClient, key: str) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def create_variable(client: N8nClient, key: str, value: str) -> str:
@@ -135,7 +141,7 @@ async def create_variable(client: N8nClient, key: str, value: str) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def update_variable(client: N8nClient, key: str, value: str) -> str:
@@ -150,7 +156,7 @@ async def update_variable(client: N8nClient, key: str, value: str) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def delete_variable(client: N8nClient, key: str) -> str:
@@ -158,7 +164,7 @@ async def delete_variable(client: N8nClient, key: str) -> str:
         await client.delete_variable(key)
         return json.dumps({"success": True, "message": f"Variable '{key}' deleted"}, indent=2)
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def set_variables(client: N8nClient, variables: dict[str, str]) -> str:
@@ -190,4 +196,4 @@ async def set_variables(client: N8nClient, variables: dict[str, str]) -> str:
             indent=2,
         )
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)

plugins/n8n/handlers/workflows.py

@@ -1,9 +1,9 @@
-"""Workflow Handler - manages n8n workflows"""
+"""Workflow Handler - manages n8n workflows."""
 
 import json
 from typing import Any
 
-from plugins.n8n.client import N8nClient
+from plugins.n8n.client import N8nApiError, N8nClient
 
 
 def get_tool_specifications() -> list[dict[str, Any]]:
@@ -318,12 +318,45 @@ def get_tool_specifications() -> list[dict[str, Any]]:
             },
             "scope": "write",
         },
+        # === TRANSFER WORKFLOW TO PROJECT (Enterprise) ===
+        {
+            "name": "transfer_workflow_to_project",
+            "method_name": "transfer_workflow_to_project",
+            "description": (
+                "Transfer a workflow to a different project (Enterprise/Pro). "
+                "The destination project must exist and the API key must have "
+                "access to both the source and destination projects."
+            ),
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "workflow_id": {
+                        "type": "string",
+                        "description": "Workflow ID to transfer",
+                        "minLength": 1,
+                    },
+                    "destination_project_id": {
+                        "type": "string",
+                        "description": "Target project ID",
+                        "minLength": 1,
+                    },
+                },
+                "required": ["workflow_id", "destination_project_id"],
+            },
+            "scope": "write",
+        },
     ]
 
 
 # === HANDLER FUNCTIONS ===
 
 
+def _error_json(exc: Exception) -> str:
+    if isinstance(exc, N8nApiError):
+        return json.dumps({"success": False, **exc.to_dict()}, indent=2)
+    return json.dumps({"success": False, "error": str(exc)}, indent=2)
+
+
 async def list_workflows(
     client: N8nClient,
     active: bool | None = None,
@@ -361,7 +394,7 @@ async def list_workflows(
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_workflow(client: N8nClient, workflow_id: str) -> str:
@@ -388,7 +421,7 @@ async def get_workflow(client: N8nClient, workflow_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def create_workflow(
@@ -429,7 +462,7 @@ async def create_workflow(
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def update_workflow(
@@ -470,7 +503,7 @@ async def update_workflow(
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def delete_workflow(client: N8nClient, workflow_id: str) -> str:
@@ -483,7 +516,7 @@ async def delete_workflow(client: N8nClient, workflow_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def activate_workflow(client: N8nClient, workflow_id: str) -> str:
@@ -504,7 +537,7 @@ async def activate_workflow(client: N8nClient, workflow_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def deactivate_workflow(client: N8nClient, workflow_id: str) -> str:
@@ -525,7 +558,7 @@ async def deactivate_workflow(client: N8nClient, workflow_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def execute_workflow(client: N8nClient, workflow_id: str) -> str:
@@ -546,7 +579,7 @@ async def execute_workflow(client: N8nClient, workflow_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def execute_workflow_with_data(
@@ -570,7 +603,7 @@ async def execute_workflow_with_data(
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def duplicate_workflow(client: N8nClient, workflow_id: str, new_name: str) -> str:
@@ -599,7 +632,7 @@ async def duplicate_workflow(client: N8nClient, workflow_id: str, new_name: str)
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def export_workflow(client: N8nClient, workflow_id: str) -> str:
@@ -613,7 +646,7 @@ async def export_workflow(client: N8nClient, workflow_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def import_workflow(
@@ -646,7 +679,7 @@ async def import_workflow(
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def get_workflow_tags(client: N8nClient, workflow_id: str) -> str:
@@ -659,7 +692,7 @@ async def get_workflow_tags(client: N8nClient, workflow_id: str) -> str:
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
 
 
 async def set_workflow_tags(
@@ -693,4 +726,23 @@ async def set_workflow_tags(
         return json.dumps(result, indent=2)
 
     except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, indent=2)
+        return _error_json(e)
+
+
+async def transfer_workflow_to_project(
+    client: N8nClient, workflow_id: str, destination_project_id: str
+) -> str:
+    """Transfer a workflow to another project (Enterprise)."""
+    try:
+        await client.transfer_workflow(workflow_id, destination_project_id)
+        return json.dumps(
+            {
+                "success": True,
+                "message": f"Workflow {workflow_id} transferred to project {destination_project_id}",
+                "workflow_id": workflow_id,
+                "destination_project_id": destination_project_id,
+            },
+            indent=2,
+        )
+    except Exception as e:
+        return _error_json(e)

plugins/n8n/plugin.py

@@ -18,8 +18,8 @@ class N8nPlugin(BasePlugin):
     n8n Automation Plugin - Comprehensive workflow management.
 
     Provides complete n8n management capabilities including:
-    - Workflow management (CRUD, activate, deactivate, execute)
-    - Execution monitoring (list, get, delete, retry, wait)
+    - Workflow management (CRUD, activate, deactivate, execute, transfer)
+    - Execution monitoring (list, get, delete, retry, wait, project filter)
     - Credential management (get, create, delete, schema, transfer)
     - Tag management (CRUD, bulk delete)
     - User management (CRUD, roles)
@@ -27,7 +27,7 @@ class N8nPlugin(BasePlugin):
     - Variable management (CRUD, bulk set) - Enterprise/Pro
     - System operations (audit, source control, health)
 
-    Total: 56 tools
+    Total: 57 tools
     """
 
     @staticmethod
@@ -69,7 +69,7 @@ class N8nPlugin(BasePlugin):
         specs = []
 
         # Collect specifications from all handlers
-        specs.extend(handlers.workflows.get_tool_specifications())  # 14 tools
+        specs.extend(handlers.workflows.get_tool_specifications())  # 15 tools
         specs.extend(handlers.executions.get_tool_specifications())  # 8 tools
         specs.extend(handlers.credentials.get_tool_specifications())  # 5 tools
         specs.extend(handlers.tags.get_tool_specifications())  # 6 tools
@@ -118,24 +118,62 @@ class N8nPlugin(BasePlugin):
         # Method not found in any handler
         raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")
 
+    async def probe_credential_capabilities(self) -> dict[str, Any]:
+        """F.7e — probe the n8n API key's effective permissions.
+
+        Calls ``GET /api/v1/user`` which returns the current user's
+        ``globalRole`` (and ``globalScopes`` on enterprise). If the key
+        is invalid or the endpoint is unreachable we return a graceful
+        fallback so the dashboard can still render a status badge.
+        """
+        from plugins.n8n.client import N8nAuthError, N8nConnectionError
+
+        try:
+            user = await self.client.get_current_user()
+        except N8nAuthError as exc:
+            return {
+                "probe_available": False,
+                "granted": [],
+                "source": "n8n_api",
+                "reason": f"auth_failed: {exc}",
+            }
+        except (N8nConnectionError, Exception) as exc:  # noqa: BLE001
+            return {
+                "probe_available": False,
+                "granted": [],
+                "source": "n8n_api",
+                "reason": f"probe_failed: {exc}",
+            }
+
+        role_name = ""
+        role_obj = user.get("role") or user.get("globalRole") or ""
+        if isinstance(role_obj, dict):
+            role_name = role_obj.get("name", "")
+        elif isinstance(role_obj, str):
+            role_name = role_obj
+        scopes = user.get("globalScopes") or []
+
+        return {
+            "probe_available": True,
+            "granted": sorted(scopes) if scopes else [role_name],
+            "source": "n8n_api",
+            "role": role_name,
+            "email": user.get("email", ""),
+        }
+
     async def check_health(self) -> dict[str, Any]:
-        """
-        Check if n8n instance is accessible (internal use).
-
-        Note: This is named check_health to avoid shadowing the handler's
-        health_check function which is exposed as an MCP tool.
-
-        Returns:
-            Dict containing health check result
-        """
+        """Check if n8n instance is accessible (internal use)."""
         try:
             result = await self.client.health_check()
             return {
                 "healthy": result.get("healthy", False),
-                "message": f"n8n instance at {self.client.site_url} is {'accessible' if result.get('healthy') else 'not accessible'}",
+                "message": (
+                    f"n8n instance at {self.client.site_url} is "
+                    f"{'accessible' if result.get('healthy') else 'not accessible'}"
+                ),
             }
         except Exception as e:
-            return {"healthy": False, "message": f"n8n health check failed: {str(e)}"}
+            return {"healthy": False, "message": f"n8n health check failed: {e}"}
 
     async def health_check(self, **kwargs) -> str:
         """