refactor: integrate token exchange into unified get_client() pattern

Resolves the token exchange implementation gap where get_session_client()
was implemented but never used by tools. Unifies token acquisition into a
single async get_client() method that handles both pass-through and token
exchange modes transparently.

Core Changes:
- Make get_client() async and merge token exchange logic into it
- Remove scopes parameter from token exchange (Nextcloud doesn't support OAuth scopes)
- Update all 8 tool modules to use await get_client(ctx)
- Fix provisioning decorator to skip checks in BasicAuth mode

Token Acquisition Modes:
1. BasicAuth: Returns shared client (no token operations)
2. OAuth pass-through (default): Verifies and passes Flow 1 token to Nextcloud
3. OAuth token exchange (opt-in): Exchanges Flow 1 token for ephemeral token via RFC 8693

Key Architectural Clarifications:
- Progressive Consent (Flow 1/2) = Authorization architecture
- Token Exchange = Token acquisition pattern during tool execution
- Refresh tokens from Flow 2 are NEVER used for tool calls (only background jobs)
- Nextcloud scopes are "soft-scopes" enforced by MCP server, not IdP

Documentation Updates:
- ADR-004: Added comprehensive token acquisition patterns section
- CRITICAL-TOKEN-EXCHANGE-PATTERN.md: Updated to reflect implementation status
- CLAUDE.md: Updated architectural patterns with async get_client()

Testing:
- All 36 unit tests passing
- All 4 smoke tests passing (BasicAuth mode)
- Linting issues fixed (ruff)

Configuration:
ENABLE_TOKEN_EXCHANGE=false (default) - pass-through mode
ENABLE_TOKEN_EXCHANGE=true (opt-in) - token exchange mode

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

nextcloud_mcp_server/config.py

@@ -1,6 +1,7 @@
 import logging.config
 import os
-from typing import Any
+from dataclasses import dataclass
+from typing import Any, Optional
 
 LOGGING_CONFIG = {
     "version": 1,
@@ -118,3 +119,58 @@ def get_document_processor_config() -> dict[str, Any]:
             }
 
     return config
+
+
+@dataclass
+class Settings:
+    """Application settings from environment variables."""
+
+    # OAuth/OIDC settings
+    oidc_discovery_url: Optional[str] = None
+    oidc_client_id: Optional[str] = None
+    oidc_client_secret: Optional[str] = None
+
+    # Nextcloud settings
+    nextcloud_host: Optional[str] = None
+    nextcloud_username: Optional[str] = None
+    nextcloud_password: Optional[str] = None
+
+    # Progressive Consent settings
+    enable_progressive_consent: bool = False
+    enable_token_exchange: bool = False
+    enable_offline_access: bool = False
+
+    # Token settings
+    token_encryption_key: Optional[str] = None
+    token_storage_db: Optional[str] = None
+
+
+def get_settings() -> Settings:
+    """Get application settings from environment variables.
+
+    Returns:
+        Settings object with configuration values
+    """
+    return Settings(
+        # OAuth/OIDC settings
+        oidc_discovery_url=os.getenv("OIDC_DISCOVERY_URL"),
+        oidc_client_id=os.getenv("OIDC_CLIENT_ID"),
+        oidc_client_secret=os.getenv("OIDC_CLIENT_SECRET"),
+        # Nextcloud settings
+        nextcloud_host=os.getenv("NEXTCLOUD_HOST"),
+        nextcloud_username=os.getenv("NEXTCLOUD_USERNAME"),
+        nextcloud_password=os.getenv("NEXTCLOUD_PASSWORD"),
+        # Progressive Consent settings
+        enable_progressive_consent=(
+            os.getenv("ENABLE_PROGRESSIVE_CONSENT", "false").lower() == "true"
+        ),
+        enable_token_exchange=(
+            os.getenv("ENABLE_TOKEN_EXCHANGE", "false").lower() == "true"
+        ),
+        enable_offline_access=(
+            os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
+        ),
+        # Token settings
+        token_encryption_key=os.getenv("TOKEN_ENCRYPTION_KEY"),
+        token_storage_db=os.getenv("TOKEN_STORAGE_DB", "/tmp/tokens.db"),
+    )