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/server/notes.py

@@ -29,7 +29,7 @@ def configure_notes_tools(mcp: FastMCP):
         ctx: Context = (
             mcp.get_context()
         )  # https://github.com/modelcontextprotocol/python-sdk/issues/244
-        client = get_client(ctx)
+        client = await get_client(ctx)
         settings_data = await client.notes.get_settings()
         return NotesSettings(**settings_data)
 
@@ -37,7 +37,7 @@ def configure_notes_tools(mcp: FastMCP):
     async def nc_notes_get_attachment_resource(note_id: int, attachment_filename: str):
         """Get a specific attachment from a note"""
         ctx: Context = mcp.get_context()
-        client = get_client(ctx)
+        client = await get_client(ctx)
         # Assuming a method get_note_attachment exists in the client
         # This method should return the raw content and determine the mime type
         content, mime_type = await client.webdav.get_note_attachment(
@@ -59,7 +59,7 @@ def configure_notes_tools(mcp: FastMCP):
         """Get user note using note id"""
 
         ctx: Context = mcp.get_context()
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.get_note(note_id)
             return Note(**note_data)
@@ -92,7 +92,7 @@ def configure_notes_tools(mcp: FastMCP):
         title: str, content: str, category: str, ctx: Context
     ) -> CreateNoteResponse:
         """Create a new note (requires notes:write scope)"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.create_note(
                 title=title,
@@ -149,7 +149,7 @@ def configure_notes_tools(mcp: FastMCP):
         If the note has been modified by someone else since you retrieved it,
         the update will fail with a 412 error."""
         logger.info("Updating note %s", note_id)
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.update(
                 note_id=note_id,
@@ -206,7 +206,7 @@ def configure_notes_tools(mcp: FastMCP):
         between the note and what will be appended."""
 
         logger.info("Appending content to note %s", note_id)
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.append_content(
                 note_id=note_id, content=content
@@ -252,7 +252,7 @@ def configure_notes_tools(mcp: FastMCP):
     @require_provisioning
     async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
         """Search notes by title or content, returning only id, title, and category (requires notes:read scope)."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             search_results_raw = await client.notes_search_notes(query=query)
 
@@ -298,7 +298,7 @@ def configure_notes_tools(mcp: FastMCP):
     @require_scopes("notes:read")
     async def nc_notes_get_note(note_id: int, ctx: Context) -> Note:
         """Get a specific note by its ID (requires notes:read scope)"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.get_note(note_id)
             return Note(**note_data)
@@ -329,7 +329,7 @@ def configure_notes_tools(mcp: FastMCP):
         note_id: int, attachment_filename: str, ctx: Context
     ) -> dict[str, str]:
         """Get a specific attachment from a note"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             content, mime_type = await client.webdav.get_note_attachment(
                 note_id=note_id, filename=attachment_filename
@@ -374,7 +374,7 @@ def configure_notes_tools(mcp: FastMCP):
     async def nc_notes_delete_note(note_id: int, ctx: Context) -> DeleteNoteResponse:
         """Delete a note permanently"""
         logger.info("Deleting note %s", note_id)
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             await client.notes.delete_note(note_id)
             return DeleteNoteResponse(