bump: version 0.14.0 → 0.14.1

fix(oauth): Remove the option to force_register new clients

CHANGELOG.md

@@ -1,3 +1,21 @@
+## v0.14.1 (2025-10-15)
+
+### Fix
+
+- **oauth**: Remove the option to force_register new clients
+
+## v0.14.0 (2025-10-15)
+
+### Feat
+
+- Add Groups API client
+- add sharing API client and server tools
+- **users**: Initialize user API client
+
+### Fix
+
+- Update user/groups API to OCS v2
+
 ## v0.13.0 (2025-10-13)
 
 ### Feat

CLAUDE.md

@@ -135,16 +135,15 @@ Each Nextcloud app has a corresponding server module that:
 OAuth integration tests support both **automated** (Playwright) and **interactive** authentication flows:
 
 **Automated Testing (Default - Recommended for CI/CD):**
-- **Default fixtures**: `nc_oauth_client`, `nc_mcp_oauth_client` now use Playwright automation by default
+- **Default fixtures**: `nc_oauth_client`, `nc_mcp_oauth_client` use Playwright automation
 - Uses Playwright headless browser automation to complete OAuth flow programmatically
-- **Shared OAuth Client**: All test users authenticate using a single OAuth client (matching MCP server behavior)
-  - Single `client_id`/`client_secret` pair is registered and reused for all test users
-  - Stored in `.nextcloud_oauth_shared_test_client.json` with `force_register=False` for reuse
-  - Reduces OAuth client registrations and matches production MCP server architecture
+- **Shared OAuth Client**: All test users authenticate using a single OAuth client
+  - Stored in `.nextcloud_oauth_shared_test_client.json`
+  - Matches production MCP server behavior
+  - Each user gets their own unique access token
+  - Implementation: `shared_oauth_client_credentials` fixture in `tests/conftest.py:812`
 - All Playwright fixtures: `playwright_oauth_token`, `nc_oauth_client`, `nc_mcp_oauth_client`, `nc_oauth_client_playwright`, `nc_mcp_oauth_client_playwright`
 - Multi-user fixtures: `alice_oauth_token`, `bob_oauth_token`, `charlie_oauth_token`, `diana_oauth_token`
-  - All use `shared_oauth_client_credentials` fixture for consistent client credentials
-  - Each user gets unique access tokens via same OAuth client (like multiple users using the MCP server)
 - Requires: `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD` environment variables
 - Uses `pytest-playwright-asyncio` for async Playwright fixtures
 - Playwright configuration: Use pytest CLI args like `--browser firefox --headed` to customize
@@ -179,14 +178,12 @@ OAuth integration tests support both **automated** (Playwright) and **interactiv
   - `mcp-oauth` (port 8001): Uses OAuth authentication - for OAuth-specific testing
 - Start OAuth MCP server: `docker-compose up --build -d mcp-oauth`
 - **Important**: When working on OAuth functionality, always rebuild `mcp-oauth` container, not `mcp`
-- Shared OAuth client is registered once and reused across test runs
-- Client credentials cached in `.nextcloud_oauth_shared_test_client.json`
+- OAuth client credentials cached in `.nextcloud_oauth_shared_test_client.json`
 
 **CI/CD Considerations:**
 - Interactive OAuth tests are automatically skipped when `GITHUB_ACTIONS` environment variable is set
 - Automated Playwright tests will run in CI/CD environments
 - Use Firefox browser in CI: `--browser firefox` (Chromium may have issues with localhost redirects)
-- Shared client approach reduces test time and API calls to Nextcloud
 
 ### Configuration Files
 

README.md

@@ -6,6 +6,9 @@
 
 The Nextcloud MCP (Model Context Protocol) server allows Large Language Models like Claude, GPT, and Gemini to interact with your Nextcloud data through a secure API. Create notes, manage calendars, organize contacts, work with files, and more - all through natural language.
 
