feat(auth): elicit Astrolabe URL on missing app password

When a tool requiring Nextcloud access is called without a stored app
password (Login Flow v2 mode), the @require_scopes decorator now invokes
MCP elicitation with a clickable Astrolabe settings URL — reconstructed
from NEXTCLOUD_PUBLIC_ISSUER_URL / NEXTCLOUD_HOST — before raising
ProvisioningRequiredError. Clients without elicitation support fall back
to the existing text error.

Surfaced by cbcoutinho/nextcloud-mcp-server#752, where users hit a 401
after OAuth and had no clickable URL to start Login Flow v2 from.

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

nextcloud_mcp_server/auth/elicitation.py

@@ -5,12 +5,21 @@ when the client supports it, or falling back to returning the URL in a message.
 """
 
 import logging
+import os
 
 from mcp.server.fastmcp import Context
 from pydantic import BaseModel, Field
 
 logger = logging.getLogger(__name__)
 
+# Path of the Astrolabe Nextcloud app's settings UI. The full URL is
+# reconstructed at elicitation time from NEXTCLOUD_PUBLIC_ISSUER_URL /
+# NEXTCLOUD_HOST so the user gets a browser-reachable link without needing a
+# separate config knob. If the Astrolabe app is not installed this path will
+# 404, and the user falls back to the nc_auth_provision_access tool path
+# mentioned in the same message.
+ASTROLABE_SETTINGS_PATH = "/index.php/apps/astrolabe/settings"
+
 
 class LoginFlowConfirmation(BaseModel):
     """Schema for Login Flow v2 confirmation elicitation."""
@@ -21,6 +30,30 @@ class LoginFlowConfirmation(BaseModel):
     )
 
 
+class ProvisioningRequiredConfirmation(BaseModel):
+    """Schema for the 'app password not provisioned' elicitation."""
+
+    acknowledged: bool = Field(
+        default=False,
+        description="Check this box after enabling Nextcloud access",
+    )
+
+
+def _astrolabe_settings_url() -> str | None:
+    """Construct the Astrolabe settings page URL from environment.
+
+    Prefers ``NEXTCLOUD_PUBLIC_ISSUER_URL`` (the browser-reachable public URL)
+    over ``NEXTCLOUD_HOST`` (which may be an internal hostname in Docker
+    deployments). Returns None if neither is set.
+    """
+    base = (
+        os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL") or os.getenv("NEXTCLOUD_HOST") or ""
+    ).strip()
+    if not base:
+        return None
+    return f"{base.rstrip('/')}{ASTROLABE_SETTINGS_PATH}"
+
+
 async def present_login_url(
     ctx: Context,
     login_url: str,
@@ -86,3 +119,79 @@ async def present_login_url(
             "falling back to message"
         )
         return "message_only"
+
+
+async def present_provisioning_required(ctx: Context) -> str:
+    """Elicit a provisioning prompt when a tool is called without an app password.
+
+    Used by the ``@require_scopes`` decorator (Login Flow v2 path) to give
+    the user a clickable Astrolabe settings URL — or a fallback instruction
+    to call the ``nc_auth_provision_access`` MCP tool — instead of just
+    raising a plain ``ProvisioningRequiredError`` text message that an LLM
+    has to translate.
+
+    The Astrolabe settings URL is reconstructed from
+    ``NEXTCLOUD_PUBLIC_ISSUER_URL`` / ``NEXTCLOUD_HOST``; if Astrolabe is not
+    installed the link 404s and the user falls back to the tool path
+    suggested in the same message.
+
+    Returns:
+        Same string contract as :func:`present_login_url`:
+        ``"accepted"`` / ``"declined"`` / ``"cancelled"`` / ``"message_only"``.
+    """
+    settings_url = _astrolabe_settings_url()
+
+    if settings_url:
+        message = (
+            "Nextcloud access is not yet provisioned for this user.\n\n"
+            f"Open this URL to enable it via the Astrolabe app:\n\n{settings_url}\n\n"
+            "If the Astrolabe app is not installed, ask your MCP client to call "
+            "the `nc_auth_provision_access` tool instead — it will return a "
+            "Login Flow v2 URL you can open directly.\n\n"
+            "Then check the box below and retry the original request."
+        )
+    else:
+        message = (
+            "Nextcloud access is not yet provisioned for this user.\n\n"
+            "Ask your MCP client to call the `nc_auth_provision_access` tool — "
+            "it will return a Login Flow v2 URL you can open in your browser to "
+            "grant access.\n\n"
+            "Then check the box below and retry the original request."
+        )
+
+    if not hasattr(ctx, "elicit"):
+        logger.debug(
+            "Elicitation not available on context — returning message_only "
+            "(plain ProvisioningRequiredError will surface to the caller)"
+        )
+        return "message_only"
+
+    try:
+        result = await ctx.elicit(
+            message=message,
+            schema=ProvisioningRequiredConfirmation,
+        )
+
+        if result.action == "accept":
+            logger.info("User acknowledged provisioning-required prompt")
+            return "accepted"
+        elif result.action == "decline":
+            logger.info("User declined provisioning-required prompt")
+            return "declined"
+        else:
+            logger.info("User cancelled provisioning-required prompt")
+            return "cancelled"
+
+    except NotImplementedError:
+        logger.debug(
+            "Elicitation not supported by client — falling back to plain error"
+        )
+        return "message_only"
+    except Exception as e:
+        logger.warning(
+            "Provisioning elicitation failed unexpectedly (%s: %s), "
+            "falling back to plain error",
+            type(e).__name__,
+            e,
+        )
+        return "message_only"

nextcloud_mcp_server/auth/scope_authorization.py

@@ -151,7 +151,16 @@ def require_scopes(*required_scopes: str):
                     stored_scopes = await _get_stored_scopes(user_id)
 
                     if stored_scopes is None:
-                        # No stored app password → require provisioning
+                        # No stored app password → require provisioning. Try to
+                        # elicit a clickable Astrolabe / Login-Flow-v2 link so
+                        # the user has somewhere to click; the elicit helper
+                        # silently falls back when the client lacks support.
+                        from nextcloud_mcp_server.auth.elicitation import (  # noqa: PLC0415
+                            present_provisioning_required,
+                        )
+
+                        await present_provisioning_required(ctx)
+
                         error_msg = (
                             f"Access denied to {func_name}: "
                             f"Nextcloud access not provisioned. "