+> [!NOTE]
+> **Nextcloud has two ways to enable AI access:** Nextcloud provides [Context Agent](https://github.com/nextcloud/context_agent), an AI agent backend that powers the [Assistant](https://github.com/nextcloud/assistant) app and allows AI to interact with Nextcloud apps like Calendar, Talk, and Contacts. Context Agent runs as an ExApp inside Nextcloud and also exposes an MCP server endpoint for external LLMs. This project (Nextcloud MCP Server) is a **dedicated standalone MCP server** designed specifically for external MCP clients like Claude Code and IDEs, with deep CRUD operations and OAuth support. See our [detailed comparison](docs/comparison-context-agent.md) to understand which approach fits your use case.
+
 ## Features
 
 ### Supported Nextcloud Apps
@@ -120,6 +123,9 @@ Or connect from:
 - **[Authentication](docs/authentication.md)** - OAuth vs BasicAuth
 - **[Running the Server](docs/running.md)** - Start and manage the server
 
+### Architecture
+- **[Comparison with Context Agent](docs/comparison-context-agent.md)** - How this MCP server differs from Nextcloud's Context Agent
+
 ### OAuth Documentation
 - **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute setup guide
 - **[OAuth Setup Guide](docs/oauth-setup.md)** - Production deployment

docs/comparison-context-agent.md

@@ -0,0 +1,698 @@
+# MCP Server Comparison: Nextcloud MCP Server vs Context Agent
+
+This document compares the two MCP server implementations in the Nextcloud ecosystem:
+
+1. **Nextcloud MCP Server** (this project) - Standalone MCP server for external access to Nextcloud
+2. **Context Agent MCP Server** - MCP server embedded within Nextcloud as an External App
+
+## Executive Summary
+
+Both projects expose Nextcloud functionality via the Model Context Protocol (MCP), but serve different purposes and audiences:
+
+- **Nextcloud MCP Server**: Brings Nextcloud OUT to external MCP clients (Claude Code, etc.)
+- **Context Agent**: Brings external MCP servers IN to Nextcloud's AI Assistant
+
+## Architecture Overview
+
+```mermaid
+graph TB
+    subgraph External["External Clients"]
+        CC[Claude Code]
+        IDE[IDEs with MCP]
+        APP[Other MCP Clients]
+    end
+
+    subgraph NMCP["Nextcloud MCP Server<br/>(This Project)"]
+        NMCP_Server[FastMCP Server]
+        NMCP_Client[HTTP Clients]
+        NMCP_Auth[OAuth/BasicAuth]
+    end
+
+    subgraph NC["Nextcloud Instance"]
+        subgraph CA["Context Agent ExApp"]
+            CA_Agent[LangGraph Agent]
+            CA_MCP[MCP Server /mcp]
+            CA_Tools[Tool Loader]
+        end
+
+        NC_Apps[Nextcloud Apps<br/>Notes, Calendar, Files, etc.]
+        NC_Assistant[Assistant App]
+    end
+
+    subgraph ExtMCP["External MCP Servers"]
+        Weather[Weather MCP]
+        Other[Other Services]
+    end
+
+    %% External clients connect to standalone MCP server
+    CC --> NMCP_Server
+    IDE --> NMCP_Server
+    APP --> NMCP_Server
+
+    %% Standalone MCP server talks to Nextcloud over HTTP
+    NMCP_Server --> NMCP_Auth
+    NMCP_Auth --> NMCP_Client
+    NMCP_Client -->|HTTP/HTTPS| NC_Apps
+
+    %% Context Agent is inside Nextcloud
+    CA_Agent --> CA_Tools
+    CA_Tools --> NC_Apps
+    CA_MCP -->|Exposes to| NC_Assistant
+    NC_Assistant -->|User requests| CA_Agent
+
+    %% Context Agent can consume external MCP servers
+    CA_Tools -->|Consumes| ExtMCP
+
+    %% Context Agent could consume Nextcloud MCP Server
+    CA_Tools -.->|Could consume| NMCP_Server
+
+    classDef external fill:#e1f5ff
+    classDef standalone fill:#fff4e1
+    classDef internal fill:#e8f5e9
+
+    class CC,IDE,APP external
+    class NMCP_Server,NMCP_Client,NMCP_Auth standalone
+    class CA_Agent,CA_MCP,CA_Tools,NC_Apps,NC_Assistant internal
+```
+
+## Deployment Models
+
+```mermaid
+graph LR
+    subgraph Deploy1["Nextcloud MCP Server Deployment"]
+        direction TB
+        D1[Docker Container]
+        D2[Cloud VM]
+        D3[Local Machine]
+        D4[Kubernetes Pod]
+    end
+
+    subgraph Deploy2["Context Agent Deployment"]
+        direction TB
+        NC[Nextcloud Instance<br/>with AppAPI]
+        ExApp[External App Container<br/>Managed by Nextcloud]
+    end
+
+    Deploy1 -.->|HTTP/HTTPS| NC
+    ExApp -->|Integrated| NC
+
+    classDef deploy fill:#fff4e1
+    classDef integrated fill:#e8f5e9
+
+    class D1,D2,D3,D4 deploy
+    class NC,ExApp integrated
+```
+
+### Nextcloud MCP Server
+- **Location**: Runs anywhere with network access to Nextcloud
+- **Deployment**: Docker, VM, local machine, Kubernetes
+- **Connection**: HTTP/HTTPS to Nextcloud APIs
+- **Independence**: Fully standalone service
+
+### Context Agent
+- **Location**: Runs inside Nextcloud as External App
+- **Deployment**: Managed by Nextcloud AppAPI
+- **Connection**: Native nc-py-api integration
+- **Integration**: Deep Nextcloud integration
+
+## Authentication Architecture
+
+```mermaid
+graph TB
+    subgraph NMCP_Auth["Nextcloud MCP Server Authentication"]
+        direction TB
+        Client1[MCP Client]
+
+        subgraph BasicAuth["BasicAuth Mode"]
+            BA_Shared[Shared NextcloudClient]
+            BA_Creds[Username + Password]
+        end
+
+        subgraph OAuth["OAuth Mode"]
+            OAuth_Token[OAuth Token]
+            OAuth_Verify[Token Verifier]
+            OAuth_OIDC[OIDC Discovery]
+            OAuth_Client[Per-Request Client]
+        end
+
+        Client1 -->|Basic Auth| BasicAuth
+        Client1 -->|Bearer Token| OAuth
+        BA_Creds --> BA_Shared
+        OAuth_Token --> OAuth_Verify
+        OAuth_OIDC --> OAuth_Verify
+        OAuth_Verify --> OAuth_Client
+    end
+
+    subgraph CA_Auth["Context Agent Authentication"]
+        direction TB
+        Client2[MCP Client]
+        CA_Header[Authorization Header]
+        CA_OCS[OCS API Validation]
+        CA_User[User Context]
+        CA_NC[nc-py-api Client]
+
+        Client2 --> CA_Header
+        CA_Header --> CA_OCS
+        CA_OCS -->|Extract user_id| CA_User
+        CA_User -->|nc.set_user| CA_NC
+    end
+
+    classDef auth fill:#fff4e1
+    classDef user fill:#e1f5ff
+
+    class BasicAuth,OAuth auth
+    class CA_User user
+```
+
+## Tool Registration & Loading
+
+```mermaid
+sequenceDiagram
+    participant Startup
+    participant NMCP as Nextcloud MCP<br/>Server
+    participant CA as Context Agent
+    participant Request as Client Request
+
+    Note over Startup,NMCP: Nextcloud MCP Server (Static)
+    Startup->>NMCP: Server starts
+    NMCP->>NMCP: configure_notes_tools(mcp)
+    NMCP->>NMCP: configure_calendar_tools(mcp)
+    NMCP->>NMCP: configure_contacts_tools(mcp)
+    Note over NMCP: Tools registered once<br/>at startup
+    Request->>NMCP: Call tool
+    NMCP->>NMCP: Use pre-registered tool
+
+    Note over Startup,CA: Context Agent (Dynamic)
+    Startup->>CA: Server starts
+    CA->>CA: Install ToolListMiddleware
+    Request->>CA: List tools (or 60s elapsed)
+    CA->>CA: get_tools(nc)
+    CA->>CA: Import all_tools/*.py
+    CA->>CA: Call module.get_tools(nc)
+    CA->>CA: Regenerate tool functions
+    Note over CA: Tools refreshed every 60s<br/>or on demand
+    Request->>CA: Call tool
+    CA->>CA: Regenerate with fresh nc
+```
+
+## Tool Definition Patterns
+
+### Nextcloud MCP Server
+
+```python
+# Static registration at startup
+def configure_notes_tools(mcp: FastMCP):
+    @mcp.tool()
+    async def nc_notes_create_note(
+        title: str,
+        content: str,
+        category: str,
+        ctx: Context
+    ) -> CreateNoteResponse:
+        """Create a new note"""
+        client = get_client(ctx)  # Auto-detects auth mode
+        note_data = await client.notes.create_note(
+            title=title,
+            content=content,
+            category=category
+        )
+        return CreateNoteResponse(
+            id=note_data["id"],
+            title=note_data["title"],
+            etag=note_data["etag"]
+        )
+
+    # Resources for structured data access
+    @mcp.resource("nc://Notes/{note_id}")
+    async def nc_get_note_resource(note_id: int):
+        """Get user note using note id"""
+        ctx = mcp.get_context()
+        client = get_client(ctx)
+        note_data = await client.notes.get_note(note_id)
+        return Note(**note_data)
+```
+
+**Key Features**:
+- Native FastMCP `@mcp.tool()` decorator
+- Pydantic models for type safety
+- MCP Resources support
+- Comprehensive error handling with McpError
+- Context-based client resolution
+
+### Context Agent
+
+```python
+# Dynamic loading at runtime
+async def get_tools(nc: Nextcloud):
+    @tool
+    @safe_tool
+    def list_calendars():
+        """List all existing calendars by name"""
+        principal = nc.cal.principal()
+        calendars = principal.calendars()
+        return ", ".join([cal.name for cal in calendars])
+
+    @tool
+    @dangerous_tool
+    def schedule_event(
+        calendar_name: str,
+        title: str,
+        description: str,
+        start_date: str,
+        end_date: str,
+        attendees: list[str] | None,
+        start_time: str | None,
+        end_time: str | None
+    ):
+        """Create a new event or meeting in a calendar"""
+        # Parse dates and times
+        start_datetime = datetime.strptime(start_date, "%Y-%m-%d")
+        # ... event creation logic
+        principal = nc.cal.principal()
+        calendar = {cal.name: cal for cal in calendars}[calendar_name]
+        calendar.add_event(str(c))
+        return True
+
+    return [list_calendars, schedule_event, ...]
+
+def get_category_name():
+    return "Calendar and Tasks"
+
+def is_available(nc: Nextcloud):
+    return True  # or check capabilities
+```
+
+**Key Features**:
+- LangChain `@tool` decorator
+- `@safe_tool` / `@dangerous_tool` decorators
+- Dynamic tool regeneration with fresh context
+- Tools returned as list from async function
+- Availability checking per module
+
+## Client Architecture
+
+```mermaid
+graph TB
+    subgraph NMCP_Client["Nextcloud MCP Server Clients"]
+        direction TB
+        NMCP_Main[NextcloudClient]
+        NMCP_Base[BaseNextcloudClient]
+
+        NMCP_Notes[NotesClient]
+        NMCP_Cal[CalendarClient]
+        NMCP_Contacts[ContactsClient]
+        NMCP_Tables[TablesClient]
+        NMCP_WebDAV[WebDAVClient]
+        NMCP_Deck[DeckClient]
+
+        NMCP_Main --> NMCP_Notes
+        NMCP_Main --> NMCP_Cal
+        NMCP_Main --> NMCP_Contacts
+        NMCP_Main --> NMCP_Tables
+        NMCP_Main --> NMCP_WebDAV
+        NMCP_Main --> NMCP_Deck
+
+        NMCP_Notes -.->|extends| NMCP_Base
+        NMCP_Cal -.->|extends| NMCP_Base
+        NMCP_Contacts -.->|extends| NMCP_Base
+
+        NMCP_Base --> HTTPX["httpx.AsyncClient"]
+        NMCP_Base --> Retry["@retry_on_429"]
+    end
+
+    subgraph CA_Client["Context Agent Client"]
+        direction TB
+        CA_NC["nc-py-api<br/>NextcloudApp"]
+
+        CA_NC --> CA_Cal["nc.cal<br/>CalDAV"]
+        CA_NC --> CA_Talk["nc.talk<br/>Talk API"]
+        CA_NC --> CA_OCS["nc.ocs<br/>OCS API"]
+        CA_NC --> CA_Session["nc._session<br/>HTTP Adapter"]
+    end
+
+    HTTPX -->|"HTTP/HTTPS"| NextcloudAPI["Nextcloud APIs"]
+    CA_Session -->|"HTTP/HTTPS"| NextcloudAPI
+
+    classDef custom fill:#fff4e1
+    classDef native fill:#e8f5e9
+
+    class NMCP_Main,NMCP_Base,NMCP_Notes,NMCP_Cal custom
+    class CA_NC,CA_Cal,CA_Talk,CA_OCS native
+```
+
+## Functionality Comparison
+
+### Available Tools & Features
+
+| Feature Category | Nextcloud MCP Server | Context Agent MCP |
+|-----------------|---------------------|-------------------|
+| **Notes** | ✅ Full CRUD, search, attachments (7 tools) | ❌ Not implemented |
+| **Calendar** | ✅ Full CalDAV (events, recurring, attendees) | ✅ Schedule events, list calendars, free/busy, tasks (4 tools) |
+| **Contacts** | ✅ Full CardDAV (address books, contacts) | ✅ Find person, current user details (2 tools) |
+| **Files** | ✅ Full WebDAV (read, write, directories) | ✅ Get content, folder tree, sharing (3 tools) |
+| **Tables** | ✅ Row CRUD operations | ❌ Not implemented |
+| **Deck** | ✅ Boards, stacks, cards | ✅ Create board, add card (2 tools) |
+| **Talk** | ❌ Not implemented | ✅ List/send messages, create conversation (4 tools) |
+| **Mail** | ❌ Not implemented | ✅ Send email, list mailboxes (2 tools) |
+| **AI Features** | ❌ Not implemented | ✅ Image gen, audio2text, doc-gen, context_chat (4 tools) |
+| **Web Search** | ❌ Not implemented | ✅ DuckDuckGo, YouTube search (2 tools) |
+| **Location** | ❌ Not implemented | ✅ OpenStreetMap, HERE transit, weather (3 tools) |
+| **OpenProject** | ❌ Not implemented | ✅ Integration (2 tools) |
+| **MCP Resources** | ✅ notes://, nc:// URIs | ❌ Not supported |
+| **External MCP** | ❌ Pure server only | ✅ Consumes external MCP servers |
+| **Sharing** | ✅ Share management API | ❌ Not implemented |
+| **Capabilities** | ✅ Server info resource | ❌ Not exposed |
+
+### Tool Count Summary
+
+- **Nextcloud MCP Server**: ~50+ tools and resources
+  - Deep integration with specific apps
+  - Full CRUD operations
+  - MCP Resources for structured data
+
+- **Context Agent**: ~28+ tools
+  - Broader feature coverage
+  - Action-oriented (agent tasks)
+  - Can aggregate external MCP servers
+
+## Tool Safety & Confirmation
+
+### Context Agent Safety Model
+
+```mermaid
+graph TD
+    Request[User Request] --> Agent[LangGraph Agent]
+    Agent --> Model[LLM generates tool calls]
+    Model --> Check{Tool type?}
+
+    Check -->|"@safe_tool"| Execute[Execute immediately]
+    Check -->|"@dangerous_tool"| Queue[Queue for confirmation]
+
+    Queue --> UserNode[Request user confirmation]
+    UserNode -->|Approved| Execute
+    UserNode -->|Denied| Cancel[Cancel with reason]
+
+    Execute --> Result[Return result to agent]
+    Cancel --> Result
+
+    Result --> Agent
+
+    classDef safe fill:#e8f5e9
+    classDef danger fill:#ffe8e8
+
+    class Execute safe
+    class Queue,UserNode,Cancel danger
+```
+
+**Safe Tools** (read-only):
+- `list_calendars`
+- `find_person_in_contacts`
+- `list_talk_conversations`
+- `get_file_content`
+- `get_folder_tree`
+
+**Dangerous Tools** (write operations):
+- `schedule_event`
+- `send_message_to_conversation`
+- `create_public_sharing_link`
+- `send_email`
+
+### Nextcloud MCP Server Safety
+
+**No built-in safety classification**:
+- All tools treated equally
+- Relies on MCP client for validation
+- OAuth scopes could control permissions
+- User must review all actions
+
+## Error Handling
+
+### Nextcloud MCP Server
+
+```python
+try:
+    note_data = await client.notes.create_note(...)
+    return CreateNoteResponse(...)
+except HTTPStatusError as e:
+    if e.response.status_code == 403:
+        raise McpError(ErrorData(
+            code=-1,
+            message="Access denied: insufficient permissions"
+        ))
+    elif e.response.status_code == 413:
+        raise McpError(ErrorData(
+            code=-1,
+            message="Note content too large"
+        ))
+    elif e.response.status_code == 409:
+        raise McpError(ErrorData(
+            code=-1,
+            message="Note with this title already exists"
+        ))
+```
+
+**Features**:
+- Comprehensive HTTP status code handling
+- User-friendly error messages
+- Specific error codes
+- Guidance on resolution
+
+### Context Agent
+
+```python
+def schedule_event(...):
+    """Create event"""
+    # ... implementation
+    calendar.add_event(str(c))
+    return True  # Simple boolean return
+```
+
+**Features**:
+- Minimal error handling
+- Exceptions propagate to agent
+- LangChain handles retries
+- Agent interprets failures
+
+## Use Cases
+
+### When to Use Nextcloud MCP Server
+
+```mermaid
+graph LR
+    Root[Nextcloud MCP Server]
+
+    Root --> ExtAccess[External Access]
+    Root --> OAuth[OAuth Security]
+    Root --> DeepAPI[Deep API Access]
+    Root --> Deploy[Standalone Deployment]
+
+    ExtAccess --> EA1[Claude Code integration]
+    ExtAccess --> EA2[IDE plugins with MCP]
+    ExtAccess --> EA3[Custom MCP clients]
+    ExtAccess --> EA4[Cross-platform tools]
+
+    OAuth --> O1[Token-based auth]
+    OAuth --> O2[OIDC compliance]
+    OAuth --> O3[Per-user permissions]
+    OAuth --> O4[Secure external access]
+
+    DeepAPI --> DA1[Full CRUD operations]
+    DeepAPI --> DA2[Notes management]
+    DeepAPI --> DA3[Calendar CalDAV]
+    DeepAPI --> DA4[Contacts CardDAV]
+    DeepAPI --> DA5[File operations]
+    DeepAPI --> DA6[Table data]
+
+    Deploy --> D1[Docker containers]
+    Deploy --> D2[Cloud VMs]
+    Deploy --> D3[Kubernetes]
+    Deploy --> D4[On-premise servers]
+
+    classDef rootStyle fill:#4a90e2,stroke:#2e5c8a,color:#fff
+    classDef categoryStyle fill:#f39c12,stroke:#d68910,color:#fff
+    classDef itemStyle fill:#e8f5e9,stroke:#81c784
+
+    class Root rootStyle
+    class ExtAccess,OAuth,DeepAPI,Deploy categoryStyle
+    class EA1,EA2,EA3,EA4,O1,O2,O3,O4,DA1,DA2,DA3,DA4,DA5,DA6,D1,D2,D3,D4 itemStyle
+```
+
+**Best for**:
+1. External clients accessing Nextcloud (Claude Code, IDEs)
+2. OAuth/OIDC authentication requirements
+3. Full CRUD on Notes, Calendar, Contacts, Tables
+4. WebDAV file system access
+5. MCP Resources for structured data
+6. Flexible deployment scenarios
+7. Building external integrations
+
+### When to Use Context Agent MCP Server
+
+```mermaid
+graph LR
+    Root[Context Agent MCP]
+
+    Root --> Assistant[AI Assistant]
+    Root --> ActionOriented[Action-Oriented]
+    Root --> MCPAgg[MCP Aggregation]
+    Root --> Safety[Safety Features]
+
+    Assistant --> A1[Nextcloud UI integration]
+    Assistant --> A2[Task Processing API]
+    Assistant --> A3[User requests in Assistant]
+    Assistant --> A4[Human-in-the-loop]
+
+    ActionOriented --> AO1[Send emails]
+    ActionOriented --> AO2[Create calendar events]
+    ActionOriented --> AO3[Post Talk messages]
+    ActionOriented --> AO4[Generate images]
+    ActionOriented --> AO5[Search web]
+
+    MCPAgg --> M1[Consume external MCP servers]
+    MCPAgg --> M2[Weather services]
+    MCPAgg --> M3[Maps and transit]
+    MCPAgg --> M4[Custom integrations]
+    MCPAgg --> M5[Unified tool interface]
+
+    Safety --> S1[Read operations auto-execute]
+    Safety --> S2[Write operations require approval]
+    Safety --> S3[User confirmation flow]
+    Safety --> S4[Agent safety]
+
+    classDef rootStyle fill:#9b59b6,stroke:#6c3483,color:#fff
+    classDef categoryStyle fill:#e74c3c,stroke:#c0392b,color:#fff
+    classDef itemStyle fill:#fff4e1,stroke:#f39c12
+
+    class Root rootStyle
+    class Assistant,ActionOriented,MCPAgg,Safety categoryStyle
+    class A1,A2,A3,A4,AO1,AO2,AO3,AO4,AO5,M1,M2,M3,M4,M5,S1,S2,S3,S4 itemStyle
+```
+
+**Best for**:
+1. AI-driven actions inside Nextcloud UI
+2. Assistant app integration
+3. Safe/dangerous tool distinction
+4. Talk, Mail, Deck operations
+5. AI features (image gen, audio2text)
+6. Web search and maps
+7. Aggregating external MCP servers
+8. Agent acting on behalf of users
+
+## Complementary Architecture
+
+The two MCP servers can work together in complementary ways:
+
+```mermaid
+graph TB
+    User[User] -->|Requests AI assistance| Assistant[Nextcloud Assistant App]
+
+    Assistant --> ContextAgent[Context Agent]
+
+    subgraph ContextAgent["Context Agent (Inside Nextcloud)"]
+        direction TB
+        Agent[LangGraph Agent]
+        MCPServer[MCP Server /mcp]
+        ToolLoader[Tool Loader]
+
+        Agent --> ToolLoader
+        ToolLoader --> InternalTools[Internal Tools<br/>Talk, Mail, Calendar]
+    end
+
+    subgraph ExternalMCP["External MCP Ecosystem"]
+        NextcloudMCP[Nextcloud MCP Server<br/>This Project]
+        WeatherMCP[Weather MCP]
+        CustomMCP[Custom MCP Services]
+    end
+
+    ToolLoader -->|Consumes| NextcloudMCP
+    ToolLoader -->|Consumes| WeatherMCP
+    ToolLoader -->|Consumes| CustomMCP
+
+    subgraph ExternalClients["External Clients"]
+        Claude[Claude Code]
+        IDE[IDEs with MCP]
+    end
+
+    Claude -->|Direct access| NextcloudMCP
+    IDE -->|Direct access| NextcloudMCP
+
+    NextcloudMCP -->|OAuth/HTTP| NextcloudApps[Nextcloud Apps<br/>Notes, Calendar, Files]
+    InternalTools -->|nc-py-api| NextcloudApps
+
+    classDef internal fill:#e8f5e9
+    classDef external fill:#e1f5ff
+    classDef mcp fill:#fff4e1
+
+    class Assistant,Agent,MCPServer,ToolLoader,InternalTools,NextcloudApps internal
+    class Claude,IDE external
+    class NextcloudMCP,WeatherMCP,CustomMCP mcp
+```
+
+### Example Workflows
+
+**Workflow 1: External Client → Nextcloud MCP Server**
+```
+Claude Code → Nextcloud MCP Server → Nextcloud Notes API
+```
+- User asks Claude Code to search notes
+- Claude Code calls `nc_notes_search_notes` tool
+- Returns results directly to user
+
+**Workflow 2: Assistant → Context Agent → Internal Tools**
+```
+User → Assistant → Context Agent → Send Email Tool
+```
+- User asks Assistant to send an email
+- Context Agent identifies "send_email" as dangerous
+- Requests user confirmation
+- Sends email via nc-py-api
+
+**Workflow 3: Assistant → Context Agent → External MCP**
+```
+User → Assistant → Context Agent → Nextcloud MCP Server → Notes
+```
+- User asks Assistant about notes
+- Context Agent consumes Nextcloud MCP Server as external MCP
+- Gets notes data via MCP protocol
+- Returns to user via Assistant
+
+## Technical Comparison Matrix
+
+| Aspect | Nextcloud MCP Server | Context Agent MCP |
+|--------|---------------------|-------------------|
+| **Framework** | FastMCP (native) | FastMCP + LangChain |
+| **Tool Decorator** | `@mcp.tool()` | `@tool` from LangChain |
+| **Tool Loading** | Static (startup) | Dynamic (runtime) |
+| **Tool Refresh** | No (restart required) | Every 60 seconds |
+| **Resources** | Yes (`@mcp.resource()`) | No |
+| **Transports** | SSE, HTTP, Streamable-HTTP | Stateless HTTP only |
+| **MCP Mode** | Server only | Server + Client (hybrid) |
+| **Client Type** | httpx (custom HTTP) | nc-py-api (native) |
+| **Deployment** | Standalone external | Inside Nextcloud (ExApp) |
+| **Auth** | BasicAuth or OAuth/OIDC | Session-based (ExApp) |
+| **User Context** | Shared or per-token | Per-request `nc.set_user()` |
+| **Error Handling** | McpError with codes | Basic exceptions |
+| **Type Safety** | Pydantic models | Python types |
+| **Safety Model** | No built-in | Safe/Dangerous classification |
+| **Dependencies** | FastMCP, httpx, Pydantic | nc-py-api, LangChain, LangGraph |
+| **Integration** | HTTP APIs | AppAPI + Task Processing |
+| **External MCP** | No | Yes (consumes) |
+
+## Summary
+
+Both MCP servers serve important but different roles in the Nextcloud ecosystem:
+
+### Nextcloud MCP Server (This Project)
+- **Purpose**: Expose Nextcloud to external MCP clients
+- **Strength**: Deep CRUD operations, OAuth security, standalone deployment
+- **Audience**: External developers, Claude Code users, integration builders
+
+### Context Agent MCP Server
+- **Purpose**: Bring AI agent capabilities to Nextcloud users
+- **Strength**: Action-oriented, safe/dangerous tools, MCP aggregation
+- **Audience**: Nextcloud users via Assistant app, AI-driven workflows
+
+**Key Insight**: These are complementary, not competing. Context Agent could even consume Nextcloud MCP Server as one of its external MCP sources, creating a unified ecosystem where:
+- External clients access Nextcloud via Nextcloud MCP Server
+- Internal users leverage Context Agent for AI assistance
+- Context Agent aggregates both internal tools and external MCP servers (including Nextcloud MCP Server)

docs/oauth-architecture.md

@@ -217,11 +217,12 @@ NEXTCLOUD_HOST=https://nextcloud.example.com
 
 **How it works**:
 1. Server checks `/.well-known/openid-configuration` for `registration_endpoint`
-2. Calls `/apps/oidc/register` to register new client
+2. Calls `/apps/oidc/register` to register a client on first startup
 3. Saves credentials to `.nextcloud_oauth_client.json`
-4. Re-registers if credentials expire
+4. Reuses these credentials on subsequent startups
+5. Re-registers only if credentials are missing or expired
 
-**Best for**: Development, testing, short-lived deployments
+**Best for**: Development, testing, quick deployments
 
 ### Pre-configured Client
 

docs/oauth-setup.md

@@ -165,23 +165,23 @@ You have two options for managing OAuth clients:
 
 ### Mode A: Automatic Registration (Dynamic Client Registration)
 
-**Best for**: Development, testing, short-lived deployments
+**Best for**: Development, testing, quick deployments
 
 **How it works**:
-- MCP server automatically registers OAuth client at startup
+- MCP server automatically registers an OAuth client on first startup
 - Uses Nextcloud's dynamic client registration endpoint
 - Saves credentials to `.nextcloud_oauth_client.json`
+- Reuses stored credentials on subsequent restarts
 - Re-registers automatically if credentials expire
 
 **Pros**:
 - Zero configuration required
 - Quick setup
-- No manual client management
+- Automatic credential management
 
 **Cons**:
 - Clients expire (default: 1 hour, configurable)
-- Must re-register on restart if expired
-- Not ideal for long-running production
+- Must have dynamic client registration enabled on Nextcloud
 
 **Configuration**: Skip to [Step 4](#step-4-configure-mcp-server) with minimal config.
 
@@ -192,8 +192,8 @@ You have two options for managing OAuth clients:
 **Best for**: Production, long-running deployments, stable environments
 
 **How it works**:
-- You manually register OAuth client via Nextcloud CLI
-- Provide client credentials to MCP server
+- You manually register an OAuth client via Nextcloud CLI
+- Provide client credentials to MCP server via environment variables
 - Credentials don't expire
 
 **Pros**:

docs/quickstart-oauth.md

@@ -151,11 +151,11 @@ curl https://your.nextcloud.instance.com/.well-known/openid-configuration
 This quick start uses **automatic client registration** which is perfect for:
 - Development
 - Testing
-- Short-lived deployments
+- Quick deployments
 
-For **production deployments**, you should:
-1. Pre-register OAuth clients manually
-2. Use dedicated client credentials
+For **production deployments**, consider:
+1. Pre-registering OAuth client manually
+2. Using dedicated client credentials that don't expire
 3. See [OAuth Setup Guide](oauth-setup.md) for production configuration
 
 ---

nextcloud_mcp_server/auth/client_registration.py

@@ -211,7 +211,6 @@ async def load_or_register_client(
     storage_path: str | Path,
     client_name: str = "Nextcloud MCP Server",
     redirect_uris: list[str] | None = None,
-    force_register: bool = True,
 ) -> ClientInfo:
     """
     Load client from storage or register a new one if not found/expired.
@@ -219,7 +218,7 @@ async def load_or_register_client(
     This function:
     1. Checks for existing client credentials in storage
     2. Validates the credentials are not expired
-    3. Registers a new client if needed
+    3. Registers a new client if needed (no stored credentials or expired)
     4. Saves the new client credentials
 
     Args:
@@ -228,7 +227,6 @@ async def load_or_register_client(
         storage_path: Path to store client credentials
         client_name: Name of the client application
         redirect_uris: List of redirect URIs
-        force_register: Force registration even if valid credentials exist
 
     Returns:
         ClientInfo with valid credentials
@@ -239,11 +237,10 @@ async def load_or_register_client(
     """
     storage_path = Path(storage_path)
 
-    # Try to load existing client unless forced to register
-    if not force_register:
-        client_info = load_client_from_file(storage_path)
-        if client_info:
-            return client_info
+    # Try to load existing client
+    client_info = load_client_from_file(storage_path)
+    if client_info:
+        return client_info
 
     # Register new client
     logger.info("Registering new OAuth client...")

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.13.0"
+version = "0.14.1"
 description = ""
 authors = [
     {name = "Chris Coutinho",email = "chris@coutinho.io"}
@@ -22,8 +22,8 @@ asyncio_mode = "auto"
 asyncio_default_test_loop_scope = "session"
 asyncio_default_fixture_loop_scope = "session"
 log_cli = 1
-log_cli_level = "INFO"
-log_level = "INFO"
+log_cli_level = "WARN"
+log_level = "WARN"
 markers = [
     "integration: marks tests as slow (deselect with '-m \"not slow\"')",
     "oauth: marks tests as oauth (deselect with '-m \"not oauth\"')"

tests/conftest.py

@@ -651,8 +651,10 @@ def oauth_callback_server():
     """
     Fixture to create an HTTP server for OAuth callback handling.
 
-    Yields a tuple of (auth_state, server_url) where:
-    - auth_state: A dict with {"code": None} that will be populated with the auth code
+    Supports multiple concurrent OAuth flows using state parameters for correlation.
+
+    Yields a tuple of (auth_states, server_url) where:
+    - auth_states: A dict mapping state parameter to auth code
     - server_url: The callback URL for the server (e.g., "http://localhost:8081")
 
     The server automatically shuts down when the fixture is torn down.
@@ -663,8 +665,9 @@ def oauth_callback_server():
     from http.server import BaseHTTPRequestHandler, HTTPServer
     from urllib.parse import parse_qs, urlparse
 
-    # Use a mutable container to share state across threads
-    auth_state = {"code": None}
+    # Use a dict to store auth codes keyed by state parameter
+    # This allows multiple concurrent OAuth flows
+    auth_states = {}
     httpd = None
     server_thread = None
 
@@ -674,26 +677,27 @@ def oauth_callback_server():
             pass
 
         def do_GET(self):
-            # Ignore subsequent requests if we already have a code
-            # (this is a session-scoped fixture, so only process the first auth code)
-            if auth_state["code"] is not None:
-                self.send_response(200)
-                self.send_header("Content-type", "text/html")
-                self.end_headers()
-                self.wfile.write(
-                    b"<html><body><h1>Authentication already completed</h1></body></html>"
-                )
-                return
-
             # Parse the callback request
             parsed_path = urlparse(self.path)
             query = parse_qs(parsed_path.query)
             code = query.get("code", [None])[0]
+            state = query.get("state", [None])[0]
 
             # Only process if we have a valid code
             if code:
-                auth_state["code"] = code
-                logger.info(f"OAuth callback received. Code: {code[:20]}...")
+                # Store code keyed by state parameter for correlation
+                if state:
+                    auth_states[state] = code
+                    logger.info(
+                        f"OAuth callback received for state={state[:16]}... Code: {code[:20]}..."
+                    )
+                else:
+                    # Fallback for flows without state parameter (legacy interactive flow)
+                    auth_states["_default"] = code
+                    logger.info(
+                        f"OAuth callback received (no state). Code: {code[:20]}..."
+                    )
+
                 self.send_response(200)
                 self.send_header("Content-type", "text/html")
                 self.end_headers()
@@ -714,8 +718,8 @@ def oauth_callback_server():
         server_thread.start()
         logger.info("OAuth callback server started on http://localhost:8081")
 
-        # Yield the auth state and server URL
-        yield auth_state, "http://localhost:8081"
+        # Yield the auth states dict and server URL
+        yield auth_states, "http://localhost:8081"
 
     finally:
         # Clean up the server
@@ -746,8 +750,8 @@ async def interactive_oauth_token(oauth_callback_server) -> str:
 
     from nextcloud_mcp_server.auth.client_registration import load_or_register_client
 
-    # Unpack the server fixture
-    auth_state, callback_url = oauth_callback_server
+    # Unpack the server fixture (now returns dict of auth_states)
+    auth_states, callback_url = oauth_callback_server
 
     nextcloud_host = os.getenv("NEXTCLOUD_HOST")
     async with httpx.AsyncClient() as http_client:
@@ -762,7 +766,6 @@ async def interactive_oauth_token(oauth_callback_server) -> str:
             registration_endpoint=registration_endpoint,
             storage_path=".nextcloud_oauth_shared_test_client.json",
             redirect_uris=[callback_url],
-            force_register=False,  # Reuse existing credentials if valid
         )
 
         # First, open Nextcloud login page to establish session
@@ -772,22 +775,22 @@ async def interactive_oauth_token(oauth_callback_server) -> str:
             "After logging in, the OAuth authorization will proceed automatically"
         )
 
-        # Construct authorization URL
+        # Construct authorization URL (no state parameter for interactive flow)
         auth_url = f"{authorization_endpoint}?response_type=code&client_id={client_info.client_id}&redirect_uri={callback_url}&scope=openid%20profile%20email"
 
         # Open authorization URL in browser
         webbrowser.open(auth_url)
 
-        # Wait for auth code with timeout
+        # Wait for auth code with timeout (uses "_default" key for flows without state)
         timeout = 120  # 2 minutes
         start_time = time.time()
-        while not auth_state["code"]:
+        while "_default" not in auth_states:
             if time.time() - start_time > timeout:
                 raise TimeoutError("OAuth authorization timed out after 2 minutes")
             logger.info("Waiting for OAuth authorization...")
             time.sleep(1)
 
-        auth_code = auth_state["code"]
+        auth_code = auth_states["_default"]
         logger.info("Received authorization code, exchanging for token...")
 
         token_response = await http_client.post(
@@ -810,13 +813,15 @@ async def interactive_oauth_token(oauth_callback_server) -> str:
 
 
 @pytest.fixture(scope="session")
-async def shared_oauth_client_credentials():
+async def shared_oauth_client_credentials(oauth_callback_server):
     """
     Fixture to obtain shared OAuth client credentials that will be reused for all users.
 
     This registers a single OAuth client with Nextcloud that matches the MCP server's
     registration, allowing all test users to authenticate using the same client_id/secret.
 
+    Now uses the real OAuth callback server for reliable token acquisition.
+
     Returns:
         Tuple of (client_id, client_secret, callback_url, token_endpoint, authorization_endpoint)
     """
@@ -826,7 +831,11 @@ async def shared_oauth_client_credentials():
     if not nextcloud_host:
         pytest.skip("Shared OAuth client requires NEXTCLOUD_HOST")
 
+    # Get callback URL from the real callback server
+    auth_states, callback_url = oauth_callback_server
+
     logger.info("Setting up shared OAuth client credentials for all test users...")
+    logger.info(f"Using real callback server at: {callback_url}")
 
     async with httpx.AsyncClient(timeout=30.0) as http_client:
         # OIDC Discovery
@@ -842,9 +851,6 @@ async def shared_oauth_client_credentials():
         if not all([token_endpoint, registration_endpoint, authorization_endpoint]):
             raise ValueError("OIDC discovery missing required endpoints")
 
-        # Use callback URL that won't actually be used (we extract code from browser URL)
-        callback_url = "http://localhost:9999/oauth/callback"
-
         # Register or load shared OAuth client (matches MCP server registration)
         client_info = await load_or_register_client(
             nextcloud_url=nextcloud_host,
@@ -852,7 +858,6 @@ async def shared_oauth_client_credentials():
             storage_path=".nextcloud_oauth_shared_test_client.json",
             client_name="Nextcloud MCP Server - Shared Test Client",
             redirect_uris=[callback_url],
-            force_register=False,  # Reuse existing credentials if valid
         )
 
         logger.info(f"Shared OAuth client ready: {client_info.client_id[:16]}...")
@@ -868,7 +873,9 @@ async def shared_oauth_client_credentials():
 
 
 @pytest.fixture(scope="session")
-async def playwright_oauth_token(browser, shared_oauth_client_credentials) -> str:
+async def playwright_oauth_token(
+    browser, shared_oauth_client_credentials, oauth_callback_server
+) -> str:
     """
     Fixture to obtain an OAuth access token using Playwright headless browser automation.
 
@@ -877,7 +884,7 @@ async def playwright_oauth_token(browser, shared_oauth_client_credentials) -> st
     2. Navigating to authorization URL in headless browser
     3. Programmatically filling in login form
     4. Handling OAuth consent
-    5. Extracting auth code from redirect
+    5. Waiting for callback server to receive auth code (NEW: using real callback server!)
     6. Exchanging code for access token
 
     Environment variables required:
@@ -890,7 +897,9 @@ async def playwright_oauth_token(browser, shared_oauth_client_credentials) -> st
     - Browser fixture provided by pytest-playwright-asyncio
     - See: https://playwright.dev/python/docs/test-runners
     """
-    from urllib.parse import parse_qs, urlparse
+    import secrets
+    import time
+    from urllib.parse import quote
 
     nextcloud_host = os.getenv("NEXTCLOUD_HOST")
     username = os.getenv("NEXTCLOUD_USERNAME")
@@ -901,6 +910,9 @@ async def playwright_oauth_token(browser, shared_oauth_client_credentials) -> st
             "Playwright OAuth requires NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, and NEXTCLOUD_PASSWORD"
         )
 
+    # Get auth_states dict from callback server
+    auth_states, _ = oauth_callback_server
+
     # Unpack shared client credentials
     client_id, client_secret, callback_url, token_endpoint, authorization_endpoint = (
         shared_oauth_client_credentials
@@ -908,13 +920,19 @@ async def playwright_oauth_token(browser, shared_oauth_client_credentials) -> st
 
     logger.info(f"Starting Playwright-based OAuth flow for {username}...")
     logger.info(f"Using shared OAuth client: {client_id[:16]}...")
+    logger.info(f"Using real callback server at: {callback_url}")
 
-    # Construct authorization URL
+    # Generate unique state parameter for this OAuth flow
+    state = secrets.token_urlsafe(32)
+    logger.debug(f"Generated state: {state[:16]}...")
+
+    # Construct authorization URL with state parameter
     auth_url = (
         f"{authorization_endpoint}?"
         f"response_type=code&"
         f"client_id={client_id}&"
-        f"redirect_uri={callback_url}&"
+        f"redirect_uri={quote(callback_url, safe='')}&"
+        f"state={state}&"
         f"scope=openid%20profile%20email"
     )
 
@@ -971,33 +989,24 @@ async def playwright_oauth_token(browser, shared_oauth_client_credentials) -> st
         except Exception as e:
             logger.debug(f"No authorization button found or already authorized: {e}")
 
-        # Wait for redirect to callback URL (which will fail to load, but we just need the URL)
-        try:
-            # The redirect might fail since localhost:9999 isn't actually running
-            # But we can still extract the code from the URL
-            await page.wait_for_url(f"{callback_url}*", timeout=10000)
-        except Exception as e:
-            # Expected - the callback URL won't load, but we should have the URL
-            logger.debug(f"Callback redirect (expected to fail): {e}")
+        # Wait for callback server to receive the auth code
+        # Browser will be redirected to localhost:8081 which will capture the code
+        logger.info("Waiting for callback server to receive auth code...")
+        timeout_seconds = 30
+        start_time = time.time()
+        while state not in auth_states:
+            if time.time() - start_time > timeout_seconds:
+                # Take a screenshot for debugging
+                screenshot_path = "/tmp/playwright_oauth_error.png"
+                await page.screenshot(path=screenshot_path)
+                logger.error(f"Screenshot saved to {screenshot_path}")
+                raise TimeoutError(
+                    f"Timeout waiting for OAuth callback (state={state[:16]}...)"
+                )
+            await asyncio.sleep(0.5)
 
-        # Extract auth code from URL
-        final_url = page.url
-        logger.debug(f"Final URL: {final_url}")
-
-        parsed_url = urlparse(final_url)
-        query_params = parse_qs(parsed_url.query)
-        auth_code = query_params.get("code", [None])[0]
-
-        if not auth_code:
-            # Take a screenshot for debugging
-            screenshot_path = "/tmp/playwright_oauth_error.png"
-            await page.screenshot(path=screenshot_path)
-            logger.error(f"Screenshot saved to {screenshot_path}")
-            raise ValueError(
-                f"No authorization code found in redirect URL: {final_url}"
-            )
-
-        logger.info(f"Successfully extracted authorization code: {auth_code[:20]}...")
+        auth_code = auth_states[state]
+        logger.info(f"Successfully received authorization code: {auth_code[:20]}...")
 
     finally:
         await context.close()
@@ -1236,23 +1245,31 @@ async def test_users_setup(nc_client: NextcloudClient):
 
 
 async def _get_oauth_token_for_user(
-    browser, shared_oauth_client_credentials, username: str, password: str
+    browser,
+    shared_oauth_client_credentials,
+    auth_states,
+    username: str,
+    password: str,
 ) -> str:
     """
     Helper function to get OAuth access token for a user via Playwright.
 
     Uses shared OAuth client credentials to authenticate multiple users with the same client.
+    Now uses real callback server with state parameters for reliable token acquisition.
 
     Args:
         browser: Playwright browser instance
         shared_oauth_client_credentials: Tuple of (client_id, client_secret, callback_url, token_endpoint, authorization_endpoint)
+        auth_states: Dict mapping state parameters to auth codes (from callback server)
         username: Username to authenticate as
         password: Password for the user
 
     Returns:
         OAuth access token string
     """
-    from urllib.parse import parse_qs, urlparse
+    import secrets
+    import time
+    from urllib.parse import quote
 
     nextcloud_host = os.getenv("NEXTCLOUD_HOST")
 
@@ -1267,14 +1284,17 @@ async def _get_oauth_token_for_user(
     logger.info(f"Getting OAuth token for user: {username}...")
     logger.info(f"Using shared OAuth client: {client_id[:16]}...")
 
-    # Construct authorization URL with properly encoded redirect_uri
-    from urllib.parse import quote
+    # Generate unique state parameter for this OAuth flow
+    state = secrets.token_urlsafe(32)
+    logger.debug(f"Generated state for {username}: {state[:16]}...")
 
+    # Construct authorization URL with state parameter
     auth_url = (
         f"{authorization_endpoint}?"
         f"response_type=code&"
         f"client_id={client_id}&"
         f"redirect_uri={quote(callback_url, safe='')}&"
+        f"state={state}&"
         f"scope=openid%20profile%20email"
     )
 
@@ -1311,22 +1331,25 @@ async def _get_oauth_token_for_user(
         except Exception as e:
             logger.debug(f"No authorization needed for {username}: {e}")
 
-        # Wait for redirect and extract auth code
-        try:
-            await page.wait_for_url(f"{callback_url}*", timeout=30000)
-        except Exception:
-            pass  # Expected - callback won't load
-
-        final_url = page.url
-        parsed_url = urlparse(final_url)
-        query_params = parse_qs(parsed_url.query)
-        auth_code = query_params.get("code", [None])[0]
-
-        if not auth_code:
-            raise ValueError(
-                f"No authorization code found for {username} in URL: {final_url}"
-            )
+        # Wait for callback server to receive the auth code
+        # Browser will be redirected to localhost:8081 which will capture the code
+        logger.info(
+            f"Waiting for callback server to receive auth code for {username}..."
+        )
+        timeout_seconds = 30
+        start_time = time.time()
+        while state not in auth_states:
+            if time.time() - start_time > timeout_seconds:
+                # Take screenshot for debugging
+                screenshot_path = f"/tmp/playwright_oauth_timeout_{username}.png"
+                await page.screenshot(path=screenshot_path)
+                logger.error(f"Screenshot saved to {screenshot_path}")
+                raise TimeoutError(
+                    f"Timeout waiting for OAuth callback for {username} (state={state[:16]}...)"
+                )
+            await asyncio.sleep(0.5)
 
+        auth_code = auth_states[state]
         logger.info(f"Got auth code for {username}: {auth_code[:20]}...")
 
     finally:
@@ -1360,7 +1383,7 @@ async def _get_oauth_token_for_user(
 # Parallel token retrieval fixture - fetches all OAuth tokens concurrently
 @pytest.fixture(scope="session")
 async def all_oauth_tokens(
-    browser, shared_oauth_client_credentials, test_users_setup
+    browser, shared_oauth_client_credentials, test_users_setup, oauth_callback_server
 ) -> dict[str, str]:
     """
     Fetch OAuth tokens for all test users in parallel for speed.
@@ -1368,26 +1391,34 @@ async def all_oauth_tokens(
     Returns a dict mapping username to OAuth access token.
     This is significantly faster than fetching tokens sequentially.
 
-    Note: We add a small stagger between starting each flow to avoid
-    race conditions in Nextcloud's OAuth session handling.
+    Now uses the real callback server with state parameters for reliable
+    concurrent token acquisition without race conditions.
     """
     import asyncio
     import time
 
+    # Get auth_states dict from callback server
+    auth_states, callback_url = oauth_callback_server
+
     start_time = time.time()
     logger.info("Fetching OAuth tokens for all users in parallel...")
+    logger.info(f"Using callback server at {callback_url} with state-based correlation")
 
     async def get_token_with_delay(username: str, config: dict, delay: float):
         """Get token for a user after a small delay to stagger requests."""
         if delay > 0:
             await asyncio.sleep(delay)
         return await _get_oauth_token_for_user(
-            browser, shared_oauth_client_credentials, username, config["password"]
+            browser,
+            shared_oauth_client_credentials,
+            auth_states,
+            username,
+            config["password"],
         )
 
     # Create tasks for all users with staggered starts (2.0s apart)
     tasks = {
-        username: get_token_with_delay(username, config, (idx + 1) * 2.0)
+        username: get_token_with_delay(username, config, idx * 0.5)
         for idx, (username, config) in enumerate(test_users_setup.items())
     }
 

uv.lock

@@ -630,7 +630,7 @@ wheels = [
 
 [[package]]
 name = "nextcloud-mcp-server"
-version = "0.13.0"
+version = "0.14.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },