bump: version 0.21.0 → 0.22.0

Feature/helm chart

.github/workflows/helm-release.yml

@@ -0,0 +1,29 @@
+name: Release Charts
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  release:
+    # depending on default permission settings for your org (contents being read-only or read-write for workloads), you will have to add permissions
+    # see: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git
+        run: |
+          git config user.name "$GITHUB_ACTOR"
+          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
+
+      - name: Run chart-releaser
+        uses: helm/chart-releaser-action@v1.7.0
+        env:
+          CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
       - name: Install uv
-        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
       - name: Install Python 3.11
         run: uv python install 3.11
       - name: Build

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
       - name: Check format
         run: |
           uv run --frozen ruff format --diff
@@ -32,7 +32,7 @@ jobs:
       ###### Required to build OIDC App ######
 
       - name: Set up php 8.4
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # v2
         with:
           php-version: 8.4
           coverage: none
@@ -52,7 +52,7 @@ jobs:
           up-flags: "--build"
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
 
       - name: Install Playwright dependencies
         run: |

CHANGELOG.md

@@ -1,3 +1,64 @@
+## v0.22.0 (2025-10-29)
+
+### Feat
+
+- **server**: Add /live & /health endpoints
+- Initialize helm chart
+
+## v0.21.0 (2025-10-25)
+
+### Feat
+
+- Add text processing background worker for telling client about progress
+
+### Refactor
+
+- Transform document parsing into pluggable processor architecture
+
+## v0.20.0 (2025-10-24)
+
+### Feat
+
+- **auth**: Add support for client registration deletion
+- Split read/write scopes into app:read/write scopes
+
+### Fix
+
+- Add support for RFC 7592 client registration and deletion
+- Update webdav models for proper serialization
+
+## v0.19.1 (2025-10-24)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.19,<1.20
+
+## v0.19.0 (2025-10-23)
+
+### Feat
+
+- Enable token introspection for opaque tokens
+
+### Fix
+
+- Add CORS middleware to allow browser-based clients like MCP Inspector
+
+## v0.18.0 (2025-10-23)
+
+### Feat
+
+- **server**: Add support for custom OIDC scopes and permissions via JWTs
+- Initialize JWT-scoped tools
+
+### Fix
+
+- Use occ-created OAuth clients with allowed_scopes for all tests
+- Separate OAuth fixtures for opaque vs JWT tokens
+
+### Refactor
+
+- Update JWT client to use DCR, re-enable tool filtering
+
 ## v0.17.1 (2025-10-20)
 
 ### Fix

CLAUDE.md

@@ -5,20 +5,41 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Development Commands
 
 ### Testing
+
+The test suite is organized in layers for fast feedback:
+
 ```bash
-# Run all tests
+# FAST FEEDBACK (recommended for development)
+# Unit tests only - ~5 seconds
+uv run pytest tests/unit/ -v
+
+# Smoke tests - critical path validation - ~30-60 seconds
+uv run pytest -m smoke -v
+
+# INTEGRATION TESTS
+# Integration tests without OAuth - ~2-3 minutes
+uv run pytest -m "integration and not oauth" -v
+
+# Full test suite - ~4-5 minutes
 uv run pytest
 
-# Run integration tests only
-uv run pytest -m integration
+# OAuth tests only (slowest, requires Playwright) - ~3 minutes
+uv run pytest -m oauth -v
 
+# COVERAGE
 # Run tests with coverage
 uv run pytest --cov
 
+# LEGACY COMMANDS (still work)
+# Run all integration tests
+uv run pytest -m integration -v
+
 # Skip integration tests
-uv run pytest -m "not integration"
+uv run pytest -m "not integration" -v
 ```
 
+! Hint: If the tests are failing due to missing environment variables, then usually the correct .env has not been created or not correctly configured yet.
+
 ### Load Testing
 ```bash
 # Run benchmark with default settings (10 workers, 30 seconds)
@@ -89,16 +110,18 @@ docker-compose up
 # For basic auth changes (most common) - uses admin credentials
 docker-compose up --build -d mcp
 
-# For OAuth changes - uses OAuth authentication flow
+# For OAuth changes - uses OAuth authentication with JWT tokens
 docker-compose up --build -d mcp-oauth
 
 # Build Docker image
 docker build -t nextcloud-mcp-server .
 ```
 
-**Important: Two MCP Server Containers**
+**Important: MCP Server Containers**
 - **`mcp`** (port 8000): Uses basic auth with admin credentials. Use this for most development and testing.
-- **`mcp-oauth`** (port 8001): Uses OAuth authentication. Only use this when working on OAuth-specific features or tests.
+- **`mcp-oauth`** (port 8001): Uses OAuth authentication with JWT tokens. Use this when working on OAuth-specific features or tests.
+  - JWT tokens are used for testing (faster validation, scopes embedded in token)
+  - The server can handle both JWT and opaque tokens via the token verifier
 
 ### Environment Setup
 ```bash
@@ -109,6 +132,36 @@ uv sync
 uv sync --group dev
 ```
 
+### Database Inspection
+
+**Docker Compose Database Credentials:**
+- Root user: `root` / password: `password`
+- App user: `nextcloud` / password: `password`
+- Database: `nextcloud`
+
+**Common Database Commands:**
+```bash
+# Connect to database as root (most common for inspection)
+docker compose exec db mariadb -u root -ppassword nextcloud
+
+# Check OAuth clients
+docker compose exec db mariadb -u root -ppassword nextcloud -e "SELECT id, name, token_type FROM oc_oidc_clients ORDER BY id DESC LIMIT 10;"
+
+# Check OAuth client scopes
+docker compose exec db mariadb -u root -ppassword nextcloud -e "SELECT c.id, c.name, s.scope FROM oc_oidc_clients c LEFT JOIN oc_oidc_client_scopes s ON c.id = s.client_id WHERE c.name LIKE '%MCP%';"
+
+# Check OAuth access tokens
+docker compose exec db mariadb -u root -ppassword nextcloud -e "SELECT id, client_id, user_id, created_at FROM oc_oidc_access_tokens ORDER BY created_at DESC LIMIT 10;"
+```
+
+**Important Tables:**
+- `oc_oidc_clients` - OAuth client registrations (DCR clients)
+- `oc_oidc_client_scopes` - Client allowed scopes
+- `oc_oidc_access_tokens` - Issued access tokens
+- `oc_oidc_authorization_codes` - Authorization codes
+- `oc_oidc_registration_tokens` - RFC 7592 registration tokens for client management
+- `oc_oidc_redirect_uris` - Redirect URIs for each client
+
 ## Architecture Overview
 
 This is a Python MCP (Model Context Protocol) server that provides LLM integration with Nextcloud. The architecture follows a layered pattern:
@@ -179,9 +232,37 @@ FastMCP serialization issue: raw lists get mangled into dicts with numeric strin
 
 ### Testing Structure
 
-- **Integration tests** in `tests/client/` and `tests/server/` - Test real Nextcloud API interactions
-- **Fixtures** in `tests/conftest.py` - Shared test setup and utilities
-- Tests are marked with `@pytest.mark.integration` for selective running
+The test suite follows a layered architecture for fast feedback:
+
+```
+tests/
+├── unit/                    # Fast unit tests (~5s total)
+│   ├── test_scope_decorator.py
+│   └── test_response_models.py
+├── smoke/                   # Critical path tests (~30-60s)
+│   └── test_smoke.py
+├── integration/
+│   ├── client/             # Direct API layer tests
+│   │   ├── notes/
+│   │   ├── calendar/
+│   │   └── ...
+│   └── server/             # MCP tool layer tests
+│       ├── oauth/          # OAuth-specific tests (slow, ~3min)
+│       │   ├── test_oauth_core.py
+│       │   ├── test_scope_authorization.py
+│       │   └── ...
+│       ├── test_mcp.py
+│       └── ...
+└── load/                   # Performance tests
+```
+
+**Test Markers:**
+- `@pytest.mark.unit` - Fast unit tests with mocked dependencies
+- `@pytest.mark.integration` - Integration tests requiring Docker containers
+- `@pytest.mark.oauth` - OAuth tests requiring Playwright (slowest)
+- `@pytest.mark.smoke` - Critical path smoke tests
+
+**Fixtures** in `tests/conftest.py` - Shared test setup and utilities
 - **Important**: Integration tests run against live Docker containers. After making code changes:
   - For basic auth tests: rebuild with `docker-compose up --build -d mcp`
   - For OAuth tests: rebuild with `docker-compose up --build -d mcp-oauth`
@@ -206,16 +287,84 @@ FastMCP serialization issue: raw lists get mangled into dicts with numeric strin
   - For OAuth changes: `uv run pytest tests/server/test_oauth*.py -v` (remember to rebuild `mcp-oauth` container)
 - **Avoid creating standalone test scripts** - use pytest with proper fixtures instead
 
+#### Writing Mocked Unit Tests
+
+For client-layer tests that verify response parsing logic, use mocked HTTP responses instead of real network calls:
+
+**Pattern:**
+```python
+import httpx
+import pytest
+from nextcloud_mcp_server.client.notes import NotesClient
+from tests.conftest import create_mock_note_response
+
+async def test_notes_api_get_note(mocker):
+    """Test that get_note correctly parses the API response."""
+    # Create mock response using helper functions
+    mock_response = create_mock_note_response(
+        note_id=123,
+        title="Test Note",
+        content="Test content",
+        category="Test",
+        etag="abc123",
+    )
+
+    # Mock the _make_request method
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NotesClient, "_make_request", return_value=mock_response
+    )
+
+    # Create client and test
+    client = NotesClient(mock_client, "testuser")
+    note = await client.get_note(note_id=123)
+
+    # Verify the response was parsed correctly
+    assert note["id"] == 123
+    assert note["title"] == "Test Note"
+    # Verify the correct API endpoint was called
+    mock_make_request.assert_called_once_with("GET", "/apps/notes/api/v1/notes/123")
+```
+
+**Mock Response Helpers in `tests/conftest.py`:**
+- `create_mock_response()` - Generic HTTP response builder
+- `create_mock_note_response()` - Pre-configured note response
+- `create_mock_error_response()` - Error responses (404, 412, etc.)
+
+**Benefits:**
+- ⚡ Fast execution (~0.1s vs minutes for integration tests)
+- 🔒 No Docker dependency
+- 🎯 Tests focus on response parsing logic
+- ♻️ Repeatable and deterministic
+
+**When to use:**
+- Testing client methods that parse JSON responses
+- Testing error handling (404, 412, etc.)
+- Testing request parameter building
+
+**When NOT to use (keep as integration tests):**
+- Complex protocol interactions (CalDAV, CardDAV, WebDAV)
+- Multi-component workflows (Notes + WebDAV attachments)
+- OAuth flows
+- End-to-end MCP tool testing
+
+**Reference Implementation:**
+- See `tests/client/notes/test_notes_api.py` for complete examples
+- Mark unit tests with `pytestmark = pytest.mark.unit`
+- Run with: `uv run pytest tests/unit/ tests/client/notes/test_notes_api.py -v`
+
 #### OAuth/OIDC Testing
 OAuth integration tests use **automated Playwright browser automation** to complete the OAuth flow programmatically.
 
 **OAuth Testing Setup:**
 - **Main fixtures**: `nc_oauth_client`, `nc_mcp_oauth_client` - Use Playwright automation
 - **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
+  - **Created fresh for each test session** via Dynamic Client Registration (DCR)
+  - Matches production MCP server behavior (one client, multiple user tokens)
   - Each user gets their own unique access token
+  - **Automatic cleanup**: Client is registered at session start, deleted at session end (RFC 7592)
   - Implementation: `shared_oauth_client_credentials` fixture in `tests/conftest.py`
+  - **Note**: Client deletion may fail due to Nextcloud middleware (logged as warning). This doesn't affect tests.
 - **Available fixtures**: `playwright_oauth_token`, `nc_oauth_client`, `nc_mcp_oauth_client`
 - **Multi-user fixtures**: `alice_oauth_token`, `bob_oauth_token`, `charlie_oauth_token`, `diana_oauth_token`
 - **Requirements**: `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD` environment variables
@@ -226,13 +375,13 @@ OAuth integration tests use **automated Playwright browser automation** to compl
 **Example Commands:**
 ```bash
 # Run all OAuth tests with Playwright automation using Firefox
-uv run pytest tests/server/test_oauth*.py --browser firefox -v
+uv run pytest tests/server/oauth/ --browser firefox -v
 
-# Run specific tests with visible browser for debugging
-uv run pytest tests/server/test_mcp_oauth.py --browser firefox --headed -v
+# Run specific OAuth test file with visible browser for debugging
+uv run pytest tests/server/oauth/test_oauth_core.py --browser firefox --headed -v
 
-# Run with Chromium (default)
-uv run pytest tests/server/test_oauth*.py -v
+# Run with Chromium (default) - use -m oauth marker for all OAuth tests
+uv run pytest -m oauth -v
 ```
 
 **Test Environment:**
@@ -241,7 +390,6 @@ uv run pytest tests/server/test_oauth*.py -v
   - `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`
-- OAuth client credentials cached in `.nextcloud_oauth_shared_test_client.json`
 
 **CI/CD Notes:**
 - Playwright tests run in CI/CD environments

Dockerfile

@@ -1,4 +1,4 @@
-FROM ghcr.io/astral-sh/uv:0.9.4-python3.11-alpine@sha256:1a51c7710eaf839fa3365329ad993b48d17ddd9ab0f0672efaa9b09f407ebf44
+FROM ghcr.io/astral-sh/uv:0.9.5-python3.11-alpine@sha256:64ecec379ff82bea84b8a80c0b374f6392bcd54aa52f8c63c12f510f9c0b214d
 
 # Install git (required for caldav dependency from git)
 RUN apk add --no-cache git

README.md

@@ -23,6 +23,7 @@ The Nextcloud MCP (Model Context Protocol) server allows Large Language Models l
 | **Calendar** | ✅ Full CalDAV + tasks (20+ tools) | ✅ Events, free/busy, tasks (4 tools) |
 | **Contacts** | ✅ Full CardDAV (8 tools) | ✅ Find person, current user (2 tools) |
 | **Files (WebDAV)** | ✅ Full filesystem access (12 tools) | ✅ Read, folder tree, sharing (3 tools) |
+| **Document Processing** | ✅ OCR with progress (PDF, DOCX, images) | ❌ Not implemented |
 | **Deck** | ✅ Full project management (15 tools) | ✅ Basic board/card ops (2 tools) |
 | **Tables** | ✅ Row operations (5 tools) | ❌ Not implemented |
 | **Cookbook** | ✅ Full recipe management (13 tools) | ❌ Not implemented |
@@ -182,13 +183,85 @@ Or connect from:
 The server exposes Nextcloud functionality through MCP tools (for actions) and resources (for data browsing).
 
 ### Tools
-Tools enable AI assistants to perform actions:
+
+The server provides 90+ tools across 8 Nextcloud apps. When using OAuth, tools are dynamically filtered based on your granted scopes.
+
+For a complete list of all supported OAuth scopes and their descriptions, see [OAuth Scopes Documentation](docs/oauth-architecture.md#oauth-scopes).
+
+#### Available Tool Categories
+
+| App | Tools | Read Scope | Write Scope | Operations |
+|-----|-------|-----------|-------------|------------|
+| **Notes** | 7 | `notes:read` | `notes:write` | Create, read, update, delete, search notes |
+| **Calendar** | 20+ | `calendar:read` `todo:read`  | `calendar:write` `todo:write`   | Events, todos (tasks), calendars, recurring events, attendees |
+| **Contacts** | 8 | `contacts:read` | `contacts:write` | Create, read, update, delete contacts and address books |
+| **Files (WebDAV)** | 12 | `files:read` | `files:write` | List, read, upload, delete, move files; **OCR/document processing** |
+| **Deck** | 15 | `deck:read` | `deck:write` | Boards, stacks, cards, labels, assignments |
+| **Cookbook** | 13 | `cookbook:read` | `cookbook:write` | Recipes, import from URLs, search, categories |
+| **Tables** | 5 | `tables:read` | `tables:write` | Row operations on Nextcloud Tables |
+| **Sharing** | 10+ | `sharing:read` | `sharing:write` | Create, manage, delete shares |
+
+#### Document Processing (Optional)
+
+The WebDAV file reading tool (`nc_webdav_read_file`) supports **automatic text extraction** from documents and images:
+
+**Supported Formats:**
+- **Documents**: PDF, DOCX, PPTX, XLSX, RTF, ODT, EPUB
+- **Images**: PNG, JPEG, TIFF, BMP (with OCR)
+- **Email**: EML, MSG files
+
+**Features:**
+- **Progress Notifications**: Long-running OCR operations (up to 120s) send progress updates every 10 seconds to prevent client timeouts
+- **Pluggable Architecture**: Multiple processor backends (Unstructured.io, Tesseract, custom HTTP APIs)
+- **Automatic Detection**: Files are processed based on MIME type
+- **Graceful Fallback**: Returns base64-encoded content if processing fails
+
+**Configuration:**
+```dotenv
+# Enable document processing (optional)
+ENABLE_DOCUMENT_PROCESSING=true
+
+# Unstructured.io processor (cloud/API-based, supports many formats)
+ENABLE_UNSTRUCTURED=true
+UNSTRUCTURED_API_URL=http://localhost:8002
+UNSTRUCTURED_STRATEGY=auto  # auto, fast, or hi_res
+UNSTRUCTURED_LANGUAGES=eng,deu
+PROGRESS_INTERVAL=10  # Progress update interval in seconds
+
+# Tesseract processor (local OCR, images only)
+ENABLE_TESSERACT=false
+TESSERACT_LANG=eng
+
+# Custom HTTP processor
+ENABLE_CUSTOM_PROCESSOR=false
+CUSTOM_PROCESSOR_URL=http://localhost:9000/process
+CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg
+```
+
+**Example Usage:**
+```
+AI: "Read the contents of Documents/report.pdf"
+→ Uses nc_webdav_read_file tool with automatic OCR processing
+→ Returns extracted text with parsing metadata
+→ Sends progress updates during long operations
+```
+
+See [env.sample](env.sample) for complete configuration options.
+
+**Example Tools:**
 - `nc_notes_create_note` - Create a new note
 - `nc_cookbook_import_recipe` - Import recipes from URLs with schema.org metadata
 - `deck_create_card` - Create a Deck card
 - `nc_calendar_create_event` - Create a calendar event
+- `nc_calendar_create_todo` - Create a CalDAV task/todo
 - `nc_contacts_create_contact` - Create a contact
-- And many more...
+- `nc_webdav_upload_file` - Upload a file to Nextcloud
+- And 80+ more...
+
+> [!TIP]
+> **OAuth Scope Filtering**: When connecting via OAuth, MCP clients will only see tools for which you've granted access. For example, granting only `notes:read` and `notes:write` will show 7 Notes tools instead of all 90+ tools. See [OAuth Scopes Documentation](docs/oauth-architecture.md#oauth-scopes) for the complete scope reference, or [OAuth Troubleshooting - Limited Scopes](docs/oauth-troubleshooting.md#limited-scopes---only-seeing-notes-tools) if you're only seeing a subset of tools.
+>
+> **Known Issue**: Claude Code and some other MCP clients may only request/grant Notes scopes during initial connection. Track progress at [#234](https://github.com/cbcoutinho/nextcloud-mcp-server/issues/234).
 
 ### Resources
 Resources provide read-only access to Nextcloud data:

app-hooks/post-installation/10-install-oidc-app.sh

@@ -33,5 +33,6 @@ fi
 # Configure OIDC Identity Provider with dynamic client registration enabled
 php /var/www/html/occ config:app:set oidc dynamic_client_registration --value='true'
 php /var/www/html/occ config:app:set oidc proof_key_for_code_exchange --value=true --type=boolean
+php /var/www/html/occ config:app:set oidc default_token_type --value='jwt'
 
 echo "OIDC app installed and configured successfully"

charts/nextcloud-mcp-server/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

charts/nextcloud-mcp-server/Chart.yaml

@@ -0,0 +1,23 @@
+apiVersion: v2
+name: nextcloud-mcp-server
+description: A Helm chart for Nextcloud MCP Server - enables AI assistants to interact with Nextcloud
+type: application
+version: 0.1.0
+appVersion: "0.21.0"
+keywords:
+  - nextcloud
+  - mcp
+  - model-context-protocol
+  - llm
+  - ai
+  - claude
+  - webdav
+  - caldav
+  - carddav
+maintainers:
+  - name: Chris Coutinho
+    email: chris@coutinho.io
+home: https://github.com/cbcoutinho/nextcloud-mcp-server
+sources:
+  - https://github.com/cbcoutinho/nextcloud-mcp-server
+icon: https://raw.githubusercontent.com/nextcloud/server/master/core/img/logo/logo.svg

charts/nextcloud-mcp-server/README.md

@@ -0,0 +1,470 @@
+# Nextcloud MCP Server Helm Chart
+
+This Helm chart deploys the Nextcloud MCP (Model Context Protocol) Server on a Kubernetes cluster, enabling AI assistants to interact with your Nextcloud instance.
+
+## Prerequisites
+
+- Kubernetes 1.19+
+- Helm 3.0+
+- A running Nextcloud instance (accessible from the Kubernetes cluster)
+- Nextcloud credentials (username/password for basic auth OR OAuth client for OAuth mode)
+
+## Installation
+
+### Quick Start with Basic Authentication
+
+```bash
+# Install with basic auth (recommended for most users)
+helm install nextcloud-mcp ./helm/nextcloud-mcp-server \
+  --set nextcloud.host=https://cloud.example.com \
+  --set auth.basic.username=myuser \
+  --set auth.basic.password=mypassword
+```
+
+### Using a values file
+
+Create a `custom-values.yaml` file:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    username: myuser
+    password: mypassword
+
+resources:
+  limits:
+    cpu: 1000m
+    memory: 512Mi
+  requests:
+    cpu: 100m
+    memory: 128Mi
+```
+
+Install with your custom values:
+
+```bash
+helm install nextcloud-mcp ./helm/nextcloud-mcp-server -f custom-values.yaml
+```
+
+### OAuth Authentication Mode (Experimental)
+
+**Warning:** OAuth mode is experimental and requires patches to the Nextcloud `user_oidc` app. See the [Authentication Guide](https://github.com/cbcoutinho/nextcloud-mcp-server#authentication) for details.
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+  mcpServerUrl: https://mcp.example.com
+  publicIssuerUrl: https://cloud.example.com
+
+auth:
+  mode: oauth
+  oauth:
+    # Optional: provide pre-registered client credentials
+    # If not provided, will use Dynamic Client Registration
+    clientId: "your-client-id"
+    clientSecret: "your-client-secret"
+    persistence:
+      enabled: true
+      size: 100Mi
+
+ingress:
+  enabled: true
+  className: nginx
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: nextcloud-mcp-tls
+      hosts:
+        - mcp.example.com
+```
+
+## Configuration
+
+### Key Configuration Parameters
+
+#### Nextcloud Connection
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `nextcloud.host` | URL of your Nextcloud instance (required) | `""` |
+| `nextcloud.mcpServerUrl` | MCP server URL for OAuth callbacks (OAuth only, optional) | Smart default* |
+| `nextcloud.publicIssuerUrl` | Public issuer URL for OAuth (OAuth only, optional) | Smart default** |
+
+**Smart Defaults:**
+- `*mcpServerUrl`: If not set, automatically uses ingress host (if enabled) or `http://localhost:8000` (for port-forward setups)
+- `**publicIssuerUrl`: If not set, automatically defaults to `nextcloud.host` (which works when both clients and MCP server access Nextcloud at the same URL)
+
+#### Authentication
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `auth.mode` | Authentication mode: `basic` or `oauth` | `basic` |
+| `auth.basic.username` | Nextcloud username (basic auth) | `""` |
+| `auth.basic.password` | Nextcloud password (basic auth) | `""` |
+| `auth.basic.existingSecret` | Use existing secret for credentials | `""` |
+| `auth.oauth.clientId` | OAuth client ID (OAuth mode, optional) | `""` |
+| `auth.oauth.clientSecret` | OAuth client secret (OAuth mode, optional) | `""` |
+| `auth.oauth.persistence.enabled` | Enable persistent storage for OAuth | `true` |
+| `auth.oauth.persistence.size` | Size of OAuth storage PVC | `100Mi` |
+
+#### Image Configuration
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `image.repository` | Container image repository | `ghcr.io/cbcoutinho/nextcloud-mcp-server` |
+| `image.tag` | Container image tag | `""` (uses chart appVersion) |
+| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
+
+#### Resources
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `resources.limits.cpu` | CPU limit | `1000m` |
+| `resources.limits.memory` | Memory limit | `512Mi` |
+| `resources.requests.cpu` | CPU request | `100m` |
+| `resources.requests.memory` | Memory request | `128Mi` |
+
+#### Service
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `service.type` | Service type | `ClusterIP` |
+| `service.port` | Service port | `8000` |
+| `service.oauthPort` | OAuth service port | `8001` |
+
+#### Ingress
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `ingress.enabled` | Enable ingress | `false` |
+| `ingress.className` | Ingress class name | `""` |
+| `ingress.hosts` | Ingress host configuration | See values.yaml |
+| `ingress.tls` | Ingress TLS configuration | `[]` |
+
+#### Autoscaling
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `autoscaling.enabled` | Enable HPA | `false` |
+| `autoscaling.minReplicas` | Minimum replicas | `1` |
+| `autoscaling.maxReplicas` | Maximum replicas | `10` |
+| `autoscaling.targetCPUUtilizationPercentage` | Target CPU % | `80` |
+
+#### Health Probes
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `livenessProbe.httpGet.path` | Liveness probe endpoint | `/health/live` |
+| `livenessProbe.initialDelaySeconds` | Initial delay for liveness | `30` |
+| `livenessProbe.periodSeconds` | Check interval for liveness | `10` |
+| `readinessProbe.httpGet.path` | Readiness probe endpoint | `/health/ready` |
+| `readinessProbe.initialDelaySeconds` | Initial delay for readiness | `10` |
+| `readinessProbe.periodSeconds` | Check interval for readiness | `5` |
+
+The application exposes HTTP health check endpoints:
+- `/health/live` - Liveness probe (checks if application is running)
+- `/health/ready` - Readiness probe (checks if application is ready to serve traffic)
+
+#### Document Processing (Optional)
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `documentProcessing.enabled` | Enable document processing | `false` |
+| `documentProcessing.defaultProcessor` | Default processor | `unstructured` |
+| `documentProcessing.unstructured.enabled` | Enable Unstructured.io processor | `false` |
+| `documentProcessing.unstructured.apiUrl` | Unstructured API URL | `http://unstructured:8000` |
+| `documentProcessing.tesseract.enabled` | Enable Tesseract OCR | `false` |
+
+## Examples
+
+### Example 1: Basic Auth with Ingress
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    username: admin
+    password: secure-password
+
+ingress:
+  enabled: true
+  className: nginx
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: mcp-tls
+      hosts:
+        - mcp.example.com
+
+resources:
+  limits:
+    cpu: 2000m
+    memory: 1Gi
+  requests:
+    cpu: 200m
+    memory: 256Mi
+```
+
+### Example 2: Using Existing Secrets
+
+#### Basic Auth with Existing Secret
+
+Create a secret manually:
+
+```bash
+kubectl create secret generic nextcloud-credentials \
+  --from-literal=username=myuser \
+  --from-literal=password=mypassword
+```
+
+Then reference it in your values:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    existingSecret: nextcloud-credentials
+    usernameKey: username
+    passwordKey: password
+```
+
+#### OAuth with Existing Secret (Pre-registered Client)
+
+If you have a pre-registered OAuth client:
+
+```bash
+kubectl create secret generic nextcloud-oauth-creds \
+  --from-literal=clientId=my-oauth-client-id \
+  --from-literal=clientSecret=my-oauth-client-secret
+```
+
+Then reference it in your values:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+  # mcpServerUrl and publicIssuerUrl are optional!
+  # If not set, mcpServerUrl defaults to ingress host or localhost
+  # publicIssuerUrl defaults to nextcloud.host
+
+auth:
+  mode: oauth
+  oauth:
+    existingSecret: nextcloud-oauth-creds
+    clientIdKey: clientId
+    clientSecretKey: clientSecret
+    persistence:
+      enabled: true
+
+ingress:
+  enabled: true
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: mcp-tls
+      hosts:
+        - mcp.example.com
+```
+
+### Example 3: OAuth with Document Processing and Dynamic Client Registration
+
+This example shows OAuth without pre-registered credentials (using DCR) and optional URL values:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+  # mcpServerUrl will automatically use ingress host (https://mcp.example.com)
+  # publicIssuerUrl will automatically default to nextcloud.host
+
+auth:
+  mode: oauth
+  oauth:
+    # No clientId/clientSecret - will use Dynamic Client Registration!
+    persistence:
+      enabled: true
+      storageClass: fast-ssd
+      size: 200Mi
+
+documentProcessing:
+  enabled: true
+  defaultProcessor: unstructured
+  unstructured:
+    enabled: true
+    apiUrl: http://unstructured-api:8000
+    strategy: hi_res
+    languages: eng,deu,fra
+
+ingress:
+  enabled: true
+  className: nginx
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+```
+
+### Example 4: High Availability with Autoscaling
+
+```yaml
+replicaCount: 2
+
+autoscaling:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 20
+  targetCPUUtilizationPercentage: 70
+  targetMemoryUtilizationPercentage: 80
+
+resources:
+  limits:
+    cpu: 2000m
+    memory: 1Gi
+  requests:
+    cpu: 500m
+    memory: 512Mi
+
+affinity:
+  podAntiAffinity:
+    preferredDuringSchedulingIgnoredDuringExecution:
+      - weight: 100
+        podAffinityTerm:
+          labelSelector:
+            matchExpressions:
+              - key: app.kubernetes.io/name
+                operator: In
+                values:
+                  - nextcloud-mcp-server
+          topologyKey: kubernetes.io/hostname
+```
+
+## Upgrading
+
+### To upgrade an existing deployment:
+
+```bash
+helm upgrade nextcloud-mcp ./helm/nextcloud-mcp-server -f custom-values.yaml
+```
+
+### To upgrade with new values:
+
+```bash
+helm upgrade nextcloud-mcp ./helm/nextcloud-mcp-server \
+  --set image.tag=0.21.0 \
+  --set resources.limits.memory=1Gi
+```
+
+## Uninstalling
+
+```bash
+helm uninstall nextcloud-mcp
+```
+
+**Note:** This will delete all resources including PVCs. If you want to preserve OAuth client data, backup the PVC before uninstalling.
+
+## Troubleshooting
+
+### Check pod status
+
+```bash
+kubectl get pods -l app.kubernetes.io/name=nextcloud-mcp-server
+```
+
+### View logs
+
+```bash
+kubectl logs -l app.kubernetes.io/name=nextcloud-mcp-server --tail=100 -f
+```
+
+### Check health endpoints
+
+The application exposes health check endpoints for monitoring:
+
+```bash
+# Port forward to the service
+kubectl port-forward svc/nextcloud-mcp 8000:8000
+
+# Check liveness (if app is running)
+curl http://localhost:8000/health/live
+
+# Check readiness (if app is ready to serve traffic)
+curl http://localhost:8000/health/ready
+```
+
+**Example responses:**
+
+Liveness (always returns 200 if running):
+```json
+{
+  "status": "alive",
+  "mode": "basic"
+}
+```
+
+Readiness (returns 200 if ready, 503 if not ready):
+```json
+{
+  "status": "ready",
+  "checks": {
+    "nextcloud_configured": "ok",
+    "auth_mode": "basic",
+    "auth_configured": "ok"
+  }
+}
+```
+
+### Common Issues
+
+1. **Connection refused to Nextcloud**
+   - Verify `nextcloud.host` is accessible from the Kubernetes cluster
+   - Check network policies and firewall rules
+
+2. **Authentication failures**
+   - For basic auth: verify username/password are correct
+   - For OAuth: check that OIDC app is properly configured
+
+3. **OAuth persistence issues**
+   - Verify PVC is bound: `kubectl get pvc`
+   - Check storage class exists: `kubectl get storageclass`
+
+4. **Resource constraints**
+   - Increase memory limits if seeing OOM errors
+   - Adjust CPU requests based on load
+
+## Security Considerations
+
+1. **Secrets Management**: Consider using external secret management (e.g., Sealed Secrets, External Secrets Operator)
+2. **TLS**: Always use TLS/HTTPS for production deployments
+3. **Network Policies**: Restrict network access to necessary services only
+4. **RBAC**: Review and customize ServiceAccount permissions as needed
+5. **App Passwords**: For basic auth, use Nextcloud app passwords instead of main account passwords
+
+## Support
+
+- GitHub Issues: https://github.com/cbcoutinho/nextcloud-mcp-server/issues
+- Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme
+
+## License
+
+This chart is licensed under AGPL-3.0, consistent with the Nextcloud MCP Server project.

charts/nextcloud-mcp-server/templates/NOTES.txt

@@ -0,0 +1,80 @@
+Thank you for installing {{ .Chart.Name }}!
+
+Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentication mode.
+
+1. Get the application URL by running these commands:
+{{- if .Values.ingress.enabled }}
+{{- range $host := .Values.ingress.hosts }}
+  {{- range .paths }}
+  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }}
+  {{- end }}
+{{- end }}
+{{- else if contains "NodePort" .Values.service.type }}
+  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "nextcloud-mcp-server.fullname" . }})
+  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
+  echo http://$NODE_IP:$NODE_PORT
+{{- else if contains "LoadBalancer" .Values.service.type }}
+     NOTE: It may take a few minutes for the LoadBalancer IP to be available.
+           You can watch the status of by running 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "nextcloud-mcp-server.fullname" . }}'
+  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "nextcloud-mcp-server.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}")
+  echo http://$SERVICE_IP:{{ .Values.service.port }}
+{{- else if contains "ClusterIP" .Values.service.type }}
+  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "nextcloud-mcp-server.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
+  export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
+  echo "Visit http://127.0.0.1:8080 to use your MCP server"
+  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT
+{{- end }}
+
+2. Check the deployment status:
+  kubectl --namespace {{ .Release.Namespace }} get pods -l "app.kubernetes.io/name={{ include "nextcloud-mcp-server.name" . }},app.kubernetes.io/instance={{ .Release.Name }}"
+
+{{- if eq .Values.auth.mode "basic" }}
+
+3. Basic Authentication Mode:
+   {{- if .Values.auth.basic.existingSecret }}
+   - Credentials: (using existing secret {{ .Values.auth.basic.existingSecret }})
+   {{- else }}
+   - Username: {{ .Values.auth.basic.username }}
+   - Password: (stored in secret {{ include "nextcloud-mcp-server.basicAuthSecretName" . }})
+   {{- end }}
+   - Connected to: {{ .Values.nextcloud.host }}
+{{- else if eq .Values.auth.mode "oauth" }}
+
+3. OAuth Authentication Mode:
+   - Server URL: {{ include "nextcloud-mcp-server.mcpServerUrl" . }}
+   - Issuer URL: {{ include "nextcloud-mcp-server.publicIssuerUrl" . }}
+   - Connected to: {{ .Values.nextcloud.host }}
+   {{- if .Values.auth.oauth.existingSecret }}
+   - Using existing OAuth client secret: {{ .Values.auth.oauth.existingSecret }}
+   {{- else if and .Values.auth.oauth.clientId .Values.auth.oauth.clientSecret }}
+   - Using pre-registered OAuth client
+   {{- else }}
+   - Using Dynamic Client Registration (DCR)
+   {{- end }}
+   {{- if .Values.auth.oauth.persistence.enabled }}
+   - OAuth client credentials are persisted in PVC: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
+   {{- end }}
+
+   IMPORTANT: OAuth mode is experimental and requires patches to the user_oidc app.
+   See: https://github.com/cbcoutinho/nextcloud-mcp-server#authentication
+{{- end }}
+
+{{- if .Values.documentProcessing.enabled }}
+
+4. Document Processing:
+   - Enabled: {{ .Values.documentProcessing.enabled }}
+   - Default processor: {{ .Values.documentProcessing.defaultProcessor }}
+   {{- if .Values.documentProcessing.unstructured.enabled }}
+   - Unstructured API: {{ .Values.documentProcessing.unstructured.apiUrl }}
+   {{- end }}
+{{- end }}
+
+For more information and documentation:
+- GitHub: https://github.com/cbcoutinho/nextcloud-mcp-server
+- Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme
+
+To upgrade this deployment:
+  helm upgrade {{ .Release.Name }} nextcloud-mcp-server
+
+To uninstall:
+  helm uninstall {{ .Release.Name }}

charts/nextcloud-mcp-server/templates/_helpers.tpl

@@ -0,0 +1,146 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "nextcloud-mcp-server.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "nextcloud-mcp-server.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "nextcloud-mcp-server.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "nextcloud-mcp-server.labels" -}}
+helm.sh/chart: {{ include "nextcloud-mcp-server.chart" . }}
+{{ include "nextcloud-mcp-server.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "nextcloud-mcp-server.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "nextcloud-mcp-server.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "nextcloud-mcp-server.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "nextcloud-mcp-server.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the secret to use for basic auth
+*/}}
+{{- define "nextcloud-mcp-server.basicAuthSecretName" -}}
+{{- if .Values.auth.basic.existingSecret }}
+{{- .Values.auth.basic.existingSecret }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-basic-auth
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the secret to use for OAuth
+*/}}
+{{- define "nextcloud-mcp-server.oauthSecretName" -}}
+{{- if .Values.auth.oauth.existingSecret }}
+{{- .Values.auth.oauth.existingSecret }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-oauth
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the PVC to use for OAuth storage
+*/}}
+{{- define "nextcloud-mcp-server.oauthPvcName" -}}
+{{- if .Values.auth.oauth.persistence.existingClaim }}
+{{- .Values.auth.oauth.persistence.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-oauth-storage
+{{- end }}
+{{- end }}
+
+{{/*
+Return the appropriate MCP server port based on auth mode
+*/}}
+{{- define "nextcloud-mcp-server.port" -}}
+{{- if eq .Values.auth.mode "oauth" }}
+{{- .Values.auth.oauth.port }}
+{{- else }}
+{{- .Values.mcp.port }}
+{{- end }}
+{{- end }}
+
+{{/*
+Return the image tag
+*/}}
+{{- define "nextcloud-mcp-server.imageTag" -}}
+{{- .Values.image.tag | default .Chart.AppVersion }}
+{{- end }}
+
+{{/*
+Return the public issuer URL for OAuth
+Defaults to nextcloud.host if not specified
+*/}}
+{{- define "nextcloud-mcp-server.publicIssuerUrl" -}}
+{{- if .Values.nextcloud.publicIssuerUrl }}
+{{- .Values.nextcloud.publicIssuerUrl }}
+{{- else }}
+{{- .Values.nextcloud.host }}
+{{- end }}
+{{- end }}
+
+{{/*
+Return the MCP server URL for OAuth callbacks
+If not specified:
+  - Uses ingress host if ingress is enabled
+  - Otherwise defaults to http://localhost:8000 (for port-forward setups)
+*/}}
+{{- define "nextcloud-mcp-server.mcpServerUrl" -}}
+{{- if .Values.nextcloud.mcpServerUrl }}
+{{- .Values.nextcloud.mcpServerUrl }}
+{{- else if .Values.ingress.enabled }}
+{{- $host := index .Values.ingress.hosts 0 }}
+{{- if .Values.ingress.tls }}
+{{- printf "https://%s" $host.host }}
+{{- else }}
+{{- printf "http://%s" $host.host }}
+{{- end }}
+{{- else }}
+{{- printf "http://localhost:%d" (int .Values.mcp.port) }}
+{{- end }}
+{{- end }}

charts/nextcloud-mcp-server/templates/deployment.yaml

@@ -0,0 +1,189 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  {{- if not .Values.autoscaling.enabled }}
+  replicas: {{ .Values.replicaCount }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "nextcloud-mcp-server.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      annotations:
+        checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
+        {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      labels:
+        {{- include "nextcloud-mcp-server.labels" . | nindent 8 }}
+        {{- with .Values.podLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+    spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      serviceAccountName: {{ include "nextcloud-mcp-server.serviceAccountName" . }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      {{- with .Values.initContainers }}
+      initContainers:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: {{ .Chart.Name }}
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
+          image: "{{ .Values.image.repository }}:{{ include "nextcloud-mcp-server.imageTag" . }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          args:
+            - "--transport"
+            - "{{ .Values.mcp.transport }}"
+            {{- if eq .Values.auth.mode "oauth" }}
+            - "--oauth"
+            - "--port"
+            - "{{ .Values.auth.oauth.port }}"
+            - "--oauth-token-type"
+            - "{{ .Values.auth.oauth.tokenType }}"
+            {{- end }}
+          ports:
+            - name: http
+              containerPort: {{ include "nextcloud-mcp-server.port" . }}
+              protocol: TCP
+          env:
+            # Nextcloud connection
+            - name: NEXTCLOUD_HOST
+              value: {{ .Values.nextcloud.host | quote }}
+            {{- if eq .Values.auth.mode "basic" }}
+            # Basic auth mode
+            - name: NEXTCLOUD_USERNAME
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.basicAuthSecretName" . }}
+                  key: {{ .Values.auth.basic.usernameKey }}
+            - name: NEXTCLOUD_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.basicAuthSecretName" . }}
+                  key: {{ .Values.auth.basic.passwordKey }}
+            {{- else if eq .Values.auth.mode "oauth" }}
+            # OAuth mode
+            - name: NEXTCLOUD_MCP_SERVER_URL
+              value: {{ include "nextcloud-mcp-server.mcpServerUrl" . | quote }}
+            - name: NEXTCLOUD_PUBLIC_ISSUER_URL
+              value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
+            - name: NEXTCLOUD_OIDC_CLIENT_STORAGE
+              value: "/app/.oauth/nextcloud_oauth_client.json"
+            - name: NEXTCLOUD_OIDC_SCOPES
+              value: {{ .Values.auth.oauth.scopes | quote }}
+            {{- if .Values.auth.oauth.clientId }}
+            - name: NEXTCLOUD_OIDC_CLIENT_ID
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.oauthSecretName" . }}
+                  key: {{ .Values.auth.oauth.clientIdKey }}
+            - name: NEXTCLOUD_OIDC_CLIENT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.oauthSecretName" . }}
+                  key: {{ .Values.auth.oauth.clientSecretKey }}
+            {{- end }}
+            {{- end }}
+            {{- if .Values.documentProcessing.enabled }}
+            # Document processing
+            - name: ENABLE_DOCUMENT_PROCESSING
+              value: {{ .Values.documentProcessing.enabled | quote }}
+            - name: DOCUMENT_PROCESSOR
+              value: {{ .Values.documentProcessing.defaultProcessor | quote }}
+            - name: PROGRESS_INTERVAL
+              value: {{ .Values.documentProcessing.progressInterval | quote }}
+            {{- if .Values.documentProcessing.unstructured.enabled }}
+            - name: ENABLE_UNSTRUCTURED
+              value: "true"
+            - name: UNSTRUCTURED_API_URL
+              value: {{ .Values.documentProcessing.unstructured.apiUrl | quote }}
+            - name: UNSTRUCTURED_TIMEOUT
+              value: {{ .Values.documentProcessing.unstructured.timeout | quote }}
+            - name: UNSTRUCTURED_STRATEGY
+              value: {{ .Values.documentProcessing.unstructured.strategy | quote }}
+            - name: UNSTRUCTURED_LANGUAGES
+              value: {{ .Values.documentProcessing.unstructured.languages | quote }}
+            {{- end }}
+            {{- if .Values.documentProcessing.tesseract.enabled }}
+            - name: ENABLE_TESSERACT
+              value: "true"
+            {{- if .Values.documentProcessing.tesseract.cmd }}
+            - name: TESSERACT_CMD
+              value: {{ .Values.documentProcessing.tesseract.cmd | quote }}
+            {{- end }}
+            - name: TESSERACT_LANG
+              value: {{ .Values.documentProcessing.tesseract.lang | quote }}
+            {{- end }}
+            {{- if .Values.documentProcessing.custom.enabled }}
+            - name: ENABLE_CUSTOM_PROCESSOR
+              value: "true"
+            - name: CUSTOM_PROCESSOR_NAME
+              value: {{ .Values.documentProcessing.custom.name | quote }}
+            - name: CUSTOM_PROCESSOR_URL
+              value: {{ .Values.documentProcessing.custom.url | quote }}
+            {{- if .Values.documentProcessing.custom.apiKey }}
+            - name: CUSTOM_PROCESSOR_API_KEY
+              value: {{ .Values.documentProcessing.custom.apiKey | quote }}
+            {{- end }}
+            - name: CUSTOM_PROCESSOR_TIMEOUT
+              value: {{ .Values.documentProcessing.custom.timeout | quote }}
+            - name: CUSTOM_PROCESSOR_TYPES
+              value: {{ .Values.documentProcessing.custom.types | quote }}
+            {{- end }}
+            {{- end }}
+            {{- with .Values.extraEnv }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+          {{- with .Values.extraEnvFrom }}
+          envFrom:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          livenessProbe:
+            {{- toYaml .Values.livenessProbe | nindent 12 }}
+          readinessProbe:
+            {{- toYaml .Values.readinessProbe | nindent 12 }}
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          volumeMounts:
+            - name: tmp
+              mountPath: /tmp
+            {{- if and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled }}
+            - name: oauth-storage
+              mountPath: /app/.oauth
+            {{- end }}
+            {{- with .Values.volumeMounts }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+      volumes:
+        - name: tmp
+          emptyDir: {}
+        {{- if and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled }}
+        - name: oauth-storage
+          persistentVolumeClaim:
+            claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
+        {{- end }}
+        {{- with .Values.volumes }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

charts/nextcloud-mcp-server/templates/hpa.yaml

@@ -0,0 +1,32 @@
+{{- if .Values.autoscaling.enabled }}
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ include "nextcloud-mcp-server.fullname" . }}
+  minReplicas: {{ .Values.autoscaling.minReplicas }}
+  maxReplicas: {{ .Values.autoscaling.maxReplicas }}
+  metrics:
+    {{- if .Values.autoscaling.targetCPUUtilizationPercentage }}
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
+    {{- end }}
+    {{- if .Values.autoscaling.targetMemoryUtilizationPercentage }}
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.autoscaling.targetMemoryUtilizationPercentage }}
+    {{- end }}
+{{- end }}

charts/nextcloud-mcp-server/templates/ingress.yaml

@@ -0,0 +1,61 @@
+{{- if .Values.ingress.enabled -}}
+{{- $fullName := include "nextcloud-mcp-server.fullname" . -}}
+{{- $svcPort := .Values.service.port -}}
+{{- if and .Values.ingress.className (not (semverCompare ">=1.18-0" .Capabilities.KubeVersion.GitVersion)) }}
+  {{- if not (hasKey .Values.ingress.annotations "kubernetes.io/ingress.class") }}
+  {{- $_ := set .Values.ingress.annotations "kubernetes.io/ingress.class" .Values.ingress.className}}
+  {{- end }}
+{{- end }}
+{{- if semverCompare ">=1.19-0" .Capabilities.KubeVersion.GitVersion -}}
+apiVersion: networking.k8s.io/v1
+{{- else if semverCompare ">=1.14-0" .Capabilities.KubeVersion.GitVersion -}}
+apiVersion: networking.k8s.io/v1beta1
+{{- else -}}
+apiVersion: extensions/v1beta1
+{{- end }}
+kind: Ingress
+metadata:
+  name: {{ $fullName }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  {{- if and .Values.ingress.className (semverCompare ">=1.18-0" .Capabilities.KubeVersion.GitVersion) }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if .Values.ingress.tls }}
+  tls:
+    {{- range .Values.ingress.tls }}
+    - hosts:
+        {{- range .hosts }}
+        - {{ . | quote }}
+        {{- end }}
+      secretName: {{ .secretName }}
+    {{- end }}
+  {{- end }}
+  rules:
+    {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+          {{- range .paths }}
+          - path: {{ .path }}
+            {{- if and .pathType (semverCompare ">=1.18-0" $.Capabilities.KubeVersion.GitVersion) }}
+            pathType: {{ .pathType }}
+            {{- end }}
+            backend:
+              {{- if semverCompare ">=1.19-0" $.Capabilities.KubeVersion.GitVersion }}
+              service:
+                name: {{ $fullName }}
+                port:
+                  number: {{ $svcPort }}
+              {{- else }}
+              serviceName: {{ $fullName }}
+              servicePort: {{ $svcPort }}
+              {{- end }}
+          {{- end }}
+    {{- end }}
+{{- end }}

charts/nextcloud-mcp-server/templates/pvc.yaml

@@ -0,0 +1,17 @@
+{{- if and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled (not .Values.auth.oauth.persistence.existingClaim) }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-oauth-storage
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - {{ .Values.auth.oauth.persistence.accessMode }}
+  {{- if .Values.auth.oauth.persistence.storageClass }}
+  storageClassName: {{ .Values.auth.oauth.persistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.auth.oauth.persistence.size }}
+{{- end }}

charts/nextcloud-mcp-server/templates/secret.yaml

@@ -0,0 +1,29 @@
+{{- if eq .Values.auth.mode "basic" }}
+{{- if not .Values.auth.basic.existingSecret }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-basic-auth
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.auth.basic.usernameKey }}: {{ .Values.auth.basic.username | b64enc | quote }}
+  {{ .Values.auth.basic.passwordKey }}: {{ .Values.auth.basic.password | b64enc | quote }}
+{{- end }}
+{{- end }}
+---
+{{- if eq .Values.auth.mode "oauth" }}
+{{- if and .Values.auth.oauth.clientId (not .Values.auth.oauth.existingSecret) }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-oauth
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.auth.oauth.clientIdKey }}: {{ .Values.auth.oauth.clientId | b64enc | quote }}
+  {{ .Values.auth.oauth.clientSecretKey }}: {{ .Values.auth.oauth.clientSecret | b64enc | quote }}
+{{- end }}
+{{- end }}

charts/nextcloud-mcp-server/templates/service.yaml

@@ -0,0 +1,19 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+  {{- with .Values.service.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    {{- include "nextcloud-mcp-server.selectorLabels" . | nindent 4 }}

charts/nextcloud-mcp-server/templates/serviceaccount.yaml

@@ -0,0 +1,13 @@
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "nextcloud-mcp-server.serviceAccountName" . }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+  {{- with .Values.serviceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+automountServiceAccountToken: {{ .Values.serviceAccount.automount }}
+{{- end }}

charts/nextcloud-mcp-server/values.yaml

@@ -0,0 +1,268 @@
+# Default values for nextcloud-mcp-server
+# This is a YAML-formatted file.
+# Declare variables to be passed into your templates.
+
+# Number of replicas
+replicaCount: 1
+
+image:
+  repository: ghcr.io/cbcoutinho/nextcloud-mcp-server
+  pullPolicy: IfNotPresent
+  # Overrides the image tag whose default is the chart appVersion.
+  tag: ""
+
+imagePullSecrets: []
+nameOverride: ""
+fullnameOverride: ""
+
+# Nextcloud connection settings
+nextcloud:
+  # URL of your Nextcloud instance (required)
+  # Example: https://cloud.example.com
+  host: ""
+
+  # MCP server URL for OAuth callbacks (OAuth mode only)
+  # If not specified, will be constructed from ingress.hosts[0] if ingress is enabled,
+  # or defaults to http://localhost:8000 (suitable for port-forward setups)
+  # Example: https://mcp.example.com
+  mcpServerUrl: ""
+
+  # Public issuer URL for OAuth (OAuth mode only)
+  # If not specified, defaults to nextcloud.host
+  # Only set this if your Nextcloud is accessible at a different URL for OAuth
+  # Example: https://cloud.example.com
+  publicIssuerUrl: ""
+
+# Authentication configuration
+# Choose either basic auth OR oauth (not both)
+auth:
+  # Authentication mode: "basic" or "oauth"
+  # basic: Uses username/password (recommended for most users)
+  # oauth: Uses OAuth2/OIDC (experimental, requires patches)
+  mode: basic
+
+  # Basic authentication settings
+  basic:
+    # Nextcloud username (ignored if existingSecret is set)
+    username: ""
+    # Nextcloud password or app password (recommended) (ignored if existingSecret is set)
+    password: ""
+    # Use existing secret instead of creating one
+    # If set, username and password above are ignored
+    # Secret must contain keys specified in usernameKey and passwordKey
+    # Example:
+    #   kubectl create secret generic my-nextcloud-creds \
+    #     --from-literal=username=myuser \
+    #     --from-literal=password=mypassword
+    existingSecret: ""
+    # Keys in the existing secret
+    usernameKey: "username"
+    passwordKey: "password"
+
+  # OAuth2/OIDC settings (experimental)
+  oauth:
+    # Port for OAuth MCP server (default: 8001)
+    port: 8001
+    # OAuth token type: "jwt" or "opaque"
+    tokenType: "jwt"
+    # Pre-registered OAuth client ID (optional, ignored if existingSecret is set)
+    # If not provided and no existingSecret, will use Dynamic Client Registration (DCR)
+    clientId: ""
+    # Pre-registered OAuth client secret (optional, ignored if existingSecret is set)
+    clientSecret: ""
+    # OAuth scopes to request (space-separated)
+    scopes: "openid profile email notes:read notes:write calendar:read calendar:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write todo:read todo:write"
+    # Use existing secret for OAuth client credentials
+    # If set, clientId and clientSecret above are ignored
+    # Secret must contain keys specified in clientIdKey and clientSecretKey
+    # Example:
+    #   kubectl create secret generic my-oauth-creds \
+    #     --from-literal=clientId=my-client-id \
+    #     --from-literal=clientSecret=my-client-secret
+    existingSecret: ""
+    # Keys in the existing secret
+    clientIdKey: "clientId"
+    clientSecretKey: "clientSecret"
+    # Persistent storage for OAuth client credentials
+    persistence:
+      enabled: true
+      # Storage class (leave empty for default)
+      storageClass: ""
+      accessMode: ReadWriteOnce
+      size: 100Mi
+      # Use existing PVC
+      existingClaim: ""
+
+# MCP server configuration
+mcp:
+  # Transport mode (default: streamable-http for SSE)
+  transport: "streamable-http"
+  # Port for basic auth mode
+  port: 8000
+
+# Document processing configuration (optional)
+documentProcessing:
+  # Enable document processing (PDF, DOCX, images, etc.)
+  enabled: false
+  # Default processor: unstructured, tesseract, or custom
+  defaultProcessor: "unstructured"
+  # Progress reporting interval in seconds
+  progressInterval: 10
+
+  # Unstructured.io processor
+  unstructured:
+    enabled: false
+    # Unstructured API endpoint
+    apiUrl: "http://unstructured:8000"
+    # Request timeout in seconds
+    timeout: 120
+    # Parsing strategy: auto, fast, or hi_res
+    strategy: "auto"
+    # OCR languages (comma-separated ISO 639-3 codes)
+    languages: "eng,deu"
+
+  # Tesseract processor (local OCR)
+  tesseract:
+    enabled: false
+    # Path to tesseract executable (optional, auto-detected if in PATH)
+    cmd: ""
+    # OCR language (e.g., eng, deu, eng+deu for multiple)
+    lang: "eng"
+
+  # Custom processor
+  custom:
+    enabled: false
+    # Unique name for your processor
+    name: "my_ocr"
+    # Custom processor API endpoint
+    url: ""
+    # Optional API key for authentication
+    apiKey: ""
+    # Request timeout in seconds
+    timeout: 60
+    # Comma-separated MIME types your processor supports
+    types: "application/pdf,image/jpeg,image/png"
+
+serviceAccount:
+  # Specifies whether a service account should be created
+  create: true
+  # Automatically mount a ServiceAccount's API credentials?
+  automount: true
+  # Annotations to add to the service account
+  annotations: {}
+  # The name of the service account to use.
+  # If not set and create is true, a name is generated using the fullname template
+  name: ""
+
+podAnnotations: {}
+podLabels: {}
+
+podSecurityContext:
+  fsGroup: 2000
+
+securityContext:
+  capabilities:
+    drop:
+    - ALL
+  readOnlyRootFilesystem: true
+  runAsNonRoot: true
+  runAsUser: 1000
+
+service:
+  type: ClusterIP
+  port: 8000
+  # For OAuth mode, you may want to expose both ports
+  oauthPort: 8001
+  annotations: {}
+
+ingress:
+  enabled: false
+  className: ""
+  annotations: {}
+    # kubernetes.io/ingress.class: nginx
+    # kubernetes.io/tls-acme: "true"
+    # cert-manager.io/cluster-issuer: letsencrypt-prod
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls: []
+  #  - secretName: nextcloud-mcp-tls
+  #    hosts:
+  #      - mcp.example.com
+
+resources:
+  # We recommend setting resource requests and limits
+  limits:
+    cpu: 1000m
+    memory: 512Mi
+  requests:
+    cpu: 100m
+    memory: 128Mi
+
+# Liveness probe configuration
+# Checks if the application process is running
+livenessProbe:
+  httpGet:
+    path: /health/live
+    port: http
+    scheme: HTTP
+  initialDelaySeconds: 30
+  periodSeconds: 10
+  timeoutSeconds: 5
+  failureThreshold: 3
+
+# Readiness probe configuration
+# Checks if the application is ready to serve traffic
+readinessProbe:
+  httpGet:
+    path: /health/ready
+    port: http
+    scheme: HTTP
+  initialDelaySeconds: 10
+  periodSeconds: 5
+  timeoutSeconds: 3
+  failureThreshold: 3
+
+# Autoscaling configuration
+autoscaling:
+  enabled: false
+  minReplicas: 1
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 80
+  # targetMemoryUtilizationPercentage: 80
+
+# Additional volumes on the output Deployment definition.
+volumes: []
+# - name: foo
+#   secret:
+#     secretName: mysecret
+#     optional: false
+
+# Additional volumeMounts on the output Deployment definition.
+volumeMounts: []
+# - name: foo
+#   mountPath: "/etc/foo"
+#   readOnly: true
+
+nodeSelector: {}
+
+tolerations: []
+
+affinity: {}
+
+# Init containers
+initContainers: []
+
+# Additional environment variables
+extraEnv: []
+# - name: CUSTOM_VAR
+#   value: "custom_value"
+
+# Additional environment variables from ConfigMaps or Secrets
+extraEnvFrom: []
+# - configMapRef:
+#     name: my-configmap
+# - secretRef:
+#     name: my-secret

docker-compose.yml

@@ -21,7 +21,7 @@ services:
     restart: always
 
   app:
-    image: docker.io/library/nextcloud:32.0.0@sha256:4fbd72f05b5e6b82e078542b6cb2ecf021d2f8b5045454ffa7f4e080e488b375
+    image: docker.io/library/nextcloud:32.0.1@sha256:1e4eae55eebe094cae6f9e7b6e0b4bccf4a4fe7b7e6f6f8f57010994b3b2ee42
     restart: always
     ports:
       - 0.0.0.0:8080:80
@@ -45,12 +45,22 @@ services:
       - REDIS_HOST=redis
 
   recipes:
-    image: docker.io/library/nginx:alpine@sha256:61e01287e546aac28a3f56839c136b31f590273f3b41187a36f46f6a03bbfe22
+    image: docker.io/library/nginx:alpine@sha256:9dacca6749f2215cc3094f641c5b6662f7791e66a57ed034e806a7c48d51c18f
     restart: always
     volumes:
       - ./tests/fixtures/test_recipe.html:/usr/share/nginx/html/test_recipe.html:ro
       - ./tests/fixtures/nginx.conf:/etc/nginx/nginx.conf:ro
 
+  unstructured:
+    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:a43ab55898599157fb0e0e097dabb8ecdd1d8e3df1ae5b67c6e15a136b171a6c
+    restart: always
+    ports:
+      - 127.0.0.1:8002:8000
+    # Unstructured API runs on port 8000 internally
+    # We expose it on 8002 externally to avoid conflict
+    profiles:
+      - unstructured
+
   mcp:
     build: .
     command: ["--transport", "streamable-http"]
@@ -66,7 +76,7 @@ services:
 
   mcp-oauth:
     build: .
-    command: ["--transport", "streamable-http", "--oauth", "--port", "8001"]
+    command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
     restart: always
     depends_on:
       - app
@@ -77,34 +87,14 @@ services:
       - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8001
       - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
       - NEXTCLOUD_OIDC_CLIENT_STORAGE=/app/.oauth/nextcloud_oauth_client.json
-      - NEXTCLOUD_OIDC_SCOPES=openid profile email nc:read nc:write
+      - NEXTCLOUD_OIDC_SCOPES=openid profile email notes:read notes:write calendar:read calendar:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write todo:read todo:write
       # No USERNAME/PASSWORD - will use OAuth with Dynamic Client Registration
       # Client credentials will be registered and stored in volume on first startup
+      # JWT token type is used for testing (faster validation, scopes embedded in token)
     volumes:
       - oauth-client-storage:/app/.oauth
 
-  mcp-oauth-jwt:
-    build: .
-    command: ["--transport", "streamable-http", "--oauth", "--port", "8002"]
-    restart: always
-    depends_on:
-      - app
-    ports:
-      - 127.0.0.1:8002:8002
-    environment:
-      - NEXTCLOUD_HOST=http://app:80
-      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002
-      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
-      - NEXTCLOUD_OIDC_CLIENT_STORAGE=/app/.oauth-jwt/nextcloud_oauth_client.json
-      - NEXTCLOUD_OIDC_SCOPES=openid profile email nc:read nc:write
-      - NEXTCLOUD_OIDC_TOKEN_TYPE=jwt
-      # No USERNAME/PASSWORD - will use OAuth with Dynamic Client Registration (DCR)
-      # Client will be registered with token_type=JWT on first startup
-    volumes:
-      - oauth-jwt-client-storage:/app/.oauth-jwt
-
 volumes:
   nextcloud:
   db:
   oauth-client-storage:
-  oauth-jwt-client-storage:

docs/jwt-oauth-reference.md

@@ -28,18 +28,18 @@ The Nextcloud MCP Server supports OAuth authentication with both **JWT** (RFC 90
 ### Key Features
 
 - ✅ **JWT Token Support** - RFC 9068 compliant access tokens with RS256 signatures
-- ✅ **Custom Scopes** - `nc:read` and `nc:write` for read/write access control
+- ✅ **Custom Scopes** - `mcp:notes:read` and `mcp:notes:write` for read/write access control
 - ✅ **Dynamic Tool Filtering** - Tools filtered based on user's token scopes
 - ✅ **Scope Challenges** - RFC-compliant `WWW-Authenticate` headers for insufficient scopes
-- ✅ **Protected Resource Metadata** - RFC 8959 endpoint for scope discovery
+- ✅ **Protected Resource Metadata** - RFC 9728 endpoint for scope discovery
 - ✅ **Backward Compatible** - BasicAuth mode bypasses all scope checks
 
 ### Supported Scopes
 
 | Scope | Description | Tool Count |
 |-------|-------------|------------|
-| `nc:read` | Read-only access to Nextcloud data | 36 tools |
-| `nc:write` | Write access to create/modify/delete data | 54 tools |
+| `mcp:notes:read` | Read-only access to Nextcloud data | 36 tools |
+| `mcp:notes:write` | Write access to create/modify/delete data | 54 tools |
 
 All MCP tools (90 total) require at least one of these scopes. Standard OIDC scopes (`openid`, `profile`, `email`) are also supported.
 
@@ -75,7 +75,7 @@ The Nextcloud OIDC app supports two token formats, configured per-client:
     "aud": "client_id",
     "exp": 1234567890,
     "iat": 1234567890,
-    "scope": "openid profile email nc:read nc:write",
+    "scope": "openid profile email mcp:notes:read mcp:notes:write",
     "client_id": "...",
     "jti": "..."
   }
@@ -116,8 +116,8 @@ The MCP server uses **coarse-grained scopes** for simplicity:
 
 | Scope | Operations | Examples |
 |-------|------------|----------|
-| `nc:read` | Read-only access | Get notes, search files, list calendars, read contacts |
-| `nc:write` | Write operations | Create notes, update events, delete files, modify contacts |
+| `mcp:notes:read` | Read-only access | Get notes, search files, list calendars, read contacts |
+| `mcp:notes:write` | Write operations | Create notes, update events, delete files, modify contacts |
 
 ### Standard OIDC Scopes
 
@@ -131,12 +131,12 @@ The MCP server uses **coarse-grained scopes** for simplicity:
 
 **Full Access:**
 ```
-openid profile email nc:read nc:write
+openid profile email mcp:notes:read mcp:notes:write
 ```
 
 **Read-Only:**
 ```
-openid profile email nc:read
+openid profile email mcp:notes:read
 ```
 
 **No Custom Scopes (OIDC only):**
@@ -150,44 +150,46 @@ All 90 MCP tools are decorated with scope requirements:
 
 ```python
 @mcp.tool()
-@require_scopes("nc:read")
+@require_scopes("mcp:notes:read")
 async def nc_notes_get_note(note_id: int, ctx: Context):
-    """Get a note by ID (requires nc:read scope)"""
+    """Get a note by ID (requires mcp:notes:read scope)"""
     ...
 
 @mcp.tool()
-@require_scopes("nc:write")
+@require_scopes("mcp:notes:write")
 async def nc_notes_create_note(title: str, content: str, ctx: Context):
-    """Create a note (requires nc:write scope)"""
+    """Create a note (requires mcp:notes:write scope)"""
     ...
 ```
 
 **Coverage:**
-- ✅ 36 read tools decorated with `@require_scopes("nc:read")`
-- ✅ 54 write tools decorated with `@require_scopes("nc:write")`
+- ✅ 36 read tools decorated with `@require_scopes("mcp:notes:read")`
+- ✅ 54 write tools decorated with `@require_scopes("mcp:notes:write")`
 - ✅ 90/90 tools covered (100%)
 
 ### Dynamic Tool Filtering
 
-The MCP server implements **dynamic tool filtering** - users only see tools they have permission to use:
+The MCP server implements **dynamic tool filtering** - users only see tools they have permission to use. This applies to **both JWT and Bearer (opaque) tokens** in OAuth mode:
 
-**JWT with `nc:read` only:**
+**Token with `mcp:notes:read` only:**
 - `list_tools()` returns 36 read-only tools
 - Write tools are hidden from the tool list
 
-**JWT with `nc:write` only:**
+**Token with `mcp:notes:write` only:**
 - `list_tools()` returns 54 write-only tools
 - Read tools are hidden from the tool list
 
-**JWT with both scopes:**
+**Token with both scopes:**
 - `list_tools()` returns all 90 tools
 
-**JWT with no custom scopes:**
-- `list_tools()` returns 0 tools (all require `nc:read` or `nc:write`)
+**Token with no custom scopes:**
+- `list_tools()` returns 0 tools (all require `mcp:notes:read` or `mcp:notes:write`)
 
 **BasicAuth mode:**
 - `list_tools()` returns all 90 tools (no filtering)
 
+**Note:** JWT tokens include scopes in the token payload, while Bearer tokens retrieve scopes via the introspection endpoint. Both methods provide reliable scope information for filtering.
+
 ### Scope Challenges
 
 When a tool is called without required scopes, the server returns a `403 Forbidden` response with a `WWW-Authenticate` header:
@@ -195,23 +197,23 @@ When a tool is called without required scopes, the server returns a `403 Forbidd
 ```http
 HTTP/1.1 403 Forbidden
 WWW-Authenticate: Bearer error="insufficient_scope",
-                  scope="nc:write",
-                  resource_metadata="http://server/.well-known/oauth-protected-resource"
+                  scope="mcp:notes:write",
+                  resource_metadata="http://server/.well-known/oauth-protected-resource/mcp"
 ```
 
 This enables **step-up authorization** - clients can detect missing scopes and trigger re-authentication to obtain additional permissions.
 
 ### Protected Resource Metadata (PRM)
 
-The server implements RFC 8959's Protected Resource Metadata endpoint:
+The server implements RFC 9728's Protected Resource Metadata endpoint:
 
-**Endpoint:** `GET /.well-known/oauth-protected-resource`
+**Endpoint:** `GET /.well-known/oauth-protected-resource/mcp`
 
 **Response:**
 ```json
 {
-  "resource": "http://localhost:8002",
-  "scopes_supported": ["nc:read", "nc:write"],
+  "resource": "http://localhost:8001/mcp",
+  "scopes_supported": ["mcp:notes:read", "mcp:notes:write"],
   "authorization_servers": ["http://localhost:8080"],
   "bearer_methods_supported": ["header"],
   "resource_signing_alg_values_supported": ["RS256"]
@@ -226,55 +228,53 @@ This allows OAuth clients to discover supported scopes before requesting authori
 
 ### Docker Services
 
-The development environment includes three MCP server variants:
+The development environment includes two MCP server variants:
 
 | Service | Port | Auth Type | Token Type | Use Case |
 |---------|------|-----------|------------|----------|
 | `mcp` | 8000 | BasicAuth | N/A | Development, testing |
-| `mcp-oauth` | 8001 | OAuth | Opaque | Standard OAuth flows |
-| `mcp-oauth-jwt` | 8002 | OAuth | JWT | Production, JWT testing |
+| `mcp-oauth` | 8001 | OAuth | JWT (configurable) | OAuth testing with JWT tokens |
 
-### JWT Service Configuration
+### OAuth Service Configuration
 
-The `mcp-oauth-jwt` service uses **Dynamic Client Registration (DCR)** by default:
+The `mcp-oauth` service uses **Dynamic Client Registration (DCR)** by default and is configured to request JWT tokens:
 
-**Default Configuration (DCR):**
+**Default Configuration (DCR with JWT tokens):**
 ```yaml
-mcp-oauth-jwt:
+mcp-oauth:
   build: .
-  command: ["--transport", "streamable-http", "--oauth", "--port", "8002"]
+  command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
   ports:
-    - 127.0.0.1:8002:8002
+    - 127.0.0.1:8001:8001
   environment:
     - NEXTCLOUD_HOST=http://app:80
-    - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002
+    - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8001
     - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
-    - NEXTCLOUD_OIDC_SCOPES=openid profile email nc:read nc:write
-    - NEXTCLOUD_OIDC_TOKEN_TYPE=jwt
+    - NEXTCLOUD_OIDC_SCOPES=openid profile email mcp:notes:read mcp:notes:write
   volumes:
-    - ./oauth-storage:/app/.oauth  # Optional: persist DCR credentials
+    - oauth-client-storage:/app/.oauth  # Persist DCR credentials
 ```
 
 **With Pre-Configured Credentials:**
 ```yaml
-mcp-oauth-jwt:
+mcp-oauth:
   build: .
-  command: ["--transport", "streamable-http", "--oauth", "--port", "8002"]
+  command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
   ports:
-    - 127.0.0.1:8002:8002
+    - 127.0.0.1:8001:8001
   environment:
     - NEXTCLOUD_HOST=http://app:80
-    - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002
+    - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8001
     - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
     - NEXTCLOUD_OIDC_CLIENT_ID=<your_client_id>      # Skips DCR
     - NEXTCLOUD_OIDC_CLIENT_SECRET=<your_client_secret>  # Skips DCR
-    - NEXTCLOUD_OIDC_TOKEN_TYPE=jwt
 ```
 
 **Key Points:**
 - **No credentials needed** - DCR automatically registers the client on first start
 - **Credentials persist** - Saved to `.nextcloud_oauth_client.json` and reused
-- **JWT tokens** - Set `TOKEN_TYPE=jwt` for better performance
+- **JWT tokens** - Use `--oauth-token-type jwt` for better performance
+- **Token verifier supports both** - Can handle JWT and opaque tokens
 - **Pre-configured credentials** - Providing `CLIENT_ID`/`CLIENT_SECRET` skips DCR
 
 ### Environment Variables
@@ -287,7 +287,7 @@ mcp-oauth-jwt:
 | `NEXTCLOUD_OIDC_CLIENT_ID` | Pre-configured OAuth client ID | (optional - uses DCR if unset) |
 | `NEXTCLOUD_OIDC_CLIENT_SECRET` | Pre-configured OAuth client secret | (optional - uses DCR if unset) |
 | `NEXTCLOUD_OIDC_CLIENT_STORAGE` | Path to persist DCR-registered credentials | `.nextcloud_oauth_client.json` |
-| `NEXTCLOUD_OIDC_SCOPES` | Space-separated scopes to request | `"openid profile email nc:read nc:write"` |
+| `NEXTCLOUD_OIDC_SCOPES` | Space-separated scopes to request | `"openid profile email mcp:notes:read mcp:notes:write"` |
 | `NEXTCLOUD_OIDC_TOKEN_TYPE` | Token format: `"jwt"` or `"Bearer"` | `"Bearer"` |
 
 ### Dynamic Client Registration (DCR)
@@ -321,7 +321,7 @@ DCR automatically configures the client based on environment variables:
 # Minimal DCR configuration (no credentials needed!)
 export NEXTCLOUD_HOST=http://localhost:8080
 export NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
-export NEXTCLOUD_OIDC_SCOPES="openid profile email nc:read nc:write"
+export NEXTCLOUD_OIDC_SCOPES="openid profile email mcp:notes:read mcp:notes:write"
 export NEXTCLOUD_OIDC_TOKEN_TYPE=jwt  # or "Bearer" for opaque tokens
 ```
 
@@ -363,7 +363,7 @@ Manual client creation is **optional** but may be preferred when:
 ```bash
 docker compose exec app php occ oidc:create \
   --token_type=jwt \
-  --allowed_scopes="openid profile email nc:read nc:write" \
+  --allowed_scopes="openid profile email mcp:notes:read mcp:notes:write" \
   "Nextcloud MCP Server" \
   "http://localhost:8000/oauth/callback"
 ```
@@ -374,7 +374,7 @@ docker compose exec app php occ oidc:create \
   "client_id": "XBd2xqIisu3Kswg39Ub4BUhC36PEYjwwivx3G5nZdDgigvwKXrTHozs7m9DeoLSY",
   "client_secret": "xNKcy0qpUSau36T60pGGdb03pMEVLXtqykxjK8YkDpoNxNcZ4ClyAT3IAEse2AKT",
   "token_type": "jwt",
-  "allowed_scopes": "openid profile email nc:read nc:write"
+  "allowed_scopes": "openid profile email mcp:notes:read mcp:notes:write"
 }
 ```
 
@@ -407,7 +407,7 @@ When credentials are provided via environment variables or storage file, **DCR i
          │                                          │
          │ JWT Access Token                         │
          │ {                                        │
-         │   "scope": "openid nc:read nc:write"    │
+         │   "scope": "openid mcp:notes:read mcp:notes:write"    │
          │   ...                                    │
          │ }                                        │
          │                                          │
@@ -456,16 +456,16 @@ When credentials are provided via environment variables or storage file, **DCR i
 - `has_required_scopes()` - Check if user has necessary scopes
 - `InsufficientScopeError` exception for WWW-Authenticate challenges
 
-**3. Dynamic Filtering** (`nextcloud_mcp_server/app.py:433-488`)
+**3. Dynamic Filtering** (`nextcloud_mcp_server/app.py:473-516`)
 - Overrides FastMCP's `list_tools()` method
-- Filters based on user's JWT token scopes
+- Filters based on user's OAuth token scopes (JWT and Bearer)
 - Only active in OAuth mode
 - Bypassed in BasicAuth mode
 
 **4. PRM Endpoint** (`nextcloud_mcp_server/app.py:503-532`)
-- `GET /.well-known/oauth-protected-resource`
-- Advertises `["nc:read", "nc:write"]`
-- RFC 8959 compliant
+- `GET /.well-known/oauth-protected-resource/mcp`
+- Advertises `["mcp:notes:read", "mcp:notes:write"]`
+- RFC 9728 compliant
 
 **5. Exception Handler** (`nextcloud_mcp_server/app.py:540-563`)
 - Catches `InsufficientScopeError`
@@ -500,7 +500,7 @@ The `NextcloudTokenVerifier` implements a **cascading validation strategy** that
                          │    ├─ Authenticate with client credentials
                          │    ├─ Response contains:
                          │    │   • active: true/false
-                         │    │   • scope: "openid nc:read nc:write"
+                         │    │   • scope: "openid mcp:notes:read mcp:notes:write"
                          │    │   • sub, exp, iat, client_id
                          │    ├─ Extract scopes from response
                          │    └─ Success: Return AccessToken
@@ -554,7 +554,7 @@ uv run pytest tests/server/test_scope_authorization.py::test_jwt_with_no_custom_
 ```
 
 **Scenario:** JWT token with only OIDC defaults (`openid profile email`)
-**Expected:** 0 tools returned (all require `nc:read` or `nc:write`)
+**Expected:** 0 tools returned (all require `mcp:notes:read` or `mcp:notes:write`)
 **Verifies:** Security - users who decline custom scopes cannot access any MCP tools
 
 #### 2. Read-Only Access (36 tools)
@@ -562,7 +562,7 @@ uv run pytest tests/server/test_scope_authorization.py::test_jwt_with_no_custom_
 uv run pytest tests/server/test_scope_authorization.py::test_jwt_consent_scenarios_read_only -v
 ```
 
-**Scenario:** JWT token with `nc:read` only
+**Scenario:** JWT token with `mcp:notes:read` only
 **Expected:** 36 read-only tools visible, write tools hidden
 **Verifies:** Read tools accessible, write tools filtered out
 
@@ -571,7 +571,7 @@ uv run pytest tests/server/test_scope_authorization.py::test_jwt_consent_scenari
 uv run pytest tests/server/test_scope_authorization.py::test_jwt_consent_scenarios_write_only -v
 ```
 
-**Scenario:** JWT token with `nc:write` only
+**Scenario:** JWT token with `mcp:notes:write` only
 **Expected:** 54 write tools visible, read tools hidden
 **Verifies:** Write tools accessible, read tools filtered out
 
@@ -580,21 +580,21 @@ uv run pytest tests/server/test_scope_authorization.py::test_jwt_consent_scenari
 uv run pytest tests/server/test_scope_authorization.py::test_jwt_consent_scenarios_full_access -v
 ```
 
-**Scenario:** JWT token with both `nc:read` and `nc:write`
+**Scenario:** JWT token with both `mcp:notes:read` and `mcp:notes:write`
 **Expected:** All 90 tools visible
 **Verifies:** Full access when user grants all custom scopes
 
 ### Test Fixtures
 
 **OAuth Client Fixtures:**
-- `read_only_oauth_client_credentials` - Client with `nc:read` only
-- `write_only_oauth_client_credentials` - Client with `nc:write` only
+- `read_only_oauth_client_credentials` - Client with `mcp:notes:read` only
+- `write_only_oauth_client_credentials` - Client with `mcp:notes:write` only
 - `full_access_oauth_client_credentials` - Client with both scopes
 - `no_custom_scopes_oauth_client_credentials` - Client with OIDC defaults only
 
 **Token Fixtures:**
-- `playwright_oauth_token_read_only` - Obtains token with `nc:read`
-- `playwright_oauth_token_write_only` - Obtains token with `nc:write`
+- `playwright_oauth_token_read_only` - Obtains token with `mcp:notes:read`
+- `playwright_oauth_token_write_only` - Obtains token with `mcp:notes:write`
 - `playwright_oauth_token_full_access` - Obtains token with both scopes
 - `playwright_oauth_token_no_custom_scopes` - Obtains token with no custom scopes
 
@@ -682,26 +682,26 @@ docker compose exec app php occ oidc:list
 # If empty, recreate client with --allowed_scopes
 docker compose exec app php occ oidc:create \
   --token_type=jwt \
-  --allowed_scopes="openid profile email nc:read nc:write" \
+  --allowed_scopes="openid profile email mcp:notes:read mcp:notes:write" \
   "Client Name" \
   "http://callback/url"
 ```
 
 ### Issue: All Tools Visible Despite Read-Only Token
 
-**Symptom:** User with `nc:read` token can see all 90 tools including write tools
+**Symptom:** User with `mcp:notes:read` token can see all 90 tools including write tools
 
 **Cause:** Server running in BasicAuth mode, not OAuth mode
 
 **Solution:**
 ```bash
 # Verify OAuth mode is active
-docker compose logs mcp-oauth-jwt | grep "OAuth mode"
+docker compose logs mcp-oauth | grep "OAuth mode"
 
 # Should see: "Running in OAuth mode"
 
 # If not, check environment variables:
-docker compose exec mcp-oauth-jwt env | grep NEXTCLOUD_OIDC
+docker compose exec mcp-oauth env | grep NEXTCLOUD_OIDC
 
 # Ensure no NEXTCLOUD_USERNAME or NEXTCLOUD_PASSWORD set
 ```
@@ -717,7 +717,7 @@ DCR **now properly sets `allowed_scopes`** when the `scope` parameter is provide
 docker compose exec db mariadb -u nextcloud -ppassword nextcloud \
   -e "SELECT name, allowed_scopes FROM oc_oauth2_clients WHERE name LIKE 'DCR-%' ORDER BY id DESC LIMIT 1;"
 
-# Should show your requested scopes (e.g., "openid profile email nc:read nc:write")
+# Should show your requested scopes (e.g., "openid profile email mcp:notes:read mcp:notes:write")
 ```
 
 **If scopes are missing:**
@@ -750,12 +750,12 @@ export NEXTCLOUD_OIDC_TOKEN_TYPE=JWT
 **Solution:**
 ```bash
 # Check server logs for OAuth mode
-docker compose logs mcp-oauth-jwt | grep "WWW-Authenticate scope challenges enabled"
+docker compose logs mcp-oauth | grep "WWW-Authenticate scope challenges enabled"
 
 # Should see this during startup
 
 # Check exception handling
-docker compose logs mcp-oauth-jwt | grep "InsufficientScopeError"
+docker compose logs mcp-oauth | grep "InsufficientScopeError"
 ```
 
 ### Debugging Tools
@@ -780,10 +780,10 @@ docker compose exec db mariadb -u nextcloud -ppassword nextcloud \
 **Check server logs:**
 ```bash
 # Follow JWT verification logs
-docker compose logs -f mcp-oauth-jwt | grep -E "JWT|scope|tool"
+docker compose logs -f mcp-oauth | grep -E "JWT|scope|tool"
 
 # Check for issuer mismatches
-docker compose logs mcp-oauth-jwt | grep -i issuer
+docker compose logs mcp-oauth | grep -i issuer
 ```
 
 ---
@@ -804,18 +804,18 @@ docker compose logs mcp-oauth-jwt | grep -i issuer
 
 ```yaml
 # docker-compose.yml (production)
-mcp-oauth-jwt:
+mcp-oauth:
   image: ghcr.io/yourusername/nextcloud-mcp-server:latest
+  command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
   environment:
     - NEXTCLOUD_HOST=https://nextcloud.example.com
     - NEXTCLOUD_MCP_SERVER_URL=https://mcp.example.com
     - NEXTCLOUD_PUBLIC_ISSUER_URL=https://nextcloud.example.com
     - NEXTCLOUD_OIDC_CLIENT_ID=${JWT_CLIENT_ID}
     - NEXTCLOUD_OIDC_CLIENT_SECRET=${JWT_CLIENT_SECRET}
-    - NEXTCLOUD_OIDC_SCOPES=openid profile email nc:read nc:write
-    - NEXTCLOUD_OIDC_TOKEN_TYPE=jwt
+    - NEXTCLOUD_OIDC_SCOPES=openid profile email mcp:notes:read mcp:notes:write
   ports:
-    - "8002:8002"
+    - "8001:8001"
 ```
 
 ### Security Considerations
@@ -847,16 +847,16 @@ mcp-oauth-jwt:
 ```bash
 # Success
 INFO JWT verified successfully for user: admin
-INFO ✅ Extracted scopes from access token: {'openid', 'profile', 'email', 'nc:read', 'nc:write'}
+INFO ✅ Extracted scopes from access token: {'openid', 'profile', 'email', 'mcp:notes:read', 'mcp:notes:write'}
 
 # Failures
 WARNING JWT issuer validation failed: Invalid issuer
-WARNING Missing required scopes: nc:write
+WARNING Missing required scopes: mcp:notes:write
 ```
 
 ### Known Limitations
 
-1. **No Fine-Grained Scopes** - Only coarse `nc:read` and `nc:write` (not per-app scopes)
+1. **No Fine-Grained Scopes** - Only coarse `mcp:notes:read` and `mcp:notes:write` (not per-app scopes)
 2. **No Refresh Token Support** - Tokens must be reacquired when expired
 
 ### Future Enhancements
@@ -876,7 +876,7 @@ WARNING Missing required scopes: nc:write
 - [RFC 9068: JWT Profile for OAuth 2.0 Access Tokens](https://www.rfc-editor.org/rfc/rfc9068.html)
 - [RFC 7519: JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519.html)
 - [RFC 7517: JSON Web Key (JWK)](https://www.rfc-editor.org/rfc/rfc7517.html)
-- [RFC 8959: Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc8959.html)
+- [RFC 9728: OAuth 2.0 Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728.html)
 - [RFC 7662: OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662.html)
 
 ### Related Documentation

docs/oauth-architecture.md

@@ -8,166 +8,463 @@ The Nextcloud MCP Server acts as an **OAuth 2.0 Resource Server**, protecting ac
 
 ## Architecture Diagram
 
+The complete OAuth flow includes server startup (with DCR), client discovery (with PRM), authorization (with PKCE), and API access phases:
+
 ```
+═══════════════════════════════════════════════════════════════════════════════════
+Phase 0: MCP Server Startup & Client Registration (DCR - RFC 7591)
+═══════════════════════════════════════════════════════════════════════════════════
+
+                                 ┌──────────────────┐                  ┌─────────────────┐
+                                 │   MCP Server     │                  │   Nextcloud     │
+                                 │   (Resource      │                  │  (OIDC Provider)│
+                                 │    Server)       │                  │                 │
+                                 └────────┬─────────┘                  └────────┬────────┘
+                                          │                                     │
+                                          │  0a. OIDC Discovery                 │
+                                          ├────────────────────────────────────>│
+                                          │  GET                                │
+                                          |  /.well-known/openid-configuration  │
+                                          │                                     │
+                                          │  0b. Discovery response             │
+                                          │<────────────────────────────────────┤
+                                          │  {issuer, endpoints, PKCE methods}  │
+                                          │                                     │
+                                          │  0c. Register OAuth client (DCR)    │
+                                          ├────────────────────────────────────>│
+                                          │  POST /apps/oidc/register           │
+                                          │  {client_name, redirect_uris,       │
+                                          │   scopes, token_type}               │
+                                          │                                     │
+                                          │  0d. Client credentials             │
+                                          │<────────────────────────────────────┤
+                                          │  {client_id, client_secret}         │
+                                          │  → Saved to .nextcloud_oauth_*.json │
+                                          │                                     │
+                                          │  ✓ Server ready for connections     │
+
+
+═══════════════════════════════════════════════════════════════════════════════════
+Phase 1: Client Connection & Discovery (PRM - RFC 9728)
+═══════════════════════════════════════════════════════════════════════════════════
+
 ┌─────────────┐                  ┌──────────────────┐                  ┌─────────────────┐
-│             │                  │                  │                  │                 │
-│ MCP Client  │                  │   MCP Server     │                  │   Nextcloud     │
-│ (Claude,    │                  │   (Resource      │                  │   Instance      │
-│  etc.)      │                  │    Server)       │                  │                 │
+│             │                  │   MCP Server     │                  │   Nextcloud     │
+│ MCP Client  │                  │   (Resource      │                  │   Instance      │
+│ (Claude)    │                  │    Server)       │                  │                 │
 │             │                  │                  │                  │                 │
 └──────┬──────┘                  └────────┬─────────┘                  └────────┬────────┘
        │                                  │                                     │
-       │                                  │                                     │
-       │  1. Connect to MCP               │                                     │
+       │  1a. Connect to MCP              │                                     │
        ├─────────────────────────────────>│                                     │
        │                                  │                                     │
-       │  2. Return auth settings         │                                     │
-       │     (issuer_url, scopes)         │                                     │
+       │  1b. Return auth settings        │                                     │
        │<─────────────────────────────────┤                                     │
+       │  {issuer_url, resource_url}      │                                     │
        │                                  │                                     │
-       │                                  │                                     │
-       │  3. Start OAuth flow (with PKCE) │                                     │
-       ├──────────────────────────────────┼────────────────────────────────────>│
-       │                                  │   /apps/oidc/authorize              │
-       │                                  │                                     │
-       │  4. User authenticates in browser│                                     │
-       │<─────────────────────────────────┼─────────────────────────────────────┤
-       │                                  │                                     │
-       │  5. Authorization code (redirect)│                                     │
-       │<─────────────────────────────────┤                                     │
-       │                                  │                                     │
-       │  6. Exchange code for token      │                                     │
-       ├──────────────────────────────────┼────────────────────────────────────>│
-       │                                  │   /apps/oidc/token                  │
-       │                                  │                                     │
-       │  7. Access token                 │                                     │
-       │<─────────────────────────────────┼─────────────────────────────────────┤
-       │                                  │                                     │
-       │                                  │                                     │
-       │  8. API request with Bearer token│                                     │
+       │  1c. PRM Discovery (RFC 9728)    │                                     │
        ├─────────────────────────────────>│                                     │
-       │     Authorization: Bearer xxx    │                                     │
+       │  GET /.well-known/oauth-         │                                     │
+       │      protected-resource/mcp      │                                     │
        │                                  │                                     │
-       │                                  │  9. Validate token via userinfo     │
-       │                                  ├────────────────────────────────────>│
-       │                                  │     /apps/oidc/userinfo             │
-       │                                  │                                     │
-       │                                  │  10. User info (token valid)        │
-       │                                  │<────────────────────────────────────┤
-       │                                  │                                     │
-       │                                  │  11. Nextcloud API request          │
-       │                                  ├────────────────────────────────────>│
-       │                                  │     Authorization: Bearer xxx       │
-       │                                  │     (Notes, Calendar, etc.)         │
-       │                                  │                                     │
-       │                                  │  12. API response                   │
-       │                                  │<────────────────────────────────────┤
-       │                                  │                                     │
-       │  13. MCP tool response           │                                     │
+       │  1d. PRM response (scopes!)      │                                     │
        │<─────────────────────────────────┤                                     │
+       │  {resource, scopes_supported,    │  ← Dynamically discovered from      │
+       │   authorization_servers}         │    @require_scopes decorators       │
+       │                                  │                                     │
+
+
+═══════════════════════════════════════════════════════════════════════════════════
+Phase 2: OAuth Authorization Flow (PKCE - RFC 7636)
+═══════════════════════════════════════════════════════════════════════════════════
+
+       │                                  │                                     │
+       │  2a. Generate PKCE challenge     │                                     │
+       │  code_verifier = random(43-128)  │                                     │
+       │  code_challenge = SHA256(verif.) │                                     │
+       │                                  │                                     │
+       │  2b. Authorization request       │                                     │
+       ├──────────────────────────────────┼────────────────────────────────────>│
+       │  /apps/oidc/authorize?           │                                     │
+       │    client_id=xxx                 │                                     │
+       │    &code_challenge=abc...        │                                     │
+       │    &code_challenge_method=S256   │                                     │
+       │    &scope=openid notes:read ...  │                                     │
+       │                                  │                                     │
+       │  2c. User consent page           │                                     │
+       │<─────────────────────────────────┼─────────────────────────────────────┤
+       │  (Browser: Select scopes)        │                                     │
+       │                                  │                                     │
+       │  2d. User grants scopes          │                                     │
+       ├──────────────────────────────────┼────────────────────────────────────>│
+       │                                  │                                     │
+       │  2e. Authorization code redirect │                                     │
+       │<─────────────────────────────────┼─────────────────────────────────────┤
+       │  callback?code=xyz123            │                                     │
+       │                                  │                                     │
+       │  2f. Exchange code for token     │                                     │
+       ├──────────────────────────────────┼────────────────────────────────────>│
+       │  POST /apps/oidc/token           │                                     │
+       │  {code, code_verifier,           │  ← Validates PKCE challenge         │
+       │   client_id, client_secret}      │                                     │
+       │                                  │                                     │
+       │  2g. Access token (JWT/opaque)   │                                     │
+       │<─────────────────────────────────┼─────────────────────────────────────┤
+       │  {access_token, token_type,      │                                     │
+       │   scope: "openid notes:read...") │  ← User's granted scopes            │
+       │                                  │                                     │
+
+
+═══════════════════════════════════════════════════════════════════════════════════
+Phase 3: MCP Tool Access (Scope-based Authorization)
+═══════════════════════════════════════════════════════════════════════════════════
+
+       │                                  │                                     │
+       │  3a. list_tools request          │                                     │
+       ├─────────────────────────────────>│                                     │
+       │  Authorization: Bearer <token>   │                                     │
+       │                                  │                                     │
+       │                                  │  3b. Validate token                 │
+       │                                  ├────────────────────────────────────>│
+       │                                  │  GET /apps/oidc/userinfo            │
+       │                                  │  Authorization: Bearer <token>      │
+       │                                  │                                     │
+       │                                  │  3c. Token valid + scopes           │
+       │                                  │<────────────────────────────────────┤
+       │                                  │  {sub, scopes, ...}                 │
+       │                                  │  ← Cached for 1 hour                │
+       │                                  │                                     │
+       │  3d. Filtered tool list          │                                     │
+       │<─────────────────────────────────┤  ← Only tools matching user's       │
+       │  [tools matching token scopes]   │    token scopes (via @require_scopes)
+       │                                  │                                     │
+       │  3e. Call tool                   │                                     │
+       ├─────────────────────────────────>│                                     │
+       │  nc_notes_get_note(note_id=1)    │  ← @require_scopes("notes:read")    │
+       │  Authorization: Bearer <token>   │                                     │
+       │                                  │                                     │
+       │                                  │  3f. Scope check PASSED             │
+       │                                  │  ✓ Token has notes:read             │
+       │                                  │                                     │
+       │                                  │  3g. Nextcloud API call             │
+       │                                  ├────────────────────────────────────>│
+       │                                  │  GET /apps/notes/api/v1/notes/1     │
+       │                                  │  Authorization: Bearer <token>      │
+       │                                  │  ← user_oidc validates Bearer token │
+       │                                  │                                     │
+       │                                  │  3h. API response                   │
+       │                                  │<────────────────────────────────────┤
+       │                                  │  {id: 1, title: "Note", ...}        │
+       │                                  │                                     │
+       │  3i. MCP tool response           │                                     │
+       │<─────────────────────────────────┤                                     │
+       │  {note data}                     │                                     │
+       │                                  │                                     │
+
+
+═══════════════════════════════════════════════════════════════════════════════════
+Insufficient Scope Example (Step-Up Authorization)
+═══════════════════════════════════════════════════════════════════════════════════
+
+       │  4a. Call write tool             │                                     │
+       ├─────────────────────────────────>│                                     │
+       │  nc_notes_create_note(...)       │  ← @require_scopes("notes:write")   │
+       │  Authorization: Bearer <token>   │                                     │
+       │                                  │                                     │
+       │                                  │  4b. Scope check FAILED             │
+       │                                  │  ✗ Token only has notes:read        │
+       │                                  │                                     │
+       │  4c. 403 Insufficient Scope      │                                     │
+       │<─────────────────────────────────┤                                     │
+       │  WWW-Authenticate: Bearer        │                                     │
+       │    error="insufficient_scope",   │                                     │
+       │    scope="notes:write",          │                                     │
+       │    resource_metadata="..."       │                                     │
+       │                                  │                                     │
+       │  → Client can re-authorize with  │                                     │
+       │    additional scopes (Step-Up)   │                                     │
        │                                  │                                     │
 ```
 
 ## Components
 
-### 1. MCP Client
-- Any MCP-compatible client (Claude Desktop, Claude Code, custom clients)
+### 1. MCP Client (e.g., Claude Desktop, Claude Code)
+
+**Capabilities**:
+- Discovers OAuth configuration via MCP server
+- Queries PRM endpoint for supported scopes
 - Initiates OAuth flow with PKCE (Proof Key for Code Exchange)
 - Stores and sends access token with each request
-- **Example**: Claude Desktop, Claude Code
+- Handles scope-based tool filtering
+- Supports step-up authorization (re-auth for additional scopes)
 
-### 2. MCP Server (Resource Server)
-- **Role**: OAuth 2.0 Resource Server
-- **Location**: This Nextcloud MCP Server implementation
-- **Responsibilities**:
-  - Validates Bearer tokens by calling Nextcloud's userinfo endpoint
-  - Caches validated tokens (default: 1 hour TTL)
-  - Creates authenticated Nextcloud client instances per-user
-  - Enforces PKCE requirements (S256 code challenge method)
-  - Exposes Nextcloud functionality via MCP tools
+**Examples**: Claude Desktop, Claude Code, MCP Inspector, custom MCP clients
+
+### 2. MCP Server (Resource Server - This Implementation)
+
+**Role**: OAuth 2.0 Resource Server (RFC 6749)
+
+**Responsibilities**:
+
+#### Startup Phase
+- **OIDC Discovery**: Queries `/.well-known/openid-configuration` for OAuth endpoints
+- **PKCE Validation**: Verifies server advertises S256 code challenge method
+- **Dynamic Client Registration (DCR)**: Automatically registers OAuth client via `/apps/oidc/register` (RFC 7591)
+  - Or loads pre-configured client credentials
+  - Saves credentials to `.nextcloud_oauth_client.json`
+- **Tool Registration**: Loads all MCP tools with their `@require_scopes` decorators
+
+#### Client Connection Phase
+- **Auth Settings**: Returns OAuth issuer URL and resource URL
+- **PRM Endpoint**: Exposes `/.well-known/oauth-protected-resource/mcp` (RFC 9728)
+  - Dynamically discovers scopes from all registered tools
+  - Returns `scopes_supported` list based on `@require_scopes` decorators
+
+#### Request Processing Phase
+- **Token Validation**: Validates Bearer tokens via Nextcloud userinfo endpoint
+  - Supports both JWT and opaque tokens
+  - Caches validation results (1-hour TTL)
+  - Extracts user identity and granted scopes
+- **Scope Enforcement**:
+  - Filters `list_tools` based on user's token scopes
+  - Validates scopes before executing each tool
+  - Returns 403 with `WWW-Authenticate` header for insufficient scopes
+- **Per-User Clients**: Creates authenticated `NextcloudClient` instance per user
+  - Uses Bearer token for all Nextcloud API requests
+  - User-specific permissions and audit trails
 
 **Key Files**:
-- [`app.py`](../nextcloud_mcp_server/app.py) - OAuth mode detection and configuration
-- [`auth/token_verifier.py`](../nextcloud_mcp_server/auth/token_verifier.py) - Token validation logic
+- [`app.py`](../nextcloud_mcp_server/app.py) - OAuth mode, DCR, PRM endpoint
+- [`auth/token_verifier.py`](../nextcloud_mcp_server/auth/token_verifier.py) - Token validation (userinfo + introspection + JWT)
 - [`auth/context_helper.py`](../nextcloud_mcp_server/auth/context_helper.py) - Per-user client creation
+- [`auth/scope_authorization.py`](../nextcloud_mcp_server/auth/scope_authorization.py) - `@require_scopes` decorator, scope discovery
+- [`auth/client_registration.py`](../nextcloud_mcp_server/auth/client_registration.py) - DCR implementation (RFC 7591)
 
 ### 3. Nextcloud OIDC Apps
 
 #### a) `oidc` - OIDC Identity Provider
-- **Role**: OAuth 2.0 Authorization Server
-- **Location**: Nextcloud app (`apps/oidc`)
-- **Endpoints**:
-  - `/.well-known/openid-configuration` - Discovery endpoint
-  - `/apps/oidc/authorize` - Authorization endpoint
-  - `/apps/oidc/token` - Token endpoint
-  - `/apps/oidc/userinfo` - User info endpoint (token validation)
-  - `/apps/oidc/jwks` - JSON Web Key Set
-  - `/apps/oidc/register` - Dynamic client registration
+
+**Role**: OAuth 2.0 Authorization Server + OIDC Provider
+
+**Location**: Nextcloud app (`apps/oidc`)
+
+**Endpoints**:
+- `/.well-known/openid-configuration` - OIDC Discovery (RFC 8414)
+- `/apps/oidc/authorize` - Authorization endpoint (OAuth 2.0 + PKCE)
+- `/apps/oidc/token` - Token endpoint (issues JWT or opaque tokens)
+- `/apps/oidc/userinfo` - UserInfo endpoint (OIDC Core, used for token validation)
+- `/apps/oidc/jwks` - JSON Web Key Set (for JWT signature verification)
+- `/apps/oidc/register` - Dynamic Client Registration endpoint (RFC 7591)
+- `/apps/oidc/introspect` - Token Introspection endpoint (RFC 7662, optional)
+
+**Token Types**:
+- **JWT tokens**: Self-contained tokens with embedded scopes, validated via JWKS or userinfo
+- **Opaque tokens**: Random strings, validated via userinfo or introspection endpoint
 
 **Configuration**:
 ```bash
-# Enable dynamic client registration (optional)
-# Settings → OIDC → "Allow dynamic client registration"
+# Enable dynamic client registration (recommended for development)
+# Nextcloud Admin → Settings → OIDC → "Allow dynamic client registration"
+
+# Enable token introspection (optional, for opaque token validation)
+# Nextcloud Admin → Settings → OIDC → "Enable token introspection"
 ```
 
 #### b) `user_oidc` - OpenID Connect User Backend
-- **Role**: Bearer token validation middleware
-- **Location**: Nextcloud app (`apps/user_oidc`)
-- **Responsibilities**:
-  - Validates Bearer tokens for Nextcloud API requests
-  - Creates user sessions from valid Bearer tokens
-  - Integrates with Nextcloud's authentication system
+
+**Role**: Bearer token validation middleware for Nextcloud APIs
+
+**Location**: Nextcloud app (`apps/user_oidc`)
+
+**Responsibilities**:
+- Intercepts Nextcloud API requests with `Authorization: Bearer` header
+- Validates tokens against OIDC provider (`oidc` app)
+- Creates authenticated user sessions
+- Enforces user-specific permissions on API requests
 
 **Configuration**:
 ```bash
-# Enable Bearer token validation (required)
+# Enable Bearer token validation (required for OAuth mode)
 php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
 ```
 
 > [!IMPORTANT]
-> The `user_oidc` app requires a patch to properly support Bearer token authentication for non-OCS endpoints. See [Upstream Status](oauth-upstream-status.md) for details.
+> The `user_oidc` app requires a patch to properly support Bearer token authentication for non-OCS endpoints (like Notes API, Calendar API). See [Upstream Status](oauth-upstream-status.md) for patch details and PR status.
 
 ### 4. Nextcloud Instance
-- **Role**: Resource Owner / API Provider
-- **Provides**: Notes, Calendar, Contacts, Deck, Files, etc.
+
+**Role**: Resource Owner + API Provider
+
+**APIs Exposed**:
+- **Notes API**: `/apps/notes/api/v1/` - Note CRUD operations
+- **Calendar (CalDAV)**: `/remote.php/dav/calendars/` - Events and todos
+- **Contacts (CardDAV)**: `/remote.php/dav/addressbooks/` - Contact management
+- **Cookbook API**: `/apps/cookbook/api/v1/` - Recipe management
+- **Deck API**: `/apps/deck/api/v1.0/` - Kanban boards
+- **Tables API**: `/apps/tables/api/2/` - Table row operations
+- **WebDAV (Files)**: `/remote.php/dav/files/` - File operations
+- **Sharing API**: `/ocs/v2.php/apps/files_sharing/api/v1/` - Share management
 
 ## Authentication Flow
 
-### Phase 1: OAuth Authorization (Steps 1-7)
+The OAuth flow consists of four distinct phases (see diagram above for visual representation):
 
-1. **Client Connects**: MCP client connects to MCP server
-2. **Auth Settings**: MCP server returns OAuth settings:
-   ```json
-   {
-     "issuer_url": "https://nextcloud.example.com",
-     "resource_server_url": "http://localhost:8000",
-     "required_scopes": ["openid", "profile"]
-   }
-   ```
-3. **OAuth Flow**: Client initiates OAuth flow with PKCE
-   - Generates `code_verifier` (random string)
-   - Calculates `code_challenge` = SHA256(code_verifier)
-   - Redirects user to `/apps/oidc/authorize` with `code_challenge`
-4. **User Authentication**: User logs in to Nextcloud via browser
-5. **Authorization Code**: Nextcloud redirects back with authorization code
-6. **Token Exchange**: Client exchanges code for access token
-   - Sends `code` + `code_verifier` to `/apps/oidc/token`
-   - OIDC app validates PKCE challenge
-7. **Access Token**: Client receives access token (JWT or opaque)
+### Phase 0: MCP Server Startup (One-time Setup)
 
-### Phase 2: API Access (Steps 8-13)
+**Happens**: On MCP server first startup
 
-8. **API Request**: Client sends MCP request with Bearer token
-9. **Token Validation**: MCP server validates token:
-   - Checks cache (1-hour TTL by default)
-   - If not cached, calls `/apps/oidc/userinfo` with Bearer token
-   - Extracts username from `sub` or `preferred_username` claim
-10. **User Info**: Nextcloud returns user info if token is valid
-11. **Nextcloud API Call**: MCP server calls Nextcloud API on behalf of user
-    - Creates `NextcloudClient` instance with Bearer token
-    - User-specific permissions apply
-12. **API Response**: Nextcloud returns data
-13. **MCP Response**: MCP server returns formatted response to client
+**Steps**:
+1. **OIDC Discovery** (`GET /.well-known/openid-configuration`)
+   - MCP server queries Nextcloud for OAuth endpoints
+   - Validates PKCE support (requires `S256` code challenge method)
+   - Extracts endpoints: authorize, token, userinfo, jwks, register
+
+2. **Dynamic Client Registration** (`POST /apps/oidc/register`)
+   - If no pre-configured client credentials exist
+   - MCP server registers itself as OAuth client (RFC 7591)
+   - Provides: client name, redirect URIs, requested scopes, token type
+   - Receives: `client_id`, `client_secret`
+   - Saves credentials to `.nextcloud_oauth_client.json`
+
+3. **Tool Registration**
+   - All MCP tools loaded with their `@require_scopes` decorators
+   - Scope metadata stored for later discovery
+
+**Result**: MCP server ready to accept client connections
+
+### Phase 1: Client Discovery (Per MCP Client Connection)
+
+**Happens**: When MCP client first connects
+
+**Steps**:
+1. **MCP Connection**
+   - Client connects to MCP server
+   - Server returns OAuth auth settings (issuer URL, resource URL)
+
+2. **PRM Discovery** (`GET /.well-known/oauth-protected-resource/mcp`)
+   - Client queries Protected Resource Metadata endpoint (RFC 9728)
+   - Server **dynamically discovers** scopes from all registered tools
+   - Returns: resource URL, `scopes_supported` list, authorization servers
+   - Client now knows which scopes are available
+
+**Result**: Client knows OAuth configuration and available scopes
+
+### Phase 2: OAuth Authorization (PKCE Flow - RFC 7636)
+
+**Happens**: User authorizes access
+
+**Steps**:
+1. **PKCE Challenge Generation** (Client-side)
+   - Generate `code_verifier`: random 43-128 character string
+   - Calculate `code_challenge`: `BASE64URL(SHA256(code_verifier))`
+
+2. **Authorization Request** (`GET /apps/oidc/authorize`)
+   - Client redirects user to Nextcloud consent page
+   - Parameters:
+     - `client_id`: OAuth client ID
+     - `code_challenge`: SHA256 hash of verifier
+     - `code_challenge_method`: `S256`
+     - `scope`: Requested scopes (e.g., `openid notes:read notes:write`)
+     - `redirect_uri`: MCP server callback URL
+
+3. **User Consent**
+   - User authenticates to Nextcloud (if not already logged in)
+   - User reviews and approves/denies requested scopes
+   - Can select subset of requested scopes
+
+4. **Authorization Code**
+   - Nextcloud redirects to `callback?code=xyz123`
+   - Code is bound to PKCE challenge
+
+5. **Token Exchange** (`POST /apps/oidc/token`)
+   - Client sends:
+     - Authorization `code`
+     - `code_verifier` (proves possession of original challenge)
+     - `client_id` and `client_secret`
+   - Nextcloud validates PKCE challenge: `SHA256(code_verifier) == code_challenge`
+   - Nextcloud issues access token
+
+6. **Access Token Response**
+   - Token type: JWT or opaque (configurable)
+   - Contains user's **granted scopes** (may be subset of requested)
+   - Client stores token for subsequent requests
+
+**Result**: Client has valid access token with granted scopes
+
+### Phase 3: MCP Tool Access (Scope-Based Authorization)
+
+**Happens**: Every MCP tool invocation
+
+**Steps**:
+
+#### Tool Listing (`list_tools`)
+1. **List Tools Request**
+   - Client sends `list_tools` with `Authorization: Bearer <token>`
+
+2. **Token Validation**
+   - MCP server calls `/apps/oidc/userinfo` with Bearer token
+   - Nextcloud returns user info including **granted scopes**
+   - Result cached for 1 hour
+
+3. **Dynamic Tool Filtering**
+   - Server compares token scopes with each tool's `@require_scopes`
+   - Only returns tools where user has all required scopes
+   - Example: Token with `notes:read` sees 4 read tools, not 3 write tools
+
+4. **Filtered Tool List**
+   - Client receives only tools they can use
+
+#### Tool Execution (e.g., `nc_notes_get_note`)
+1. **Tool Call**
+   - Client invokes tool with `Authorization: Bearer <token>`
+
+2. **Scope Validation**
+   - `@require_scopes` decorator extracts token scopes
+   - Verifies token contains required scope (e.g., `notes:read`)
+   - If missing → 403 with `WWW-Authenticate` header (step-up auth)
+   - If present → continues execution
+
+3. **Nextcloud API Call**
+   - MCP server creates `NextcloudClient` with Bearer token
+   - Calls Nextcloud API (e.g., `GET /apps/notes/api/v1/notes/1`)
+   - `user_oidc` app validates Bearer token again
+   - Request executes as authenticated user
+
+4. **Response**
+   - Nextcloud returns data
+   - MCP server formats response
+   - Returns to client
+
+**Result**: User can only access tools and data they have permissions for
+
+### Phase 4: Insufficient Scope Handling (Step-Up Authorization)
+
+**Happens**: When user lacks required scopes
+
+**Steps**:
+1. **Tool Call with Insufficient Scopes**
+   - User calls `nc_notes_create_note` (requires `notes:write`)
+   - But token only has `notes:read`
+
+2. **Scope Validation Fails**
+   - `@require_scopes("notes:write")` decorator checks token
+   - Finds `notes:write` missing
+
+3. **403 Response with Challenge**
+   - Returns `403 Forbidden`
+   - Includes `WWW-Authenticate` header:
+     ```
+     Bearer error="insufficient_scope",
+            scope="notes:write",
+            resource_metadata="http://localhost:8000/.well-known/oauth-protected-resource/mcp"
+     ```
+
+4. **Client Re-Authorization** (Optional)
+   - Client can initiate new OAuth flow requesting additional scopes
+   - User re-consents with expanded permissions
+   - New token includes both `notes:read` and `notes:write`
+
+**Result**: User can dynamically upgrade permissions without full re-authentication
 
 ## Token Validation
 
@@ -272,14 +569,145 @@ client = get_client_from_context(ctx)
 - Protects against authorization code interception
 
 ### Scopes
-- Required scopes: `openid`, `profile`
-- Additional scopes inferred from userinfo response
+- Base required scopes: `openid`, `profile`, `email`
+- App-specific scopes control access to individual Nextcloud apps
+- See [OAuth Scopes](#oauth-scopes) section for complete scope reference
 
 ### Token Validation
 - Every MCP request validates Bearer token
 - Cached for performance (1-hour default)
 - Calls userinfo endpoint for validation
 
+## OAuth Scopes
+
+The Nextcloud MCP Server implements fine-grained OAuth scopes for each Nextcloud app integration. Scopes control which tools are visible and accessible to users based on their granted permissions.
+
+### Scope-Based Access Control
+
+When using OAuth authentication:
+1. **Dynamic Discovery**: The server automatically discovers all required scopes from `@require_scopes` decorators on MCP tools
+2. **Tool Filtering**: Tools are dynamically filtered based on the user's token scopes - users only see tools they have permission to use
+3. **Per-Tool Enforcement**: Each tool validates required scopes before execution, returning a 403 error if insufficient scopes are present
+
+### Supported Scopes
+
+The server supports the following OAuth scopes, organized by Nextcloud app:
+
+#### Base OIDC Scopes
+- `openid` - OpenID Connect authentication (required)
+- `profile` - Access to user profile information (required)
+- `email` - Access to user email address (required)
+
+#### Notes App
+- `notes:read` - Read notes, search notes, get note attachments
+- `notes:write` - Create, update, append to, and delete notes
+
+#### Calendar App
+- `calendar:read` - List calendars, read events, search events
+- `calendar:write` - Create, update, and delete calendars and events
+
+#### Calendar Tasks (VTODO)
+- `todo:read` - List and read CalDAV tasks
+- `todo:write` - Create, update, and delete CalDAV tasks
+
+#### Contacts App
+- `contacts:read` - List address books and read contacts (CardDAV)
+- `contacts:write` - Create, update, and delete address books and contacts
+
+#### Cookbook App
+- `cookbook:read` - Read recipes, search recipes
+- `cookbook:write` - Create, update, and delete recipes
+
+#### Deck App
+- `deck:read` - List boards, stacks, cards, and labels
+- `deck:write` - Create, update, and delete boards, stacks, cards, and labels
+
+#### Tables App
+- `tables:read` - List tables and read rows
+- `tables:write` - Create, update, and delete rows in tables
+
+#### Files (WebDAV)
+- `files:read` - List files, read file contents, search files
+- `files:write` - Upload, update, move, copy, and delete files
+
+#### Sharing
+- `sharing:read` - List shares and read share information
+- `sharing:write` - Create, update, and delete shares
+
+### Scope Discovery
+
+The MCP server provides scope discovery through two mechanisms:
+
+#### 1. Protected Resource Metadata (PRM) Endpoint
+```bash
+# Query the PRM endpoint
+curl http://localhost:8000/.well-known/oauth-protected-resource/mcp
+
+# Response includes dynamically discovered scopes
+{
+  "resource": "http://localhost:8000/mcp",
+  "scopes_supported": ["openid", "profile", "email", "notes:read", ...],
+  "authorization_servers": ["https://nextcloud.example.com"],
+  "bearer_methods_supported": ["header"],
+  "resource_signing_alg_values_supported": ["RS256"]
+}
+```
+
+The `scopes_supported` field is **dynamically generated** from all registered MCP tools, ensuring it always reflects the actual available scopes.
+
+#### 2. Scope Enforcement via Decorators
+
+Tools are decorated with `@require_scopes()` to declare their required permissions:
+
+```python
+from nextcloud_mcp_server.auth import require_scopes
+
+@mcp.tool()
+@require_scopes("notes:read")
+async def nc_notes_get_note(ctx: Context, note_id: int):
+    """Get a specific note by ID"""
+    # Implementation
+```
+
+### Client Registration Scopes
+
+During OAuth client registration (dynamic or manual), clients request a set of scopes that define the **maximum allowed** scopes for that client. The actual per-tool enforcement is handled separately via decorators.
+
+**Environment Variable**:
+```bash
+NEXTCLOUD_OIDC_SCOPES="openid profile email notes:read notes:write calendar:read calendar:write ..."
+```
+
+**Default**: All supported scopes (recommended for development)
+
+> **Note**: Client registration scopes define the maximum permissions. The MCP server's PRM endpoint dynamically advertises the actual supported scopes based on registered tools.
+
+### Step-Up Authorization
+
+The server supports OAuth step-up authorization (RFC 8693). If a user attempts to use a tool requiring scopes they don't have:
+
+1. Tool returns `403 Forbidden` with `InsufficientScopeError`
+2. Response includes `WWW-Authenticate` header listing missing scopes:
+   ```
+   WWW-Authenticate: Bearer error="insufficient_scope", scope="notes:write", resource_metadata="..."
+   ```
+3. Client can re-authorize with additional scopes
+
+### Scope Validation
+
+All scope enforcement happens at two levels:
+
+1. **Tool Visibility**: During `list_tools` requests, only tools matching the user's token scopes are returned
+2. **Execution Time**: When calling a tool, the `@require_scopes` decorator validates the token has necessary scopes
+
+**Example**:
+```python
+# User token has: ["openid", "profile", "email", "notes:read"]
+# They will see: 4 read-only notes tools
+# They will NOT see: 3 write notes tools (notes:write required)
+# Attempting to call a write tool returns 403 Forbidden
+```
+
 ## Configuration
 
 See [Configuration Guide](configuration.md) for all OAuth environment variables:

docs/oauth-troubleshooting.md

@@ -14,6 +14,7 @@ Start here to identify your issue:
 | "OAuth mode requires client credentials OR dynamic registration" | OIDC apps not configured | [Missing OIDC Apps](#missing-or-misconfigured-oidc-apps) |
 | "PKCE support validation failed" | OIDC app doesn't advertise PKCE | [PKCE Not Advertised](#pkce-not-advertised) |
 | "Stored client has expired" | Dynamic client expired | [Client Expired](#client-expired) |
+| Only seeing Notes tools (7 instead of 90+) | Limited OAuth scopes granted | [Limited Scopes](#limited-scopes---only-seeing-notes-tools) |
 | HTTP 401 for Notes API | Bearer token patch missing | [Bearer Token Auth Fails](#bearer-token-authentication-fails) |
 | "OIDC discovery failed" | Network or configuration issue | [Discovery Failed](#oidc-discovery-failed) |
 | "Permission denied" on .nextcloud_oauth_client.json | File permissions issue | [File Permission Error](#file-permission-error) |
@@ -407,6 +408,94 @@ http://localhost:8000/oauth/callback
 
 ---
 
+### Limited Scopes - Only Seeing Notes Tools
+
+**Symptoms**:
+- MCP client (e.g., Claude Code) successfully connects via OAuth
+- Only Notes tools are available (7 tools instead of 90+)
+- Token scopes show only `mcp:notes:read` and `mcp:notes:write`
+
+**Cause**: During the OAuth consent flow, the user only granted access to Notes scopes, or the client only requested those scopes.
+
+**Diagnosis**:
+
+Check what scopes the client has been granted:
+
+```bash
+# View registered clients and their allowed scopes
+php occ oidc:list | jq '.[] | select(.name | contains("Claude Code")) | {name, allowed_scopes}'
+```
+
+Look for the client's `allowed_scopes` field. If it's empty or only contains notes scopes, that's the issue.
+
+**Solution**:
+
+**Option 1: Delete Client and Reconnect** (Recommended for MCP clients)
+
+```bash
+# Find the client ID
+php occ oidc:list | jq '.[] | select(.name | contains("Claude Code")) | {name, client_id}'
+
+# Delete the client
+php occ oidc:delete <client_id>
+
+# Reconnect from Claude Code
+# This will trigger a new OAuth flow where you can grant all scopes
+```
+
+When reconnecting, you'll see a consent screen listing all available scopes. Make sure to approve all the scopes you want the client to access.
+
+**Option 2: Update Client Scopes via CLI**
+
+```bash
+# Update allowed scopes for an existing client
+php occ oidc:update <client_id> \
+  --allowed-scopes "openid profile email mcp:notes:read mcp:notes:write mcp:calendar:read mcp:calendar:write mcp:contacts:read mcp:contacts:write mcp:cookbook:read mcp:cookbook:write mcp:deck:read mcp:deck:write mcp:tables:read mcp:tables:write mcp:files:read mcp:files:write mcp:sharing:read mcp:sharing:write"
+
+# User will need to reconnect to get new token with updated scopes
+```
+
+**Verify Available Scopes**:
+
+Check what scopes the MCP server advertises:
+
+```bash
+curl http://localhost:8001/.well-known/oauth-protected-resource | jq '.scopes_supported'
+
+# Should show all 16 scope categories:
+# - openid
+# - mcp:notes:read, mcp:notes:write
+# - mcp:calendar:read, mcp:calendar:write
+# - mcp:contacts:read, mcp:contacts:write
+# - mcp:cookbook:read, mcp:cookbook:write
+# - mcp:deck:read, mcp:deck:write
+# - mcp:tables:read, mcp:tables:write
+# - mcp:files:read, mcp:files:write
+# - mcp:sharing:read, mcp:sharing:write
+```
+
+**Understanding Scope Filtering**:
+
+The MCP server dynamically filters tools based on the scopes in your access token:
+- Check server logs for: `✂️ JWT scope filtering: X/90 tools available for scopes: {...}`
+- This shows how many tools are visible vs total available
+- Each tool requires specific scopes (read and/or write)
+
+**Available Scope Categories**:
+
+| Scope Prefix | Nextcloud App | Read Operations | Write Operations |
+|--------------|---------------|-----------------|------------------|
+| `mcp:notes:*` | Notes | Get, search, list | Create, update, delete, append |
+| `mcp:calendar:*` | Calendar (CalDAV) | Get events, todos, calendars | Create/update/delete events, todos |
+| `mcp:contacts:*` | Contacts (CardDAV) | Get contacts, address books | Create/update/delete contacts |
+| `mcp:cookbook:*` | Cookbook | Get recipes, search | Create/update recipes |
+| `mcp:deck:*` | Deck | Get boards, cards | Create/update boards, cards |
+| `mcp:tables:*` | Tables | Get rows, tables | Create/update/delete rows |
+| `mcp:files:*` | Files (WebDAV) | List, read files | Upload, delete, move files |
+| `mcp:sharing:*` | Sharing | Get shares | Create/update shares |
+
+---
+
 ## Switching Authentication Modes
 
 ### From BasicAuth to OAuth

docs/testing-oidc-consent.md

@@ -182,15 +182,15 @@ You can test using the MCP OAuth container or manually:
 
 **Option A: Using MCP OAuth container**
 ```bash
-# The mcp-oauth-jwt container will trigger the OAuth flow
-docker compose logs -f mcp-oauth-jwt
+# The mcp-oauth container will trigger the OAuth flow
+docker compose logs -f mcp-oauth
 ```
 
 **Option B: Manual browser test**
 1. Get client_id from the JWT client JSON
 2. Visit in browser:
 ```
-http://localhost:8080/apps/oidc/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://localhost:8002/oauth/callback&scope=openid+profile+email+nc:read+nc:write&state=test123
+http://localhost:8080/apps/oidc/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://localhost:8001/oauth/callback&scope=openid+profile+email+mcp:notes:read+mcp:notes:write&state=test123
 ```
 
 ### 3. Expected Behavior
@@ -203,8 +203,8 @@ http://localhost:8080/apps/oidc/authorize?client_id=YOUR_CLIENT_ID&response_type
      - ✓ Basic authentication (openid) - required, cannot deselect
      - ✓ Profile information (profile)
      - ✓ Email address (email)
-     - ✓ nc:read (custom scope, shown as-is)
-     - ✓ nc:write (custom scope, shown as-is)
+     - ✓ mcp:notes:read (custom scope, shown as-is)
+     - ✓ mcp:notes:write (custom scope, shown as-is)
    - "Allow" and "Deny" buttons
 3. User selects scopes and clicks "Allow"
 4. Authorization proceeds with selected scopes

env.sample

@@ -21,3 +21,77 @@ NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
 # - If these are set, OAuth mode is disabled
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
+
+# ============================================
+# Document Processing Configuration
+# ============================================
+# Enable document processing (PDF, DOCX, images, etc.)
+# Set to false to disable all document processing
+ENABLE_DOCUMENT_PROCESSING=false
+
+# Default processor to use when multiple are available
+# Options: unstructured, tesseract, custom
+DOCUMENT_PROCESSOR=unstructured
+
+# ============================================
+# Unstructured.io Processor
+# ============================================
+# Enable Unstructured processor (requires unstructured service in docker-compose)
+# This is a cloud-based/API processor supporting many document types
+ENABLE_UNSTRUCTURED=false
+
+# Unstructured API endpoint
+UNSTRUCTURED_API_URL=http://unstructured:8000
+
+# Request timeout in seconds (default: 120)
+# OCR operations can take 30-120 seconds for large documents
+UNSTRUCTURED_TIMEOUT=120
+
+# Parsing strategy: auto, fast, hi_res
+# - auto: Automatically choose based on document type
+# - fast: Fast parsing without OCR
+# - hi_res: High-resolution with OCR (slowest, most accurate)
+UNSTRUCTURED_STRATEGY=auto
+
+# OCR languages (comma-separated ISO 639-3 codes)
+# Common: eng=English, deu=German, fra=French, spa=Spanish
+UNSTRUCTURED_LANGUAGES=eng,deu
+
+# Progress reporting interval in seconds (default: 10)
+# During long-running OCR operations, progress notifications are sent to the MCP client
+# at this interval to prevent timeouts and provide status updates
+PROGRESS_INTERVAL=10
+
+# ============================================
+# Tesseract Processor (Local OCR)
+# ============================================
+# Enable Tesseract processor (requires tesseract binary installed)
+# This is a local, lightweight OCR solution for images only
+ENABLE_TESSERACT=false
+
+# Path to tesseract executable (optional, auto-detected if in PATH)
+#TESSERACT_CMD=/usr/bin/tesseract
+
+# OCR language (e.g., eng, deu, eng+deu for multiple)
+TESSERACT_LANG=eng
+
+# ============================================
+# Custom Processor (Your own API)
+# ============================================
+# Enable custom document processor via HTTP API
+ENABLE_CUSTOM_PROCESSOR=false
+
+# Unique name for your processor
+#CUSTOM_PROCESSOR_NAME=my_ocr
+
+# Your custom processor API endpoint
+#CUSTOM_PROCESSOR_URL=http://localhost:9000/process
+
+# Optional API key for authentication
+#CUSTOM_PROCESSOR_API_KEY=your-api-key-here
+
+# Request timeout in seconds
+#CUSTOM_PROCESSOR_TIMEOUT=60
+
+# Comma-separated MIME types your processor supports
+#CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg,image/png

nextcloud_mcp_server/app.py

@@ -11,19 +11,26 @@ from mcp.server.auth.settings import AuthSettings
 from mcp.server.fastmcp import Context, FastMCP
 from pydantic import AnyHttpUrl
 from starlette.applications import Starlette
+from starlette.middleware.cors import CORSMiddleware
 from starlette.responses import JSONResponse
 from starlette.routing import Mount, Route
 
 from nextcloud_mcp_server.auth import (
     InsufficientScopeError,
     NextcloudTokenVerifier,
+    discover_all_scopes,
     get_access_token_scopes,
     has_required_scopes,
     is_jwt_token,
 )
 from nextcloud_mcp_server.client import NextcloudClient
-from nextcloud_mcp_server.config import LOGGING_CONFIG, setup_logging
+from nextcloud_mcp_server.config import (
+    LOGGING_CONFIG,
+    get_document_processor_config,
+    setup_logging,
+)
 from nextcloud_mcp_server.context import get_client as get_nextcloud_client
+from nextcloud_mcp_server.document_processors import get_registry
 from nextcloud_mcp_server.server import (
     configure_calendar_tools,
     configure_contacts_tools,
@@ -38,6 +45,92 @@ from nextcloud_mcp_server.server import (
 logger = logging.getLogger(__name__)
 
 
+def initialize_document_processors():
+    """Initialize and register document processors based on configuration.
+
+    This function reads the environment configuration and registers available
+    processors (Unstructured, Tesseract, Custom HTTP) with the global registry.
+    """
+    config = get_document_processor_config()
+
+    if not config["enabled"]:
+        logger.info("Document processing disabled")
+        return
+
+    registry = get_registry()
+    registered_count = 0
+
+    # Register Unstructured processor
+    if "unstructured" in config["processors"]:
+        unst_config = config["processors"]["unstructured"]
+        try:
+            from nextcloud_mcp_server.document_processors.unstructured import (
+                UnstructuredProcessor,
+            )
+
+            processor = UnstructuredProcessor(
+                api_url=unst_config["api_url"],
+                timeout=unst_config["timeout"],
+                default_strategy=unst_config["strategy"],
+                default_languages=unst_config["languages"],
+                progress_interval=unst_config.get("progress_interval", 10),
+            )
+            registry.register(processor, priority=10)
+            logger.info(f"Registered Unstructured processor: {unst_config['api_url']}")
+            registered_count += 1
+        except Exception as e:
+            logger.warning(f"Failed to register Unstructured processor: {e}")
+
+    # Register Tesseract processor
+    if "tesseract" in config["processors"]:
+        tess_config = config["processors"]["tesseract"]
+        try:
+            from nextcloud_mcp_server.document_processors.tesseract import (
+                TesseractProcessor,
+            )
+
+            processor = TesseractProcessor(
+                tesseract_cmd=tess_config.get("tesseract_cmd"),
+                default_lang=tess_config["lang"],
+            )
+            registry.register(processor, priority=5)
+            logger.info(f"Registered Tesseract processor: lang={tess_config['lang']}")
+            registered_count += 1
+        except Exception as e:
+            logger.warning(f"Failed to register Tesseract processor: {e}")
+
+    # Register custom processor
+    if "custom" in config["processors"]:
+        custom_config = config["processors"]["custom"]
+        try:
+            from nextcloud_mcp_server.document_processors.custom_http import (
+                CustomHTTPProcessor,
+            )
+
+            processor = CustomHTTPProcessor(
+                name=custom_config["name"],
+                api_url=custom_config["api_url"],
+                api_key=custom_config.get("api_key"),
+                timeout=custom_config["timeout"],
+                supported_types=custom_config["supported_types"],
+            )
+            registry.register(processor, priority=1)
+            logger.info(
+                f"Registered Custom processor '{custom_config['name']}': {custom_config['api_url']}"
+            )
+            registered_count += 1
+        except Exception as e:
+            logger.warning(f"Failed to register Custom processor: {e}")
+
+    if registered_count > 0:
+        logger.info(
+            f"Document processing initialized with {registered_count} processor(s): "
+            f"{', '.join(registry.list_processors())}"
+        )
+    else:
+        logger.warning("Document processing enabled but no processors registered")
+
+
 def validate_pkce_support(discovery: dict, discovery_url: str) -> None:
     """
     Validate that the OIDC provider properly advertises PKCE support.
@@ -191,9 +284,28 @@ async def load_oauth_client_credentials(
         redirect_uris = [f"{mcp_server_url}/oauth/callback"]
 
         # Get scopes from environment or use defaults
-        scopes = os.getenv(
-            "NEXTCLOUD_OIDC_SCOPES", "openid profile email nc:read nc:write"
+        # Note: Client registration happens BEFORE tools are registered, so we can't
+        # dynamically discover scopes here. These scopes define the "maximum allowed"
+        # scopes for this OAuth client. The actual per-tool scope enforcement happens
+        # via @require_scopes decorators, and the PRM endpoint advertises the actual
+        # supported scopes dynamically.
+        #
+        # IMPORTANT: Keep this list in sync with all @require_scopes decorators
+        # when adding new apps, or set NEXTCLOUD_OIDC_SCOPES environment variable
+        # to override.
+        default_scopes = (
+            "openid profile email "
+            "notes:read notes:write "
+            "calendar:read calendar:write "
+            "todo:read todo:write "
+            "contacts:read contacts:write "
+            "cookbook:read cookbook:write "
+            "deck:read deck:write "
+            "tables:read tables:write "
+            "files:read files:write "
+            "sharing:read sharing:write"
         )
+        scopes = os.getenv("NEXTCLOUD_OIDC_SCOPES", default_scopes)
         logger.info(f"Requesting OAuth scopes: {scopes}")
 
         # Get token type from environment (Bearer or jwt)
@@ -213,7 +325,7 @@ async def load_oauth_client_credentials(
             nextcloud_url=nextcloud_host,
             registration_endpoint=registration_endpoint,
             storage_path=storage_path,
-            client_name="Nextcloud MCP Server",
+            client_name=f"Nextcloud MCP Server ({token_type})",
             redirect_uris=redirect_uris,
             scopes=scopes,
             token_type=token_type,
@@ -245,6 +357,9 @@ async def app_lifespan_basic(server: FastMCP) -> AsyncIterator[AppContext]:
     client = NextcloudClient.from_env()
     logger.info("Client initialization complete")
 
+    # Initialize document processors
+    initialize_document_processors()
+
     try:
         yield AppContext(client=client)
     finally:
@@ -305,6 +420,9 @@ async def app_lifespan_oauth(server: FastMCP) -> AsyncIterator[OAuthAppContext]:
 
         logger.info("OAuth initialization complete")
 
+        # Initialize document processors
+        initialize_document_processors()
+
         try:
             yield OAuthAppContext(
                 nextcloud_host=nextcloud_host, token_verifier=token_verifier
@@ -423,9 +541,9 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     if oauth_enabled:
         logger.info("Configuring MCP server for OAuth mode")
         # Asynchronously get the OAuth configuration
-        import asyncio
+        import anyio
 
-        _, token_verifier, auth_settings = asyncio.run(setup_oauth_config())
+        _, token_verifier, auth_settings = anyio.run(setup_oauth_config)
         mcp = FastMCP(
             "Nextcloud MCP",
             lifespan=app_lifespan_oauth,
@@ -474,7 +592,7 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
         original_list_tools = mcp._tool_manager.list_tools
 
         def list_tools_filtered():
-            """List tools filtered by user's token scopes (JWT tokens only)."""
+            """List tools filtered by user's token scopes (JWT and Bearer tokens)."""
             # Get user's scopes from token using MCP SDK's contextvar
             # This works for all request types including list_tools
             user_scopes = get_access_token_scopes()
@@ -487,35 +605,36 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
             # Get all tools
             all_tools = original_list_tools()
 
-            # Only filter for JWT tokens (opaque tokens show all tools)
-            # JWT tokens have scopes embedded, so we can reliably filter
-            # Opaque tokens may not have accurate scope information from introspection
-            if is_jwt and user_scopes:
+            # Filter tools based on user's token scopes (both JWT and opaque tokens)
+            # JWT tokens have scopes embedded in payload
+            # Opaque tokens get scopes via introspection endpoint
+            # Claude Code now properly respects PRM endpoint for scope discovery
+            if user_scopes:
                 allowed_tools = [
                     tool
                     for tool in all_tools
                     if has_required_scopes(tool.fn, user_scopes)
                 ]
+                token_type = "JWT" if is_jwt else "Bearer"
                 logger.info(
-                    f"✂️ JWT scope filtering: {len(allowed_tools)}/{len(all_tools)} tools "
+                    f"✂️ {token_type} scope filtering: {len(allowed_tools)}/{len(all_tools)} tools "
                     f"available for scopes: {user_scopes}"
                 )
             else:
-                # Opaque token, BasicAuth mode, or no token - show all tools
+                # BasicAuth mode or no token - show all tools
                 allowed_tools = all_tools
-                reason = (
-                    "opaque token (no filtering)"
-                    if not is_jwt and user_scopes
-                    else "no token/BasicAuth"
+                logger.info(
+                    f"📋 Showing all {len(all_tools)} tools (no token/BasicAuth)"
                 )
-                logger.info(f"📋 Showing all {len(all_tools)} tools ({reason})")
 
             # Return the Tool objects directly (they're already in the correct format)
             return allowed_tools
 
         # Replace the tool manager's list_tools method
         mcp._tool_manager.list_tools = list_tools_filtered
-        logger.info("Dynamic tool filtering enabled for OAuth mode (JWT tokens only)")
+        logger.info(
+            "Dynamic tool filtering enabled for OAuth mode (JWT and Bearer tokens)"
+        )
 
     if transport == "sse":
         mcp_app = mcp.sse_app()
@@ -529,15 +648,85 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 await stack.enter_async_context(mcp.session_manager.run())
                 yield
 
+    # Health check endpoints for Kubernetes probes
+    def health_live(request):
+        """Liveness probe endpoint.
+
+        Returns 200 OK if the application process is running.
+        This is a simple check that doesn't verify external dependencies.
+        """
+        return JSONResponse(
+            {
+                "status": "alive",
+                "mode": "oauth" if oauth_enabled else "basic",
+            }
+        )
+
+    async def health_ready(request):
+        """Readiness probe endpoint.
+
+        Returns 200 OK if the application is ready to serve traffic.
+        Checks that required configuration is present.
+        """
+        checks = {}
+        is_ready = True
+
+        # Check Nextcloud host configuration
+        nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+        if nextcloud_host:
+            checks["nextcloud_configured"] = "ok"
+        else:
+            checks["nextcloud_configured"] = "error: NEXTCLOUD_HOST not set"
+            is_ready = False
+
+        # Check authentication configuration
+        if oauth_enabled:
+            # OAuth mode - just verify we got this far (token_verifier initialized in lifespan)
+            checks["auth_mode"] = "oauth"
+            checks["auth_configured"] = "ok"
+        else:
+            # BasicAuth mode - verify credentials are set
+            username = os.getenv("NEXTCLOUD_USERNAME")
+            password = os.getenv("NEXTCLOUD_PASSWORD")
+            if username and password:
+                checks["auth_mode"] = "basic"
+                checks["auth_configured"] = "ok"
+            else:
+                checks["auth_mode"] = "basic"
+                checks["auth_configured"] = "error: credentials not set"
+                is_ready = False
+
+        status_code = 200 if is_ready else 503
+        return JSONResponse(
+            {
+                "status": "ready" if is_ready else "not_ready",
+                "checks": checks,
+            },
+            status_code=status_code,
+        )
+
     # Add Protected Resource Metadata (PRM) endpoint for OAuth mode
     routes = []
+
+    # Add health check routes (available in both OAuth and BasicAuth modes)
+    routes.append(Route("/health/live", health_live, methods=["GET"]))
+    routes.append(Route("/health/ready", health_ready, methods=["GET"]))
+    logger.info("Health check endpoints enabled: /health/live, /health/ready")
+
     if oauth_enabled:
 
         def oauth_protected_resource_metadata(request):
-            """RFC 8959 Protected Resource Metadata endpoint."""
+            """RFC 9728 Protected Resource Metadata endpoint.
+
+            Dynamically discovers supported scopes from registered MCP tools.
+            This ensures the advertised scopes always match the actual tool requirements.
+            """
             mcp_server_url = os.getenv(
                 "NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000"
             )
+            # Append /mcp to match the actual resource path (FastMCP streamable-http endpoint)
+            resource_url = f"{mcp_server_url}/mcp"
+
             # Use PUBLIC_ISSUER_URL for authorization server since external clients
             # (like Claude) need the publicly accessible URL, not internal Docker URLs
             public_issuer_url = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
@@ -545,16 +734,30 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 # Fallback to NEXTCLOUD_HOST if PUBLIC_ISSUER_URL not set
                 public_issuer_url = os.getenv("NEXTCLOUD_HOST", "")
 
+            # Dynamically discover all scopes from registered tools
+            # This provides a single source of truth based on @require_scopes decorators
+            supported_scopes = discover_all_scopes(mcp)
+
             return JSONResponse(
                 {
-                    "resource": mcp_server_url,
-                    "scopes_supported": ["nc:read", "nc:write"],
+                    "resource": resource_url,
+                    "scopes_supported": supported_scopes,
                     "authorization_servers": [public_issuer_url],
                     "bearer_methods_supported": ["header"],
                     "resource_signing_alg_values_supported": ["RS256"],
                 }
             )
 
+        # Register PRM endpoint at both path-based and root locations per RFC 9728
+        # Path-based discovery: /.well-known/oauth-protected-resource{path}
+        routes.append(
+            Route(
+                "/.well-known/oauth-protected-resource/mcp",
+                oauth_protected_resource_metadata,
+                methods=["GET"],
+            )
+        )
+        # Root discovery (fallback): /.well-known/oauth-protected-resource
         routes.append(
             Route(
                 "/.well-known/oauth-protected-resource",
@@ -562,11 +765,23 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 methods=["GET"],
             )
         )
-        logger.info("Protected Resource Metadata (PRM) endpoint enabled")
+        logger.info(
+            "Protected Resource Metadata (PRM) endpoints enabled (path-based + root)"
+        )
 
     routes.append(Mount("/", app=mcp_app))
     app = Starlette(routes=routes, lifespan=lifespan)
 
+    # Add CORS middleware to allow browser-based clients like MCP Inspector
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # Allow all origins for development
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+        expose_headers=["*"],
+    )
+
     # Add exception handler for scope challenges (OAuth mode only)
     if oauth_enabled:
 
@@ -584,7 +799,7 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                     "WWW-Authenticate": (
                         f'Bearer error="insufficient_scope", '
                         f'scope="{scope_str}", '
-                        f'resource_metadata="{resource_url}/.well-known/oauth-protected-resource"'
+                        f'resource_metadata="{resource_url}/.well-known/oauth-protected-resource/mcp"'
                     )
                 },
                 content={
@@ -677,9 +892,9 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
 @click.option(
     "--oauth-scopes",
     envvar="NEXTCLOUD_OIDC_SCOPES",
-    default="openid profile email nc:read nc:write",
+    default="openid profile email notes:read notes:write calendar:read calendar:write todo:read todo:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write",
     show_default=True,
-    help="OAuth scopes to request (can also use NEXTCLOUD_OIDC_SCOPES env var)",
+    help="OAuth scopes to request during client registration. These define the maximum allowed scopes for the client. Note: Actual supported scopes are discovered dynamically from MCP tools at runtime. (can also use NEXTCLOUD_OIDC_SCOPES env var)",
 )
 @click.option(
     "--oauth-token-type",
@@ -741,7 +956,7 @@ def run(
 
       # OAuth mode with custom scopes and JWT tokens
       $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth \\
-          --oauth-scopes="openid nc:read" --oauth-token-type=jwt
+          --oauth-scopes="openid notes:read notes:write" --oauth-token-type=jwt
 
       # OAuth with public issuer URL (for Docker/proxy setups)
       $ nextcloud-mcp-server --nextcloud-host=http://app --oauth \\

nextcloud_mcp_server/auth/__init__.py

@@ -7,6 +7,7 @@ from .scope_authorization import (
     InsufficientScopeError,
     ScopeAuthorizationError,
     check_scopes,
+    discover_all_scopes,
     get_access_token_scopes,
     get_required_scopes,
     has_required_scopes,
@@ -25,6 +26,7 @@ __all__ = [
     "ScopeAuthorizationError",
     "InsufficientScopeError",
     "check_scopes",
+    "discover_all_scopes",
     "get_access_token_scopes",
     "get_required_scopes",
     "has_required_scopes",

nextcloud_mcp_server/auth/client_registration.py

@@ -8,13 +8,14 @@ import time
 from pathlib import Path
 from typing import Any
 
+import anyio
 import httpx
 
 logger = logging.getLogger(__name__)
 
 
 class ClientInfo:
-    """Client registration information."""
+    """Client registration information with RFC 7592 support."""
 
     def __init__(
         self,
@@ -23,12 +24,16 @@ class ClientInfo:
         client_id_issued_at: int,
         client_secret_expires_at: int,
         redirect_uris: list[str],
+        registration_access_token: str | None = None,
+        registration_client_uri: str | None = None,
     ):
         self.client_id = client_id
         self.client_secret = client_secret
         self.client_id_issued_at = client_id_issued_at
         self.client_secret_expires_at = client_secret_expires_at
         self.redirect_uris = redirect_uris
+        self.registration_access_token = registration_access_token
+        self.registration_client_uri = registration_client_uri
 
     @property
     def is_expired(self) -> bool:
@@ -42,13 +47,18 @@ class ClientInfo:
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for storage."""
-        return {
+        result = {
             "client_id": self.client_id,
             "client_secret": self.client_secret,
             "client_id_issued_at": self.client_id_issued_at,
             "client_secret_expires_at": self.client_secret_expires_at,
             "redirect_uris": self.redirect_uris,
         }
+        if self.registration_access_token:
+            result["registration_access_token"] = self.registration_access_token
+        if self.registration_client_uri:
+            result["registration_client_uri"] = self.registration_client_uri
+        return result
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "ClientInfo":
@@ -59,6 +69,8 @@ class ClientInfo:
             client_id_issued_at=data["client_id_issued_at"],
             client_secret_expires_at=data["client_secret_expires_at"],
             redirect_uris=data["redirect_uris"],
+            registration_access_token=data.get("registration_access_token"),
+            registration_client_uri=data.get("registration_client_uri"),
         )
 
 
@@ -125,6 +137,16 @@ async def register_client(
                 f"(in {client_info.get('client_secret_expires_at', 0) - int(time.time())} seconds)"
             )
 
+            # Log if RFC 7592 fields are present
+            has_reg_token = "registration_access_token" in client_info
+            has_reg_uri = "registration_client_uri" in client_info
+            if has_reg_token and has_reg_uri:
+                logger.info(
+                    "RFC 7592 management fields received - client deletion will be supported"
+                )
+            else:
+                logger.warning("RFC 7592 fields missing - client deletion may not work")
+
             return ClientInfo(
                 client_id=client_info["client_id"],
                 client_secret=client_info["client_secret"],
@@ -135,6 +157,8 @@ async def register_client(
                     "client_secret_expires_at", int(time.time()) + 3600
                 ),
                 redirect_uris=client_info.get("redirect_uris", redirect_uris),
+                registration_access_token=client_info.get("registration_access_token"),
+                registration_client_uri=client_info.get("registration_client_uri"),
             )
 
         except httpx.HTTPStatusError as e:
@@ -212,6 +236,132 @@ def save_client_to_file(client_info: ClientInfo, storage_path: Path):
         raise
 
 
+async def delete_client(
+    nextcloud_url: str,
+    client_id: str,
+    registration_access_token: str | None = None,
+    client_secret: str | None = None,
+    registration_client_uri: str | None = None,
+    max_retries: int = 3,
+) -> bool:
+    """
+    Delete a dynamically registered OAuth client using RFC 7592.
+
+    This implements RFC 7592 Section 2.3 (Client Delete Request).
+    Prefers Bearer token authentication (RFC 7592 standard) but falls back
+    to HTTP Basic Auth if registration_access_token is not available.
+
+    Args:
+        nextcloud_url: Base URL of the Nextcloud instance
+        client_id: Client identifier to delete
+        registration_access_token: RFC 7592 registration access token (preferred)
+        client_secret: Client secret for fallback HTTP Basic Auth
+        registration_client_uri: RFC 7592 client configuration URI (optional)
+        max_retries: Maximum number of retries for 429 responses (default: 3)
+
+    Returns:
+        True if deletion successful, False otherwise
+
+    Note:
+        RFC 7592 deletion endpoint: {registration_client_uri} or {nextcloud_url}/apps/oidc/register/{client_id}
+
+        Authentication methods (in order of preference):
+        1. Bearer token: Authorization: Bearer {registration_access_token} (RFC 7592 standard)
+        2. HTTP Basic Auth: client_id as username, client_secret as password (fallback)
+    """
+
+    # Determine deletion endpoint
+    if registration_client_uri:
+        deletion_endpoint = registration_client_uri
+    else:
+        deletion_endpoint = f"{nextcloud_url}/apps/oidc/register/{client_id}"
+
+    logger.info(f"Deleting OAuth client: {client_id[:16]}...")
+    logger.debug(f"Deletion endpoint: {deletion_endpoint}")
+
+    async with httpx.AsyncClient(timeout=30.0) as http_client:
+        for attempt in range(max_retries):
+            try:
+                # Prefer RFC 7592 Bearer token authentication
+                if registration_access_token:
+                    logger.debug("Using RFC 7592 Bearer token authentication")
+                    response = await http_client.delete(
+                        deletion_endpoint,
+                        headers={
+                            "Authorization": f"Bearer {registration_access_token}"
+                        },
+                    )
+                elif client_secret:
+                    logger.debug(
+                        "Falling back to HTTP Basic Auth (registration_access_token not available)"
+                    )
+                    response = await http_client.delete(
+                        deletion_endpoint,
+                        auth=(client_id, client_secret),
+                    )
+                else:
+                    logger.error(
+                        "Cannot delete client: no registration_access_token or client_secret provided"
+                    )
+                    return False
+
+                # RFC 7592: Successful deletion returns 204 No Content
+                if response.status_code == 204:
+                    logger.info(
+                        f"Successfully deleted OAuth client: {client_id[:16]}..."
+                    )
+                    return True
+                elif response.status_code == 429:
+                    # Rate limited - retry with exponential backoff
+                    if attempt < max_retries - 1:
+                        retry_after = int(response.headers.get("Retry-After", 2))
+                        wait_time = min(
+                            retry_after, 2**attempt
+                        )  # Exponential backoff, max from header
+                        logger.warning(
+                            f"Rate limited (429) deleting client {client_id[:16]}..., "
+                            f"retrying in {wait_time}s (attempt {attempt + 1}/{max_retries})"
+                        )
+                        await anyio.sleep(wait_time)
+                        continue
+                    else:
+                        logger.error(
+                            f"Failed to delete client {client_id[:16]}... after {max_retries} attempts: Rate limited (429)"
+                        )
+                        return False
+                elif response.status_code == 401:
+                    logger.error(
+                        f"Failed to delete client {client_id[:16]}...: Authentication failed (invalid credentials)"
+                    )
+                    return False
+                elif response.status_code == 403:
+                    logger.error(
+                        f"Failed to delete client {client_id[:16]}...: Not authorized (not a DCR client or wrong client)"
+                    )
+                    return False
+                else:
+                    logger.error(
+                        f"Failed to delete client {client_id[:16]}...: HTTP {response.status_code}"
+                    )
+                    logger.debug(f"Response: {response.text}")
+                    return False
+
+            except httpx.HTTPStatusError as e:
+                logger.error(
+                    f"HTTP error deleting client {client_id[:16]}...: {e.response.status_code}"
+                )
+                logger.debug(f"Response: {e.response.text}")
+                return False
+            except Exception as e:
+                logger.error(
+                    f"Unexpected error deleting client {client_id[:16]}...: {e}"
+                )
+                return False
+
+        # Should not reach here, but return False if we do
+        return False
+
+
 async def load_or_register_client(
     nextcloud_url: str,
     registration_endpoint: str,

nextcloud_mcp_server/auth/scope_authorization.py

@@ -46,7 +46,7 @@ def require_scopes(*required_scopes: str):
     users who lack the necessary scopes.
 
     Args:
-        *required_scopes: Variable number of scope strings required (e.g., "nc:read", "nc:write")
+        *required_scopes: Variable number of scope strings required (e.g., "notes:read", "notes:write")
 
     Returns:
         Decorated function that checks scopes before execution
@@ -54,15 +54,15 @@ def require_scopes(*required_scopes: str):
     Example:
         ```python
         @mcp.tool()
-        @require_scopes("nc:read")
+        @require_scopes("notes:read")
         async def nc_notes_get_note(ctx: Context, note_id: int):
-            # This tool requires the nc:read scope
+            # This tool requires the notes:read scope
             ...
 
         @mcp.tool()
-        @require_scopes("nc:write")
+        @require_scopes("notes:write")
         async def nc_notes_create_note(ctx: Context, ...):
-            # This tool requires the nc:write scope
+            # This tool requires the notes:write scope
             ...
         ```
 
@@ -173,7 +173,7 @@ def check_scopes(ctx: Context, *required_scopes: str) -> tuple[bool, set[str]]:
     Example:
         ```python
         async def my_tool(ctx: Context):
-            has_scopes, missing = check_scopes(ctx, "nc:read", "nc:write")
+            has_scopes, missing = check_scopes(ctx, "notes:read", "notes:write")
             if not has_scopes:
                 # Handle missing scopes
                 ...
@@ -203,11 +203,11 @@ def get_required_scopes(func: Callable) -> list[str]:
 
     Example:
         ```python
-        @require_scopes("nc:read", "nc:write")
+        @require_scopes("notes:read", "notes:write")
         async def my_tool():
             pass
 
-        scopes = get_required_scopes(my_tool)  # ["nc:read", "nc:write"]
+        scopes = get_required_scopes(my_tool)  # ["notes:read", "notes:write"]
         ```
     """
     return getattr(func, "_required_scopes", [])
@@ -253,14 +253,14 @@ def has_required_scopes(func: Callable, user_scopes: set[str]) -> bool:
 
     Example:
         ```python
-        @require_scopes("nc:write")
+        @require_scopes("notes:write")
         async def create_note():
             pass
 
-        user_scopes = {"nc:read", "nc:write"}
+        user_scopes = {"notes:read", "notes:write"}
         can_see = has_required_scopes(create_note, user_scopes)  # True
 
-        limited_user_scopes = {"nc:read"}
+        limited_user_scopes = {"notes:read"}
         can_see = has_required_scopes(create_note, limited_user_scopes)  # False
         ```
     """
@@ -276,3 +276,68 @@ def has_required_scopes(func: Callable, user_scopes: set[str]) -> bool:
 
     # Check if user has all required scopes
     return set(required).issubset(user_scopes)
+
+
+def discover_all_scopes(mcp) -> list[str]:
+    """
+    Dynamically discover all OAuth scopes required by registered MCP tools.
+
+    This function inspects all registered tools and extracts their required scopes
+    from the @require_scopes decorator metadata. It provides a single source of truth
+    for available scopes based on the actual tool implementations.
+
+    Args:
+        mcp: FastMCP instance with registered tools
+
+    Returns:
+        Sorted list of unique scope strings, including base OIDC scopes
+
+    Example:
+        ```python
+        from mcp.server.fastmcp import FastMCP
+
+        mcp = FastMCP("My Server")
+
+        @mcp.tool()
+        @require_scopes("notes:read")
+        async def get_notes():
+            pass
+
+        @mcp.tool()
+        @require_scopes("notes:write")
+        async def create_note():
+            pass
+
+        scopes = discover_all_scopes(mcp)
+        # Returns: ["notes:read", "notes:write", "openid", "profile", "email"]
+        ```
+
+    Note:
+        - Base OIDC scopes (openid, profile, email) are always included
+        - Scopes are deduplicated and sorted alphabetically
+        - Only scopes from decorated tools are included
+        - Must be called after tools are registered
+    """
+    # Start with base OIDC scopes that are always required
+    all_scopes = {"openid", "profile", "email"}
+
+    # Get all registered tools
+    try:
+        tools = mcp._tool_manager.list_tools()
+    except AttributeError:
+        logger.warning("FastMCP instance does not have _tool_manager attribute")
+        return sorted(all_scopes)
+
+    # Extract scopes from each tool
+    for tool in tools:
+        # Get the original function (tools have a .fn attribute)
+        func = getattr(tool, "fn", None)
+        if func is None:
+            continue
+
+        # Extract scopes using existing helper
+        tool_scopes = get_required_scopes(func)
+        all_scopes.update(tool_scopes)
+
+    # Return sorted list of unique scopes
+    return sorted(all_scopes)

nextcloud_mcp_server/auth/token_verifier.py

@@ -309,11 +309,18 @@ class NextcloudTokenVerifier(TokenVerifier):
                 )
 
             elif response.status_code in (400, 401, 403):
-                logger.info(f"Token introspection failed: HTTP {response.status_code}")
+                logger.warning(
+                    f"Token introspection failed: HTTP {response.status_code}. "
+                    f"This may indicate: (1) Client credentials mismatch - trying to introspect "
+                    f"token issued to different OAuth client, (2) Expired client credentials, "
+                    f"(3) Invalid token. Will fall back to userinfo endpoint. "
+                    f"Response: {response.text[:200] if response.text else 'empty'}"
+                )
                 return None
             else:
                 logger.warning(
-                    f"Unexpected response from introspection: {response.status_code}"
+                    f"Unexpected response from introspection: {response.status_code}. "
+                    f"Response: {response.text[:200] if response.text else 'empty'}"
                 )
                 return None
 
@@ -420,15 +427,31 @@ class NextcloudTokenVerifier(TokenVerifier):
         """
         Extract scopes from userinfo response.
 
-        Since the userinfo response doesn't include the original scopes,
-        we infer them from the claims present in the response.
+        First attempts to read actual scopes from the 'scope' field (RFC 8693).
+        If not present, infers scopes from the claims present in the response.
 
         Args:
             userinfo: The userinfo response dictionary
 
         Returns:
-            List of inferred scopes
+            List of scopes (actual or inferred)
         """
+        # Try to get actual scopes from userinfo response (if OIDC provider includes it)
+        scope_string = userinfo.get("scope")
+        if scope_string:
+            scopes = scope_string.split() if isinstance(scope_string, str) else []
+            if scopes:
+                logger.debug(
+                    f"Using actual scopes from userinfo: {scopes} (scope field present)"
+                )
+                return scopes
+
+        # Fallback: Infer scopes from claims present in response
+        # This maintains backward compatibility with OIDC providers that don't
+        # include the scope field in userinfo responses
+        logger.debug(
+            "No scope field in userinfo response, inferring scopes from claims"
+        )
         scopes = ["openid"]  # Always present
 
         if "email" in userinfo:
@@ -445,6 +468,7 @@ class NextcloudTokenVerifier(TokenVerifier):
         if "groups" in userinfo:
             scopes.append("groups")
 
+        logger.debug(f"Inferred scopes from userinfo claims: {scopes}")
         return scopes
 
     def clear_cache(self):

nextcloud_mcp_server/config.py

@@ -1,4 +1,6 @@
 import logging.config
+import os
+from typing import Any
 
 LOGGING_CONFIG = {
     "version": 1,
@@ -51,3 +53,68 @@ LOGGING_CONFIG = {
 
 def setup_logging():
     logging.config.dictConfig(LOGGING_CONFIG)
+
+
+# Document Processing Configuration
+
+
+def get_document_processor_config() -> dict[str, Any]:
+    """Get document processor configuration from environment.
+
+    Returns:
+        Dict with processor configs:
+        {
+            "enabled": bool,
+            "default_processor": str,
+            "processors": {
+                "unstructured": {...},
+                "tesseract": {...},
+                "custom": {...},
+            }
+        }
+    """
+    config: dict[str, Any] = {
+        "enabled": os.getenv("ENABLE_DOCUMENT_PROCESSING", "false").lower() == "true",
+        "default_processor": os.getenv("DOCUMENT_PROCESSOR", "unstructured"),
+        "processors": {},
+    }
+
+    # Unstructured configuration
+    if os.getenv("ENABLE_UNSTRUCTURED", "false").lower() == "true":
+        config["processors"]["unstructured"] = {
+            "api_url": os.getenv("UNSTRUCTURED_API_URL", "http://unstructured:8000"),
+            "timeout": int(os.getenv("UNSTRUCTURED_TIMEOUT", "120")),
+            "strategy": os.getenv("UNSTRUCTURED_STRATEGY", "auto"),
+            "languages": [
+                lang.strip()
+                for lang in os.getenv("UNSTRUCTURED_LANGUAGES", "eng,deu").split(",")
+                if lang.strip()
+            ],
+            "progress_interval": int(os.getenv("PROGRESS_INTERVAL", "10")),
+        }
+
+    # Tesseract configuration
+    if os.getenv("ENABLE_TESSERACT", "false").lower() == "true":
+        config["processors"]["tesseract"] = {
+            "tesseract_cmd": os.getenv("TESSERACT_CMD"),  # None = auto-detect
+            "lang": os.getenv("TESSERACT_LANG", "eng"),
+        }
+
+    # Custom processor (via HTTP API)
+    if os.getenv("ENABLE_CUSTOM_PROCESSOR", "false").lower() == "true":
+        custom_url = os.getenv("CUSTOM_PROCESSOR_URL")
+        if custom_url:
+            supported_types_str = os.getenv("CUSTOM_PROCESSOR_TYPES", "application/pdf")
+            supported_types = {
+                t.strip() for t in supported_types_str.split(",") if t.strip()
+            }
+
+            config["processors"]["custom"] = {
+                "name": os.getenv("CUSTOM_PROCESSOR_NAME", "custom"),
+                "api_url": custom_url,
+                "api_key": os.getenv("CUSTOM_PROCESSOR_API_KEY"),
+                "timeout": int(os.getenv("CUSTOM_PROCESSOR_TIMEOUT", "60")),
+                "supported_types": supported_types,
+            }
+
+    return config

nextcloud_mcp_server/document_processors/__init__.py

@@ -0,0 +1,12 @@
+"""Document processing plugins for extracting text from various file formats."""
+
+from .base import DocumentProcessor, ProcessingResult, ProcessorError
+from .registry import ProcessorRegistry, get_registry
+
+__all__ = [
+    "DocumentProcessor",
+    "ProcessingResult",
+    "ProcessorError",
+    "ProcessorRegistry",
+    "get_registry",
+]

nextcloud_mcp_server/document_processors/base.py

@@ -0,0 +1,126 @@
+"""Abstract base class for document processing plugins."""
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+
+class ProcessingResult(BaseModel):
+    """Standardized result from any document processor."""
+
+    text: str
+    """Extracted text content"""
+
+    metadata: dict[str, Any]
+    """Processor-specific metadata"""
+
+    processor: str
+    """Name of processor that handled this (e.g., 'unstructured', 'tesseract')"""
+
+    success: bool = True
+    """Whether processing succeeded"""
+
+    error: Optional[str] = None
+    """Error message if processing failed"""
+
+
+class DocumentProcessor(ABC):
+    """Abstract base class for document processing plugins.
+
+    Document processors extract text from various file formats (PDF, DOCX, images, etc.).
+    Each processor implements this interface and can be registered with the ProcessorRegistry.
+
+    Example:
+        class MyProcessor(DocumentProcessor):
+            @property
+            def name(self) -> str:
+                return "my_processor"
+
+            @property
+            def supported_mime_types(self) -> set[str]:
+                return {"application/pdf", "image/jpeg"}
+
+            async def process(self, content: bytes, content_type: str, **kwargs) -> ProcessingResult:
+                # Extract text from content
+                return ProcessingResult(text="...", metadata={}, processor=self.name)
+
+            async def health_check(self) -> bool:
+                return True
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique identifier for this processor (e.g., 'unstructured', 'tesseract')."""
+        pass
+
+    @property
+    @abstractmethod
+    def supported_mime_types(self) -> set[str]:
+        """Set of MIME types this processor can handle.
+
+        Examples: {"application/pdf", "image/jpeg", "image/png"}
+        """
+        pass
+
+    @abstractmethod
+    async def process(
+        self,
+        content: bytes,
+        content_type: str,
+        filename: Optional[str] = None,
+        options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
+    ) -> ProcessingResult:
+        """Process a document and extract text.
+
+        Args:
+            content: Document bytes
+            content_type: MIME type of the document
+            filename: Optional filename for format detection
+            options: Processor-specific options (e.g., OCR language, strategy)
+            progress_callback: Optional async callback for progress updates.
+                Called as: await progress_callback(progress, total, message)
+                - progress: Current progress value (monotonically increasing)
+                - total: Optional total value (None if unknown)
+                - message: Optional human-readable status message
+
+        Returns:
+            ProcessingResult with extracted text and metadata
+
+        Raises:
+            ProcessorError: If processing fails
+        """
+        pass
+
+    @abstractmethod
+    async def health_check(self) -> bool:
+        """Check if processor is available and healthy.
+
+        Returns:
+            True if processor is ready to use, False otherwise
+        """
+        pass
+
+    def supports(self, content_type: str) -> bool:
+        """Check if this processor supports the given MIME type.
+
+        Args:
+            content_type: MIME type (may include parameters like "application/pdf; charset=utf-8")
+
+        Returns:
+            True if this processor can handle the type
+        """
+        # Strip parameters from content type
+        base_type = content_type.split(";")[0].strip().lower()
+        return base_type in self.supported_mime_types
+
+
+class ProcessorError(Exception):
+    """Raised when document processing fails."""
+
+    pass

nextcloud_mcp_server/document_processors/custom_http.py

@@ -0,0 +1,150 @@
+"""Generic HTTP API processor wrapper for custom document processing services."""
+
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, Optional
+
+import httpx
+
+from .base import DocumentProcessor, ProcessingResult, ProcessorError
+
+logger = logging.getLogger(__name__)
+
+
+class CustomHTTPProcessor(DocumentProcessor):
+    """Generic HTTP API processor wrapper.
+
+    Allows integration with any custom document processing API that follows
+    a simple request/response pattern. This makes it easy to integrate your
+    own text extraction services without writing a full processor.
+
+    Expected API Contract:
+        - POST request with file as multipart/form-data
+        - Response: {"text": "extracted text", "metadata": {...}}
+
+    Example:
+        processor = CustomHTTPProcessor(
+            name="my_ocr",
+            api_url="https://my-ocr-service.com/process",
+            api_key="secret",
+            supported_types={"application/pdf", "image/jpeg"},
+        )
+        result = await processor.process(pdf_bytes, "application/pdf")
+    """
+
+    def __init__(
+        self,
+        api_url: str,
+        api_key: Optional[str] = None,
+        timeout: int = 60,
+        supported_types: Optional[set[str]] = None,
+        name: str = "custom",
+    ):
+        """Initialize custom HTTP processor.
+
+        Args:
+            api_url: Your API endpoint (should accept POST with multipart/form-data)
+            api_key: Optional API key for authentication (sent as Bearer token)
+            timeout: Request timeout in seconds (default: 60)
+            supported_types: MIME types your API supports
+            name: Unique name for this processor (default: "custom")
+        """
+        self.api_url = api_url
+        self.api_key = api_key
+        self.timeout = timeout
+        self._name = name
+        self._supported_types = supported_types or set()
+
+        logger.info(f"Initialized CustomHTTPProcessor: {name} -> {api_url}")
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def supported_mime_types(self) -> set[str]:
+        return self._supported_types
+
+    async def process(
+        self,
+        content: bytes,
+        content_type: str,
+        filename: Optional[str] = None,
+        options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
+    ) -> ProcessingResult:
+        """Process via custom HTTP API.
+
+        Args:
+            content: Document bytes
+            content_type: MIME type
+            filename: Optional filename
+            options: Custom options (passed as form data to API)
+
+        Returns:
+            ProcessingResult with extracted text and metadata
+
+        Raises:
+            ProcessorError: If API call fails
+        """
+        options = options or {}
+
+        # Prepare request
+        files = {"file": (filename or "document", content, content_type)}
+        headers = {}
+
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(
+                    self.api_url,
+                    files=files,
+                    headers=headers,
+                    data=options,  # Pass options as form data
+                )
+                response.raise_for_status()
+
+                # Parse response
+                result = response.json()
+                text = result.get("text", "")
+                metadata = result.get("metadata", {})
+
+                logger.debug(
+                    f"Custom processor '{self.name}' extracted {len(text)} characters"
+                )
+
+                return ProcessingResult(
+                    text=text,
+                    metadata=metadata,
+                    processor=self.name,
+                    success=True,
+                )
+
+        except httpx.HTTPError as e:
+            logger.error(f"Custom processor '{self.name}' HTTP error: {e}")
+            raise ProcessorError(f"API call failed: {str(e)}") from e
+        except Exception as e:
+            logger.error(f"Custom processor '{self.name}' failed: {e}")
+            raise ProcessorError(f"Processing failed: {str(e)}") from e
+
+    async def health_check(self) -> bool:
+        """Check if custom API is available.
+
+        Returns:
+            True if API responds with status < 500
+        """
+        try:
+            async with httpx.AsyncClient(timeout=5) as client:
+                # Try GET request to check availability
+                response = await client.get(
+                    self.api_url,
+                    headers={"User-Agent": "nextcloud-mcp-server"},
+                )
+                return response.status_code < 500
+        except Exception as e:
+            logger.warning(f"Custom processor '{self.name}' health check failed: {e}")
+            return False

nextcloud_mcp_server/document_processors/registry.py

@@ -0,0 +1,171 @@
+"""Central registry for document processors."""
+
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, Optional
+
+from .base import DocumentProcessor, ProcessingResult, ProcessorError
+
+logger = logging.getLogger(__name__)
+
+
+class ProcessorRegistry:
+    """Central registry for document processors.
+
+    Manages registration and routing of document processing requests to
+    appropriate processors based on MIME types and priorities.
+
+    Example:
+        registry = ProcessorRegistry()
+        registry.register(UnstructuredProcessor(...), priority=10)
+        registry.register(TesseractProcessor(...), priority=5)
+
+        # Auto-select processor based on MIME type
+        result = await registry.process(pdf_bytes, "application/pdf")
+
+        # Force specific processor
+        result = await registry.process(img_bytes, "image/png", processor_name="tesseract")
+    """
+
+    def __init__(self):
+        self._processors: dict[str, tuple[DocumentProcessor, int]] = {}
+        self._priority_order: list[str] = []
+
+    def register(self, processor: DocumentProcessor, priority: int = 0):
+        """Register a document processor.
+
+        Args:
+            processor: Processor instance to register
+            priority: Higher priority processors are tried first (default: 0)
+        """
+        name = processor.name
+
+        if name in self._processors:
+            logger.warning(f"Processor '{name}' already registered, replacing")
+
+        self._processors[name] = (processor, priority)
+
+        # Update priority order
+        if name in self._priority_order:
+            self._priority_order.remove(name)
+
+        # Insert in priority order (higher priority first)
+        inserted = False
+        for i, existing_name in enumerate(self._priority_order):
+            existing_priority = self._processors[existing_name][1]
+            if priority > existing_priority:
+                self._priority_order.insert(i, name)
+                inserted = True
+                break
+
+        if not inserted:
+            self._priority_order.append(name)
+
+        logger.info(
+            f"Registered processor: {name} "
+            f"(priority={priority}, supports={len(processor.supported_mime_types)} types)"
+        )
+
+    def get_processor(self, name: str) -> Optional[DocumentProcessor]:
+        """Get a processor by name.
+
+        Args:
+            name: Processor name
+
+        Returns:
+            DocumentProcessor instance or None if not found
+        """
+        if name in self._processors:
+            return self._processors[name][0]
+        return None
+
+    def find_processor(self, content_type: str) -> Optional[DocumentProcessor]:
+        """Find the first processor that supports the given MIME type.
+
+        Processors are checked in priority order (highest priority first).
+
+        Args:
+            content_type: MIME type to match
+
+        Returns:
+            First matching processor or None
+        """
+        for name in self._priority_order:
+            processor = self._processors[name][0]
+            if processor.supports(content_type):
+                logger.debug(f"Found processor '{name}' for type '{content_type}'")
+                return processor
+
+        logger.debug(f"No processor found for type '{content_type}'")
+        return None
+
+    def list_processors(self) -> list[str]:
+        """List all registered processor names in priority order.
+
+        Returns:
+            List of processor names (highest priority first)
+        """
+        return list(self._priority_order)
+
+    async def process(
+        self,
+        content: bytes,
+        content_type: str,
+        filename: Optional[str] = None,
+        processor_name: Optional[str] = None,
+        options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
+    ) -> ProcessingResult:
+        """Process a document using available processors.
+
+        Args:
+            content: Document bytes
+            content_type: MIME type
+            filename: Optional filename for format detection
+            processor_name: Force specific processor (or None for auto-select)
+            options: Processing options passed to processor
+            progress_callback: Optional async callback for progress updates
+
+        Returns:
+            ProcessingResult with extracted text and metadata
+
+        Raises:
+            ProcessorError: If no processor found or processing fails
+        """
+        # Find processor
+        if processor_name:
+            processor = self.get_processor(processor_name)
+            if not processor:
+                raise ProcessorError(
+                    f"Processor '{processor_name}' not found. "
+                    f"Available: {', '.join(self.list_processors())}"
+                )
+        else:
+            processor = self.find_processor(content_type)
+            if not processor:
+                raise ProcessorError(
+                    f"No processor found for type: {content_type}. "
+                    f"Registered processors: {', '.join(self.list_processors())}"
+                )
+
+        logger.info(f"Processing with '{processor.name}' processor")
+
+        # Process
+        return await processor.process(
+            content, content_type, filename, options, progress_callback
+        )
+
+
+# Global registry instance
+_registry = ProcessorRegistry()
+
+
+def get_registry() -> ProcessorRegistry:
+    """Get the global processor registry.
+
+    Returns:
+        Singleton ProcessorRegistry instance
+    """
+    return _registry

nextcloud_mcp_server/document_processors/tesseract.py

@@ -0,0 +1,165 @@
+"""Document processor using Tesseract OCR (local)."""
+
+import logging
+import shutil
+from collections.abc import Awaitable, Callable
+from typing import Any, Optional
+
+from .base import DocumentProcessor, ProcessingResult, ProcessorError
+
+logger = logging.getLogger(__name__)
+
+try:
+    import io
+
+    import pytesseract
+    from PIL import Image
+
+    TESSERACT_AVAILABLE = True
+except ImportError:
+    TESSERACT_AVAILABLE = False
+
+
+class TesseractProcessor(DocumentProcessor):
+    """Document processor using Tesseract OCR (local).
+
+    This processor runs OCR locally using the Tesseract engine, which is
+    faster and more lightweight than cloud-based solutions but requires
+    Tesseract to be installed on the system.
+
+    Requirements:
+        - tesseract binary installed (e.g., apt install tesseract-ocr)
+        - Python packages: pip install pytesseract pillow
+
+    Example:
+        processor = TesseractProcessor(default_lang="eng+deu")
+        result = await processor.process(image_bytes, "image/jpeg")
+    """
+
+    SUPPORTED_TYPES = {
+        "image/jpeg",
+        "image/png",
+        "image/tiff",
+        "image/bmp",
+        "image/gif",
+    }
+
+    def __init__(
+        self,
+        tesseract_cmd: Optional[str] = None,
+        default_lang: str = "eng",
+    ):
+        """Initialize Tesseract processor.
+
+        Args:
+            tesseract_cmd: Path to tesseract executable (None = auto-detect)
+            default_lang: Default OCR language (e.g., "eng", "deu", "eng+deu")
+
+        Raises:
+            ProcessorError: If Tesseract or required packages not available
+        """
+        if not TESSERACT_AVAILABLE:
+            raise ProcessorError(
+                "Tesseract processor requires: pip install pytesseract pillow"
+            )
+
+        if tesseract_cmd:
+            pytesseract.pytesseract.tesseract_cmd = tesseract_cmd
+        elif not shutil.which("tesseract"):
+            raise ProcessorError(
+                "Tesseract not found in PATH. Install with: apt install tesseract-ocr"
+            )
+
+        self.default_lang = default_lang
+        logger.info(f"Initialized TesseractProcessor: lang={default_lang}")
+
+    @property
+    def name(self) -> str:
+        return "tesseract"
+
+    @property
+    def supported_mime_types(self) -> set[str]:
+        return self.SUPPORTED_TYPES
+
+    async def process(
+        self,
+        content: bytes,
+        content_type: str,
+        filename: Optional[str] = None,
+        options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
+    ) -> ProcessingResult:
+        """Process image via Tesseract OCR.
+
+        Args:
+            content: Image bytes
+            content_type: Image MIME type
+            filename: Optional filename
+            options: Processing options:
+                - lang: OCR language(s) (default: from init)
+                - config: Tesseract config string
+
+        Returns:
+            ProcessingResult with extracted text and metadata
+
+        Raises:
+            ProcessorError: If OCR fails
+        """
+        options = options or {}
+        lang = options.get("lang", self.default_lang)
+        config = options.get("config", "")
+
+        try:
+            # Load image
+            image = Image.open(io.BytesIO(content))
+
+            # Run OCR
+            text = pytesseract.image_to_string(image, lang=lang, config=config)
+
+            # Get additional data for confidence scores
+            data = pytesseract.image_to_data(
+                image, lang=lang, output_type=pytesseract.Output.DICT
+            )
+
+            # Calculate average confidence
+            confidences = [c for c in data["conf"] if c != -1]
+            avg_confidence = sum(confidences) / len(confidences) if confidences else 0
+
+            metadata = {
+                "text_length": len(text),
+                "language": lang,
+                "image_size": image.size,
+                "image_mode": image.mode,
+                "confidence": round(avg_confidence, 2),
+                "words_detected": len([c for c in data["conf"] if c != -1]),
+            }
+
+            logger.debug(
+                f"Tesseract OCR completed: {len(text)} chars, "
+                f"confidence={avg_confidence:.1f}%"
+            )
+
+            return ProcessingResult(
+                text=text.strip(),
+                metadata=metadata,
+                processor=self.name,
+                success=True,
+            )
+
+        except Exception as e:
+            logger.error(f"Tesseract processing failed: {e}")
+            raise ProcessorError(f"OCR failed: {str(e)}") from e
+
+    async def health_check(self) -> bool:
+        """Check if Tesseract is available.
+
+        Returns:
+            True if Tesseract is installed and working
+        """
+        try:
+            pytesseract.get_tesseract_version()
+            return True
+        except Exception:
+            return False

nextcloud_mcp_server/document_processors/unstructured.py

@@ -0,0 +1,310 @@
+"""Document processor using Unstructured.io API."""
+
+import io
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any, Optional
+
+import anyio
+import httpx
+
+from .base import DocumentProcessor, ProcessingResult, ProcessorError
+
+logger = logging.getLogger(__name__)
+
+
+class UnstructuredProcessor(DocumentProcessor):
+    """Document processor using Unstructured.io API.
+
+    The Unstructured API provides document parsing capabilities for various formats
+    including PDF, DOCX, images with OCR, and more.
+
+    API Documentation: https://docs.unstructured.io/api-reference/api-services/api-parameters
+    """
+
+    # Supported MIME types for Unstructured
+    SUPPORTED_TYPES = {
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/msword",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        "application/vnd.ms-powerpoint",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "application/vnd.ms-excel",
+        "application/rtf",
+        "text/rtf",
+        "application/vnd.oasis.opendocument.text",
+        "application/epub+zip",
+        "message/rfc822",
+        "application/vnd.ms-outlook",
+        "image/jpeg",
+        "image/png",
+        "image/tiff",
+        "image/bmp",
+    }
+
+    def __init__(
+        self,
+        api_url: str,
+        timeout: int = 120,
+        default_strategy: str = "auto",
+        default_languages: Optional[list[str]] = None,
+        progress_interval: int = 10,
+    ):
+        """Initialize Unstructured processor.
+
+        Args:
+            api_url: Unstructured API endpoint
+            timeout: Request timeout in seconds (default: 120)
+            default_strategy: Default parsing strategy - "auto", "fast", or "hi_res"
+            default_languages: Default OCR language codes (e.g., ["eng", "deu"])
+            progress_interval: Seconds between progress updates (default: 10)
+        """
+        self.api_url = api_url
+        self.timeout = timeout
+        self.default_strategy = default_strategy
+        self.default_languages = default_languages or ["eng"]
+        self.progress_interval = progress_interval
+
+        logger.info(
+            f"Initialized UnstructuredProcessor: {api_url}, "
+            f"strategy={default_strategy}, languages={self.default_languages}, "
+            f"progress_interval={progress_interval}s"
+        )
+
+    @property
+    def name(self) -> str:
+        return "unstructured"
+
+    @property
+    def supported_mime_types(self) -> set[str]:
+        return self.SUPPORTED_TYPES
+
+    async def _run_progress_poller(
+        self,
+        stop_event: anyio.Event,
+        progress_callback: Callable[
+            [float, Optional[float], Optional[str]], Awaitable[None]
+        ],
+        start_time: float,
+    ):
+        """Run progress poller that reports status every N seconds.
+
+        Args:
+            stop_event: Event to signal when processing is complete
+            progress_callback: Async callback to report progress
+            start_time: Time when processing started (from time.time())
+        """
+        logger.debug("Starting progress poller")
+        while not stop_event.is_set():
+            try:
+                # Wait for the event to be set, with a timeout equal to progress_interval
+                with anyio.fail_after(self.progress_interval):
+                    await stop_event.wait()
+                # If wait() finished, the event was set (processing complete)
+                break
+            except TimeoutError:
+                # Timeout occurred - time to send a progress update
+                if not stop_event.is_set():  # Double-check in case of race condition
+                    elapsed = int(time.time() - start_time)
+                    message = (
+                        f"Processing document with unstructured... ({elapsed}s elapsed)"
+                    )
+                    try:
+                        await progress_callback(
+                            progress=float(elapsed),
+                            total=None,  # Unknown total duration
+                            message=message,
+                        )
+                        logger.debug(f"Progress update sent: {elapsed}s elapsed")
+                    except Exception as e:
+                        logger.warning(f"Failed to send progress update: {e}")
+        logger.debug("Progress poller stopped")
+
+    async def _make_api_request(
+        self,
+        content: bytes,
+        content_type: str,
+        filename: Optional[str],
+        strategy: str,
+        languages: list[str],
+        extract_image_block_types: Optional[list[str]],
+    ) -> ProcessingResult:
+        """Make the actual API request to Unstructured.
+
+        Args:
+            content: Document bytes
+            content_type: MIME type
+            filename: Optional filename
+            strategy: Processing strategy
+            languages: OCR languages
+            extract_image_block_types: Image element types to extract
+
+        Returns:
+            ProcessingResult with extracted text and metadata
+
+        Raises:
+            ProcessorError: If processing fails
+        """
+        # Prepare multipart request
+        files = {
+            "files": (
+                filename or "document",
+                io.BytesIO(content),
+                content_type or "application/octet-stream",
+            )
+        }
+
+        data = {
+            "strategy": strategy,
+            "languages": ",".join(languages),
+        }
+
+        if extract_image_block_types:
+            data["extract_image_block_types"] = ",".join(extract_image_block_types)
+
+        logger.debug(
+            f"Processing with Unstructured API: strategy={strategy}, languages={languages}"
+        )
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(
+                    f"{self.api_url}/general/v0/general",
+                    files=files,
+                    data=data,
+                )
+                response.raise_for_status()
+
+                # Parse response
+                elements = response.json()
+
+                # Extract text and metadata
+                texts = []
+                element_types: dict[str, int] = {}
+
+                for element in elements:
+                    if "text" in element and element["text"]:
+                        texts.append(element["text"])
+
+                    el_type = element.get("type", "unknown")
+                    element_types[el_type] = element_types.get(el_type, 0) + 1
+
+                parsed_text = "\n\n".join(texts)
+
+                metadata = {
+                    "element_count": len(elements),
+                    "text_length": len(parsed_text),
+                    "element_types": element_types,
+                    "strategy": strategy,
+                    "languages": languages,
+                }
+
+                logger.debug(
+                    f"Successfully processed: {len(elements)} elements, "
+                    f"{len(parsed_text)} characters"
+                )
+
+                return ProcessingResult(
+                    text=parsed_text,
+                    metadata=metadata,
+                    processor=self.name,
+                    success=True,
+                )
+
+        except httpx.HTTPError as e:
+            logger.error(f"Unstructured API HTTP error: {e}")
+            raise ProcessorError(f"HTTP error: {str(e)}") from e
+        except Exception as e:
+            logger.error(f"Unstructured API processing failed: {e}")
+            raise ProcessorError(f"Processing failed: {str(e)}") from e
+
+    async def process(
+        self,
+        content: bytes,
+        content_type: str,
+        filename: Optional[str] = None,
+        options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
+    ) -> ProcessingResult:
+        """Process document via Unstructured API.
+
+        Args:
+            content: Document bytes
+            content_type: MIME type
+            filename: Optional filename for format detection
+            options: Processing options:
+                - strategy: "auto", "fast", or "hi_res" (default: from init)
+                - languages: List of language codes (default: from init)
+                - extract_image_block_types: Types of image elements to extract
+            progress_callback: Optional async callback for progress updates
+
+        Returns:
+            ProcessingResult with extracted text and metadata
+
+        Raises:
+            ProcessorError: If processing fails
+        """
+        options = options or {}
+
+        # Extract options with defaults
+        strategy = options.get("strategy", self.default_strategy)
+        languages = options.get("languages", self.default_languages)
+        extract_image_block_types = options.get("extract_image_block_types")
+
+        # If no progress callback, just make the request directly
+        if progress_callback is None:
+            return await self._make_api_request(
+                content=content,
+                content_type=content_type,
+                filename=filename,
+                strategy=strategy,
+                languages=languages,
+                extract_image_block_types=extract_image_block_types,
+            )
+
+        # With progress callback: run API request + progress poller concurrently
+        stop_event = anyio.Event()
+        start_time = time.time()
+        result = None
+
+        async def capture_result():
+            nonlocal result
+            try:
+                result = await self._make_api_request(
+                    content=content,
+                    content_type=content_type,
+                    filename=filename,
+                    strategy=strategy,
+                    languages=languages,
+                    extract_image_block_types=extract_image_block_types,
+                )
+            finally:
+                # Signal poller to stop after API request completes
+                stop_event.set()
+
+        # Run both tasks concurrently using anyio task groups
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(capture_result)
+            tg.start_soon(
+                self._run_progress_poller, stop_event, progress_callback, start_time
+            )
+
+        return result
+
+    async def health_check(self) -> bool:
+        """Check if Unstructured API is available.
+
+        Returns:
+            True if API is healthy, False otherwise
+        """
+        try:
+            async with httpx.AsyncClient(timeout=5) as client:
+                response = await client.get(f"{self.api_url}/healthcheck")
+                return response.status_code == 200
+        except Exception as e:
+            logger.warning(f"Unstructured health check failed: {e}")
+            return False

nextcloud_mcp_server/models/cookbook.py

@@ -2,7 +2,7 @@
 
 from typing import List, Optional, Union
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 from .base import BaseResponse, IdResponse, StatusResponse
 
@@ -38,8 +38,7 @@ class Nutrition(BaseModel):
         None, description="Unsaturated fat (e.g., '40 g')"
     )
 
-    class Config:
-        populate_by_name = True
+    model_config = ConfigDict(populate_by_name=True)
 
 
 class RecipeStub(BaseModel):
@@ -91,9 +90,7 @@ class Recipe(BaseModel):
     )
     nutrition: Optional[Nutrition] = Field(None, description="Nutrition information")
 
-    class Config:
-        populate_by_name = True
-        extra = "allow"  # Allow additional schema.org fields
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
 
 
 class Category(BaseModel):
@@ -127,8 +124,7 @@ class VisibleInfoBlocks(BaseModel):
     )
     tools: Optional[bool] = Field(None, description="Show tools list")
 
-    class Config:
-        populate_by_name = True
+    model_config = ConfigDict(populate_by_name=True)
 
 
 class CookbookConfig(BaseModel):

nextcloud_mcp_server/models/webdav.py

@@ -40,7 +40,7 @@ class DirectoryListing(BaseResponse):
     """Response model for directory listings."""
 
     path: str = Field(description="Directory path")
-    items: List[FileInfo] = Field(description="Files and directories in the path")
+    files: List[FileInfo] = Field(description="Files and directories in the path")
     total_count: int = Field(description="Total number of items")
     directories_count: int = Field(description="Number of directories")
     files_count: int = Field(description="Number of files")

nextcloud_mcp_server/server/calendar.py

@@ -19,7 +19,7 @@ logger = logging.getLogger(__name__)
 def configure_calendar_tools(mcp: FastMCP):
     # Calendar tools
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("calendar:read")
     async def nc_calendar_list_calendars(ctx: Context) -> ListCalendarsResponse:
         """List all available calendars for the user"""
         client = get_client(ctx)
@@ -29,7 +29,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return ListCalendarsResponse(calendars=calendars, total_count=len(calendars))
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("calendar:write")
     async def nc_calendar_create_event(
         calendar_name: str,
         title: str,
@@ -105,7 +105,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return await client.calendar.create_event(calendar_name, event_data)
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("calendar:read")
     async def nc_calendar_list_events(
         calendar_name: str,
         ctx: Context,
@@ -207,7 +207,7 @@ def configure_calendar_tools(mcp: FastMCP):
             return events
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("calendar:read")
     async def nc_calendar_get_event(
         calendar_name: str,
         event_uid: str,
@@ -219,7 +219,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return event_data
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("calendar:write")
     async def nc_calendar_update_event(
         calendar_name: str,
         event_uid: str,
@@ -292,7 +292,7 @@ def configure_calendar_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("calendar:write")
     async def nc_calendar_delete_event(
         calendar_name: str,
         event_uid: str,
@@ -303,7 +303,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return await client.calendar.delete_event(calendar_name, event_uid)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("calendar:write")
     async def nc_calendar_create_meeting(
         title: str,
         date: str,
@@ -369,7 +369,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return await client.calendar.create_event(calendar_name, event_data)
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("calendar:read")
     async def nc_calendar_get_upcoming_events(
         ctx: Context,
         calendar_name: str = "",  # Empty = all calendars
@@ -419,7 +419,7 @@ def configure_calendar_tools(mcp: FastMCP):
             return all_events[:limit]
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("calendar:read")
     async def nc_calendar_find_availability(
         duration_minutes: int,
         ctx: Context,
@@ -499,7 +499,7 @@ def configure_calendar_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("calendar:write")
     async def nc_calendar_bulk_operations(
         operation: str,  # "update", "delete", "move"
         ctx: Context,
@@ -748,7 +748,7 @@ def configure_calendar_tools(mcp: FastMCP):
             }
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("calendar:write")
     async def nc_calendar_manage_calendar(
         action: str,  # "create", "delete", "update", "list"
         ctx: Context,
@@ -817,7 +817,7 @@ def configure_calendar_tools(mcp: FastMCP):
     # ============= Todo/Task Tools =============
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("todo:read", "calendar:read")
     async def nc_calendar_list_todos(
         calendar_name: str,
         ctx: Context,
@@ -862,7 +862,7 @@ def configure_calendar_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("todo:write", "calendar:read")
     async def nc_calendar_create_todo(
         calendar_name: str,
         summary: str,
@@ -905,7 +905,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return await client.calendar.create_todo(calendar_name, todo_data)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("todo:write", "calendar:read")
     async def nc_calendar_update_todo(
         calendar_name: str,
         todo_uid: str,
@@ -965,7 +965,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return await client.calendar.update_todo(calendar_name, todo_uid, todo_data)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("todo:write", "calendar:read")
     async def nc_calendar_delete_todo(
         calendar_name: str,
         todo_uid: str,
@@ -985,7 +985,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return await client.calendar.delete_todo(calendar_name, todo_uid)
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("todo:read", "calendar:read")
     async def nc_calendar_search_todos(
         ctx: Context,
         status: Optional[str] = None,

nextcloud_mcp_server/server/contacts.py

@@ -11,21 +11,21 @@ logger = logging.getLogger(__name__)
 def configure_contacts_tools(mcp: FastMCP):
     # Contacts tools
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("contacts:read")
     async def nc_contacts_list_addressbooks(ctx: Context):
         """List all addressbooks for the user."""
         client = get_client(ctx)
         return await client.contacts.list_addressbooks()
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("contacts:read")
     async def nc_contacts_list_contacts(ctx: Context, *, addressbook: str):
         """List all contacts in the specified addressbook."""
         client = get_client(ctx)
         return await client.contacts.list_contacts(addressbook=addressbook)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("contacts:write")
     async def nc_contacts_create_addressbook(
         ctx: Context, *, name: str, display_name: str
     ):
@@ -41,14 +41,14 @@ def configure_contacts_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("contacts:write")
     async def nc_contacts_delete_addressbook(ctx: Context, *, name: str):
         """Delete an addressbook."""
         client = get_client(ctx)
         return await client.contacts.delete_addressbook(name=name)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("contacts:write")
     async def nc_contacts_create_contact(
         ctx: Context, *, addressbook: str, uid: str, contact_data: dict
     ):
@@ -65,14 +65,14 @@ def configure_contacts_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("contacts:write")
     async def nc_contacts_delete_contact(ctx: Context, *, addressbook: str, uid: str):
         """Delete a contact."""
         client = get_client(ctx)
         return await client.contacts.delete_contact(addressbook=addressbook, uid=uid)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("contacts:write")
     async def nc_contacts_update_contact(
         ctx: Context, *, addressbook: str, uid: str, contact_data: dict, etag: str = ""
     ):

nextcloud_mcp_server/server/cookbook.py

@@ -71,7 +71,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("cookbook:write")
     async def nc_cookbook_import_recipe(url: str, ctx: Context) -> ImportRecipeResponse:
         """Import a recipe from a URL using schema.org metadata.
 
@@ -128,7 +128,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("cookbook:read")
     async def nc_cookbook_list_recipes(ctx: Context) -> ListRecipesResponse:
         """Get all recipes in the database"""
         client = get_client(ctx)
@@ -153,7 +153,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("cookbook:read")
     async def nc_cookbook_get_recipe(recipe_id: int, ctx: Context) -> Recipe:
         """Get a specific recipe by its ID"""
         client = get_client(ctx)
@@ -178,7 +178,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("cookbook:write")
     async def nc_cookbook_create_recipe(
         name: str,
         description: str | None = None,
@@ -257,7 +257,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("cookbook:write")
     async def nc_cookbook_update_recipe(
         recipe_id: int,
         name: str | None = None,
@@ -346,7 +346,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("cookbook:write")
     async def nc_cookbook_delete_recipe(
         recipe_id: int, ctx: Context
     ) -> DeleteRecipeResponse:
@@ -381,7 +381,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("cookbook:read")
     async def nc_cookbook_search_recipes(
         query: str, ctx: Context
     ) -> SearchRecipesResponse:
@@ -417,7 +417,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("cookbook:read")
     async def nc_cookbook_list_categories(ctx: Context) -> ListCategoriesResponse:
         """Get all known categories.
 
@@ -444,7 +444,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("cookbook:read")
     async def nc_cookbook_get_recipes_in_category(
         category: str, ctx: Context
     ) -> ListRecipesResponse:
@@ -480,7 +480,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("cookbook:read")
     async def nc_cookbook_list_keywords(ctx: Context) -> ListKeywordsResponse:
         """Get all known keywords/tags"""
         client = get_client(ctx)
@@ -505,7 +505,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("cookbook:read")
     async def nc_cookbook_get_recipes_with_keywords(
         keywords: list[str], ctx: Context
     ) -> ListRecipesResponse:
@@ -539,7 +539,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("cookbook:write")
     async def nc_cookbook_set_config(
         folder: str | None = None,
         update_interval: int | None = None,
@@ -582,7 +582,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("cookbook:write")
     async def nc_cookbook_reindex(ctx: Context) -> ReindexResponse:
         """Trigger a rescan of all recipes into the caching database.
 

nextcloud_mcp_server/server/deck.py

@@ -117,7 +117,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Read Tools (converted from resources)
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("deck:read")
     async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
         """Get all Nextcloud Deck boards"""
         client = get_client(ctx)
@@ -125,7 +125,7 @@ def configure_deck_tools(mcp: FastMCP):
         return boards
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("deck:read")
     async def deck_get_board(ctx: Context, board_id: int) -> DeckBoard:
         """Get details of a specific Nextcloud Deck board"""
         client = get_client(ctx)
@@ -133,7 +133,7 @@ def configure_deck_tools(mcp: FastMCP):
         return board
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("deck:read")
     async def deck_get_stacks(ctx: Context, board_id: int) -> list[DeckStack]:
         """Get all stacks in a Nextcloud Deck board"""
         client = get_client(ctx)
@@ -141,7 +141,7 @@ def configure_deck_tools(mcp: FastMCP):
         return stacks
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("deck:read")
     async def deck_get_stack(ctx: Context, board_id: int, stack_id: int) -> DeckStack:
         """Get details of a specific Nextcloud Deck stack"""
         client = get_client(ctx)
@@ -149,7 +149,7 @@ def configure_deck_tools(mcp: FastMCP):
         return stack
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("deck:read")
     async def deck_get_cards(
         ctx: Context, board_id: int, stack_id: int
     ) -> list[DeckCard]:
@@ -161,7 +161,7 @@ def configure_deck_tools(mcp: FastMCP):
         return []
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("deck:read")
     async def deck_get_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> DeckCard:
@@ -171,7 +171,7 @@ def configure_deck_tools(mcp: FastMCP):
         return card
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("deck:read")
     async def deck_get_labels(ctx: Context, board_id: int) -> list[DeckLabel]:
         """Get all labels in a Nextcloud Deck board"""
         client = get_client(ctx)
@@ -179,7 +179,7 @@ def configure_deck_tools(mcp: FastMCP):
         return board.labels
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("deck:read")
     async def deck_get_label(ctx: Context, board_id: int, label_id: int) -> DeckLabel:
         """Get details of a specific Nextcloud Deck label"""
         client = get_client(ctx)
@@ -189,7 +189,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Create/Update/Delete Tools
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_create_board(
         ctx: Context, title: str, color: str
     ) -> CreateBoardResponse:
@@ -206,7 +206,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Stack Tools
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_create_stack(
         ctx: Context, board_id: int, title: str, order: int
     ) -> CreateStackResponse:
@@ -222,7 +222,7 @@ def configure_deck_tools(mcp: FastMCP):
         return CreateStackResponse(id=stack.id, title=stack.title, order=stack.order)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_update_stack(
         ctx: Context,
         board_id: int,
@@ -248,7 +248,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_delete_stack(
         ctx: Context, board_id: int, stack_id: int
     ) -> StackOperationResponse:
@@ -269,7 +269,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Card Tools
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_create_card(
         ctx: Context,
         board_id: int,
@@ -303,7 +303,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_update_card(
         ctx: Context,
         board_id: int,
@@ -356,7 +356,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_delete_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> CardOperationResponse:
@@ -378,7 +378,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_archive_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> CardOperationResponse:
@@ -400,7 +400,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_unarchive_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> CardOperationResponse:
@@ -422,7 +422,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_reorder_card(
         ctx: Context,
         board_id: int,
@@ -454,7 +454,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Label Tools
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_create_label(
         ctx: Context, board_id: int, title: str, color: str
     ) -> CreateLabelResponse:
@@ -470,7 +470,7 @@ def configure_deck_tools(mcp: FastMCP):
         return CreateLabelResponse(id=label.id, title=label.title, color=label.color)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_update_label(
         ctx: Context,
         board_id: int,
@@ -496,7 +496,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_delete_label(
         ctx: Context, board_id: int, label_id: int
     ) -> LabelOperationResponse:
@@ -517,7 +517,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Card-Label Assignment Tools
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_assign_label_to_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int, label_id: int
     ) -> CardOperationResponse:
@@ -540,7 +540,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_remove_label_from_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int, label_id: int
     ) -> CardOperationResponse:
@@ -564,7 +564,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Card-User Assignment Tools
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_assign_user_to_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int, user_id: str
     ) -> CardOperationResponse:
@@ -587,7 +587,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("deck:write")
     async def deck_unassign_user_from_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int, user_id: str
     ) -> CardOperationResponse:

nextcloud_mcp_server/server/notes.py

@@ -85,11 +85,11 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("notes:write")
     async def nc_notes_create_note(
         title: str, content: str, category: str, ctx: Context
     ) -> CreateNoteResponse:
-        """Create a new note (requires nc:write scope)"""
+        """Create a new note (requires notes:write scope)"""
         client = get_client(ctx)
         try:
             note_data = await client.notes.create_note(
@@ -131,7 +131,7 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("notes:write")
     async def nc_notes_update_note(
         note_id: int,
         etag: str,
@@ -140,7 +140,7 @@ def configure_notes_tools(mcp: FastMCP):
         category: str | None,
         ctx: Context,
     ) -> UpdateNoteResponse:
-        """Update an existing note's title, content, or category (requires nc:write scope).
+        """Update an existing note's title, content, or category (requires notes:write scope).
 
         REQUIRED: etag parameter must be provided to prevent overwriting concurrent changes.
         Get the current ETag by first retrieving the note using nc_notes_get_note tool.
@@ -196,7 +196,7 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("notes:write")
     async def nc_notes_append_content(
         note_id: int, content: str, ctx: Context
     ) -> AppendContentResponse:
@@ -246,9 +246,9 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("notes:read")
     async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
-        """Search notes by title or content, returning only id, title, and category (requires nc:read scope)."""
+        """Search notes by title or content, returning only id, title, and category (requires notes:read scope)."""
         client = get_client(ctx)
         try:
             search_results_raw = await client.notes_search_notes(query=query)
@@ -292,9 +292,9 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("notes:read")
     async def nc_notes_get_note(note_id: int, ctx: Context) -> Note:
-        """Get a specific note by its ID (requires nc:read scope)"""
+        """Get a specific note by its ID (requires notes:read scope)"""
         client = get_client(ctx)
         try:
             note_data = await client.notes.get_note(note_id)
@@ -321,7 +321,7 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("notes:read")
     async def nc_notes_get_attachment(
         note_id: int, attachment_filename: str, ctx: Context
     ) -> dict[str, str]:
@@ -367,7 +367,7 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("notes:write")
     async def nc_notes_delete_note(note_id: int, ctx: Context) -> DeleteNoteResponse:
         """Delete a note permanently"""
         logger.info("Deleting note %s", note_id)

nextcloud_mcp_server/server/sharing.py

@@ -16,7 +16,7 @@ def configure_sharing_tools(mcp: FastMCP):
     """
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("sharing:write")
     async def nc_share_create(
         path: str,
         share_with: str,
@@ -55,7 +55,7 @@ def configure_sharing_tools(mcp: FastMCP):
         return json.dumps(share_data, indent=2)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("sharing:write")
     async def nc_share_delete(share_id: int, ctx: Context) -> str:
         """Delete a share by its ID.
 
@@ -74,7 +74,7 @@ def configure_sharing_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("sharing:write")
     async def nc_share_get(share_id: int, ctx: Context) -> str:
         """Get information about a specific share.
 
@@ -92,7 +92,7 @@ def configure_sharing_tools(mcp: FastMCP):
         return json.dumps(share_data, indent=2)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("sharing:write")
     async def nc_share_list(
         ctx: Context, path: str | None = None, shared_with_me: bool = False
     ) -> str:
@@ -113,7 +113,7 @@ def configure_sharing_tools(mcp: FastMCP):
         return json.dumps(shares, indent=2)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("sharing:write")
     async def nc_share_update(share_id: int, permissions: int, ctx: Context) -> str:
         """Update the permissions of an existing share.
 

nextcloud_mcp_server/server/tables.py

@@ -11,21 +11,21 @@ logger = logging.getLogger(__name__)
 def configure_tables_tools(mcp: FastMCP):
     # Tables tools
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("tables:read")
     async def nc_tables_list_tables(ctx: Context):
         """List all tables available to the user"""
         client = get_client(ctx)
         return await client.tables.list_tables()
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("tables:read")
     async def nc_tables_get_schema(table_id: int, ctx: Context):
         """Get the schema/structure of a specific table including columns and views"""
         client = get_client(ctx)
         return await client.tables.get_table_schema(table_id)
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("tables:read")
     async def nc_tables_read_table(
         table_id: int,
         ctx: Context,
@@ -37,7 +37,7 @@ def configure_tables_tools(mcp: FastMCP):
         return await client.tables.get_table_rows(table_id, limit, offset)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("tables:write")
     async def nc_tables_insert_row(table_id: int, data: dict, ctx: Context):
         """Insert a new row into a table.
 
@@ -47,7 +47,7 @@ def configure_tables_tools(mcp: FastMCP):
         return await client.tables.create_row(table_id, data)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("tables:write")
     async def nc_tables_update_row(row_id: int, data: dict, ctx: Context):
         """Update an existing row in a table.
 
@@ -57,7 +57,7 @@ def configure_tables_tools(mcp: FastMCP):
         return await client.tables.update_row(row_id, data)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("tables:write")
     async def nc_tables_delete_row(row_id: int, ctx: Context):
         """Delete a row from a table"""
         client = get_client(ctx)

nextcloud_mcp_server/server/webdav.py

@@ -4,7 +4,11 @@ from mcp.server.fastmcp import Context, FastMCP
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
-from nextcloud_mcp_server.models import FileInfo, SearchFilesResponse
+from nextcloud_mcp_server.models import DirectoryListing, FileInfo, SearchFilesResponse
+from nextcloud_mcp_server.utils.document_parser import (
+    is_parseable_document,
+    parse_document,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -12,21 +16,40 @@ logger = logging.getLogger(__name__)
 def configure_webdav_tools(mcp: FastMCP):
     # WebDAV file system tools
     @mcp.tool()
-    @require_scopes("nc:read")
-    async def nc_webdav_list_directory(ctx: Context, path: str = ""):
+    @require_scopes("files:read")
+    async def nc_webdav_list_directory(
+        ctx: Context, path: str = ""
+    ) -> DirectoryListing:
         """List files and directories in the specified NextCloud path.
 
         Args:
             path: Directory path to list (empty string for root directory)
 
         Returns:
-            List of items with metadata including name, path, is_directory, size, content_type, last_modified
+            DirectoryListing with files, total_count, directories_count, files_count, and total_size
         """
         client = get_client(ctx)
-        return await client.webdav.list_directory(path)
+        items = await client.webdav.list_directory(path)
+
+        # Convert to FileInfo models
+        file_infos = [FileInfo(**item) for item in items]
+
+        # Calculate metadata
+        directories_count = sum(1 for f in file_infos if f.is_directory)
+        files_count = sum(1 for f in file_infos if not f.is_directory)
+        total_size = sum(f.size or 0 for f in file_infos if not f.is_directory)
+
+        return DirectoryListing(
+            path=path,
+            files=file_infos,
+            total_count=len(file_infos),
+            directories_count=directories_count,
+            files_count=files_count,
+            total_size=total_size,
+        )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("files:read")
     async def nc_webdav_read_file(path: str, ctx: Context):
         """Read the content of a file from NextCloud.
 
@@ -34,12 +57,53 @@ def configure_webdav_tools(mcp: FastMCP):
             path: Full path to the file to read
 
         Returns:
-            Dict with path, content, content_type, size, and encoding (if binary)
-            Text files are decoded to UTF-8, binary files are base64 encoded
+            Dict with path, content, content_type, size, and optional parsing metadata
+            - Text files are decoded to UTF-8
+            - Documents (PDF, DOCX, etc.) are parsed and text is extracted
+            - Other binary files are base64 encoded
+
+        Examples:
+            # Read a text file
+            result = await nc_webdav_read_file("Documents/readme.txt")
+            logger.info(result['content'])  # Decoded text content
+
+            # Read a PDF document (automatically parsed)
+            result = await nc_webdav_read_file("Documents/report.pdf")
+            logger.info(result['content'])  # Extracted text from PDF
+            logger.info(result['parsing_metadata'])  # Document parsing info
+
+            # Read a binary file
+            result = await nc_webdav_read_file("Images/photo.jpg")
+            logger.info(result['encoding'])  # 'base64'
         """
         client = get_client(ctx)
         content, content_type = await client.webdav.read_file(path)
 
+        # Check if this is a parseable document (PDF, DOCX, etc.)
+        # is_parseable_document() checks if document processing is enabled
+        if is_parseable_document(content_type):
+            try:
+                logger.info(f"Parsing document '{path}' of type '{content_type}'")
+                parsed_text, metadata = await parse_document(
+                    content,
+                    content_type,
+                    filename=path,
+                    progress_callback=ctx.report_progress,
+                )
+                return {
+                    "path": path,
+                    "content": parsed_text,
+                    "content_type": content_type,
+                    "size": len(content),
+                    "parsed": True,
+                    "parsing_metadata": metadata,
+                }
+            except Exception as e:
+                logger.warning(
+                    f"Failed to parse document '{path}', falling back to base64: {e}"
+                )
+                # Fall through to base64 encoding on parse failure
+
         # For text files, decode content for easier viewing
         if content_type and content_type.startswith("text/"):
             try:
@@ -65,7 +129,7 @@ def configure_webdav_tools(mcp: FastMCP):
         }
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("files:write")
     async def nc_webdav_write_file(
         path: str, content: str, ctx: Context, content_type: str | None = None
     ):
@@ -93,7 +157,7 @@ def configure_webdav_tools(mcp: FastMCP):
         return await client.webdav.write_file(path, content_bytes, content_type)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("files:write")
     async def nc_webdav_create_directory(path: str, ctx: Context):
         """Create a directory in NextCloud.
 
@@ -107,7 +171,7 @@ def configure_webdav_tools(mcp: FastMCP):
         return await client.webdav.create_directory(path)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("files:write")
     async def nc_webdav_delete_resource(path: str, ctx: Context):
         """Delete a file or directory in NextCloud.
 
@@ -121,7 +185,7 @@ def configure_webdav_tools(mcp: FastMCP):
         return await client.webdav.delete_resource(path)
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("files:write")
     async def nc_webdav_move_resource(
         source_path: str, destination_path: str, ctx: Context, overwrite: bool = False
     ):
@@ -141,7 +205,7 @@ def configure_webdav_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:write")
+    @require_scopes("files:write")
     async def nc_webdav_copy_resource(
         source_path: str, destination_path: str, ctx: Context, overwrite: bool = False
     ):
@@ -161,7 +225,7 @@ def configure_webdav_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("files:read")
     async def nc_webdav_search_files(
         ctx: Context,
         scope: str = "",
@@ -277,7 +341,7 @@ def configure_webdav_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("files:read")
     async def nc_webdav_find_by_name(
         pattern: str, ctx: Context, scope: str = "", limit: int | None = None
     ) -> SearchFilesResponse:
@@ -304,7 +368,7 @@ def configure_webdav_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("files:read")
     async def nc_webdav_find_by_type(
         mime_type: str, ctx: Context, scope: str = "", limit: int | None = None
     ) -> SearchFilesResponse:
@@ -331,7 +395,7 @@ def configure_webdav_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
-    @require_scopes("nc:read")
+    @require_scopes("files:read")
     async def nc_webdav_list_favorites(
         ctx: Context, scope: str = "", limit: int | None = None
     ) -> SearchFilesResponse:

nextcloud_mcp_server/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility functions for the Nextcloud MCP server."""

nextcloud_mcp_server/utils/document_parser.py

@@ -0,0 +1,100 @@
+"""Document parsing utilities using pluggable processor registry."""
+
+import base64
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Optional, Tuple
+
+from nextcloud_mcp_server.config import get_document_processor_config
+from nextcloud_mcp_server.document_processors import (
+    ProcessorError,
+    get_registry,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def is_parseable_document(content_type: Optional[str]) -> bool:
+    """Check if a document type can be parsed by any registered processor.
+
+    Args:
+        content_type: The MIME type of the document
+
+    Returns:
+        True if any processor can handle this type, False otherwise
+    """
+    if not content_type:
+        return False
+
+    config = get_document_processor_config()
+    if not config["enabled"]:
+        return False
+
+    registry = get_registry()
+    processor = registry.find_processor(content_type)
+    return processor is not None
+
+
+async def parse_document(
+    content: bytes,
+    content_type: Optional[str],
+    filename: Optional[str] = None,
+    progress_callback: Optional[
+        Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+    ] = None,
+) -> Tuple[str, dict]:
+    """Parse a document using registered processors.
+
+    This function uses the processor registry to find an appropriate
+    processor for the given document type and extract text from it.
+
+    Args:
+        content: The document content as bytes
+        content_type: The MIME type of the document
+        filename: Optional filename to help with format detection
+        progress_callback: Optional async callback for progress updates during long operations
+
+    Returns:
+        Tuple of (parsed_text, metadata) where:
+        - parsed_text: The extracted text content
+        - metadata: Additional metadata about the parsing
+
+    Raises:
+        ValueError: If the document type is not supported
+        Exception: If parsing fails
+    """
+    if not content_type:
+        raise ValueError("Content type is required for document parsing")
+
+    config = get_document_processor_config()
+    if not config["enabled"]:
+        raise ValueError("Document processing is disabled")
+
+    registry = get_registry()
+
+    logger.debug(f"Parsing document of type '{content_type}'")
+
+    try:
+        # Process using registry (auto-selects processor based on MIME type)
+        result = await registry.process(
+            content=content,
+            content_type=content_type,
+            filename=filename,
+            progress_callback=progress_callback,
+        )
+
+        logger.info(f"Successfully parsed document with '{result.processor}' processor")
+
+        return result.text, result.metadata
+
+    except ProcessorError as e:
+        logger.error(f"Document processing failed: {e}")
+        # Fallback to base64 with error metadata
+        parsed_text = f"Document could not be parsed. Base64 content: {base64.b64encode(content).decode('ascii')[:200]}..."
+        metadata = {
+            "mime_type": content_type,
+            "text_length": len(parsed_text),
+            "parsing_method": "fallback_base64",
+            "error": str(e),
+        }
+        return parsed_text, metadata

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.17.1"
+version = "0.22.0"
 description = "Model Context Protocol (MCP) server for Nextcloud integration - enables AI assistants to interact with Nextcloud data"
 authors = [
     {name = "Chris Coutinho", email = "chris@coutinho.io"}
@@ -10,7 +10,7 @@ license = {text = "AGPL-3.0-only"}
 requires-python = ">=3.11"
 keywords = ["nextcloud", "mcp", "model-context-protocol", "llm", "ai", "claude", "webdav", "caldav", "carddav"]
 dependencies = [
-    "mcp[cli] (>=1.18,<1.19)",
+    "mcp[cli] (>=1.19,<1.20)",
     "httpx (>=0.28.1,<0.29.0)",
     "pillow (>=12.0.0,<12.1.0)",
     "icalendar (>=6.0.0,<7.0.0)",
@@ -18,7 +18,7 @@ dependencies = [
     "pydantic>=2.11.4",
     "click>=8.1.8",
     "caldav",
-    "pyjwt[crypto]>=2.8.0",  # JWT validation with RSA support
+    "pyjwt[crypto]>=2.8.0", # Async I/O library for better compatibility
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -46,8 +46,10 @@ log_cli = 1
 log_cli_level = "ERROR"
 log_level = "ERROR"
 markers = [
-    "integration: marks tests as slow (deselect with '-m \"not slow\"')",
-    "oauth: marks tests as oauth (deselect with '-m \"not oauth\"')"
+    "unit: Fast unit tests with mocked dependencies",
+    "integration: Integration tests requiring Docker containers",
+    "oauth: OAuth tests requiring Playwright (slowest)",
+    "smoke: Critical path smoke tests for quick validation",
 ]
 testpaths = [
     "tests",
@@ -85,9 +87,11 @@ dev = [
     "playwright>=1.49.1",
     "pytest>=8.3.5",
     "pytest-cov>=6.1.1",
+    "pytest-mock>=3.15.1",
     "pytest-playwright-asyncio>=0.7.1",
     "pytest-timeout>=2.3.1",
     "ruff>=0.11.13",
+    "reportlab>=4.0.0",
 ]
 
 [project.scripts]

tests/client/conftest.py

@@ -0,0 +1,482 @@
+import httpx
+
+# ============================================================================
+# Mock Response Helpers for Unit Tests
+# ============================================================================
+
+
+def create_mock_response(
+    status_code: int = 200,
+    json_data: dict | list | None = None,
+    headers: dict | None = None,
+    content: bytes | None = None,
+) -> httpx.Response:
+    """Create a mock httpx.Response for testing.
+
+    Args:
+        status_code: HTTP status code
+        json_data: JSON data to return from response.json()
+        headers: Response headers
+        content: Raw response content (if not using json_data)
+
+    Returns:
+        Mock httpx.Response object
+    """
+    import json as json_module
+
+    if headers is None:
+        headers = {}
+
+    # If json_data is provided, serialize it to content
+    if json_data is not None:
+        content = json_module.dumps(json_data).encode("utf-8")
+        headers.setdefault("content-type", "application/json")
+
+    if content is None:
+        content = b""
+
+    # Create a mock request
+    request = httpx.Request("GET", "http://test.local/api")
+
+    # Create the response
+    return httpx.Response(
+        status_code=status_code,
+        headers=headers,
+        content=content,
+        request=request,
+    )
+
+
+def create_mock_note_response(
+    note_id: int = 1,
+    title: str = "Test Note",
+    content: str = "Test content",
+    category: str = "Test",
+    etag: str = "abc123",
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for a Nextcloud note.
+
+    Args:
+        note_id: Note ID
+        title: Note title
+        content: Note content
+        category: Note category
+        etag: ETag header value
+        **kwargs: Additional note fields
+
+    Returns:
+        Mock httpx.Response with note data
+    """
+    note_data = {
+        "id": note_id,
+        "title": title,
+        "content": content,
+        "category": category,
+        "etag": etag,
+        "modified": 1234567890,
+        "favorite": False,
+        **kwargs,
+    }
+
+    return create_mock_response(
+        status_code=200,
+        json_data=note_data,
+        headers={"etag": f'"{etag}"'},
+    )
+
+
+def create_mock_error_response(
+    status_code: int,
+    message: str = "Error",
+) -> httpx.Response:
+    """Create a mock error response.
+
+    Args:
+        status_code: HTTP error status code (e.g., 404, 412)
+        message: Error message
+
+    Returns:
+        Mock httpx.Response with error
+    """
+    return create_mock_response(
+        status_code=status_code,
+        json_data={"message": message},
+    )
+
+
+def create_mock_recipe_response(
+    recipe_id: int = 1,
+    name: str = "Test Recipe",
+    description: str = "Test description",
+    recipe_category: str = "Test",
+    keywords: str = "test",
+    recipe_yield: int = 4,
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for a Nextcloud Cookbook recipe.
+
+    Args:
+        recipe_id: Recipe ID
+        name: Recipe name
+        description: Recipe description
+        recipe_category: Recipe category
+        keywords: Recipe keywords (comma-separated)
+        recipe_yield: Recipe yield (number of servings)
+        **kwargs: Additional recipe fields (recipeIngredient, recipeInstructions, etc.)
+
+    Returns:
+        Mock httpx.Response with recipe data
+    """
+    recipe_data = {
+        "id": recipe_id,
+        "name": name,
+        "description": description,
+        "recipeCategory": recipe_category,
+        "keywords": keywords,
+        "recipeYield": recipe_yield,
+        "recipeIngredient": kwargs.get("recipeIngredient", []),
+        "recipeInstructions": kwargs.get("recipeInstructions", []),
+        "prepTime": kwargs.get("prepTime", "PT15M"),
+        "cookTime": kwargs.get("cookTime", "PT30M"),
+        "totalTime": kwargs.get("totalTime", "PT45M"),
+        "url": kwargs.get("url", ""),
+        **{
+            k: v
+            for k, v in kwargs.items()
+            if k
+            not in [
+                "recipeIngredient",
+                "recipeInstructions",
+                "prepTime",
+                "cookTime",
+                "totalTime",
+                "url",
+            ]
+        },
+    }
+
+    return create_mock_response(
+        status_code=200,
+        json_data=recipe_data,
+    )
+
+
+def create_mock_recipe_list_response(
+    recipes: list[dict] = None,
+) -> httpx.Response:
+    """Create a mock response for a list of recipe stubs.
+
+    Args:
+        recipes: List of recipe stub dictionaries. If None, returns empty list.
+
+    Returns:
+        Mock httpx.Response with recipe list data
+    """
+    if recipes is None:
+        recipes = []
+
+    return create_mock_response(
+        status_code=200,
+        json_data=recipes,
+    )
+
+
+def create_mock_deck_board_response(
+    board_id: int = 1,
+    title: str = "Test Board",
+    color: str = "0000FF",
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for a Nextcloud Deck board.
+
+    Args:
+        board_id: Board ID
+        title: Board title
+        color: Board color (hex without #)
+        **kwargs: Additional board fields
+
+    Returns:
+        Mock httpx.Response with board data
+    """
+    board_data = {
+        "id": board_id,
+        "title": title,
+        "color": color,
+        "owner": {
+            "primaryKey": "testuser",
+            "uid": "testuser",
+            "displayname": "Test User",
+        },
+        "archived": False,
+        "labels": [],
+        "acl": [],
+        "permissions": {
+            "PERMISSION_READ": True,
+            "PERMISSION_EDIT": True,
+            "PERMISSION_MANAGE": True,
+            "PERMISSION_SHARE": True,
+        },
+        "users": [],
+        "deletedAt": 0,
+        **kwargs,
+    }
+
+    return create_mock_response(status_code=200, json_data=board_data)
+
+
+def create_mock_deck_stack_response(
+    stack_id: int = 1,
+    title: str = "Test Stack",
+    board_id: int = 1,
+    order: int = 1,
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for a Nextcloud Deck stack.
+
+    Args:
+        stack_id: Stack ID
+        title: Stack title
+        board_id: Parent board ID
+        order: Stack order
+        **kwargs: Additional stack fields
+
+    Returns:
+        Mock httpx.Response with stack data
+    """
+    stack_data = {
+        "id": stack_id,
+        "title": title,
+        "boardId": board_id,
+        "order": order,
+        "deletedAt": 0,
+        **kwargs,
+    }
+
+    return create_mock_response(status_code=200, json_data=stack_data)
+
+
+def create_mock_deck_card_response(
+    card_id: int = 1,
+    title: str = "Test Card",
+    stack_id: int = 1,
+    description: str = "Test description",
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for a Nextcloud Deck card.
+
+    Args:
+        card_id: Card ID
+        title: Card title
+        stack_id: Parent stack ID
+        description: Card description
+        **kwargs: Additional card fields
+
+    Returns:
+        Mock httpx.Response with card data
+    """
+    card_data = {
+        "id": card_id,
+        "title": title,
+        "stackId": stack_id,
+        "type": "plain",
+        "order": 999,
+        "archived": False,
+        "owner": "testuser",
+        "description": description,
+        "labels": [],
+        "assignedUsers": [],
+        **kwargs,
+    }
+
+    return create_mock_response(status_code=200, json_data=card_data)
+
+
+def create_mock_deck_label_response(
+    label_id: int = 1,
+    title: str = "Test Label",
+    color: str = "FF0000",
+    board_id: int = 1,
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for a Nextcloud Deck label.
+
+    Args:
+        label_id: Label ID
+        title: Label title
+        color: Label color (hex without #)
+        board_id: Parent board ID
+        **kwargs: Additional label fields
+
+    Returns:
+        Mock httpx.Response with label data
+    """
+    label_data = {
+        "id": label_id,
+        "title": title,
+        "color": color,
+        "boardId": board_id,
+        **kwargs,
+    }
+
+    return create_mock_response(status_code=200, json_data=label_data)
+
+
+def create_mock_deck_comment_response(
+    comment_id: int = 1,
+    message: str = "Test comment",
+    card_id: int = 1,
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for a Nextcloud Deck comment (OCS format).
+
+    Args:
+        comment_id: Comment ID
+        message: Comment message
+        card_id: Parent card ID
+        **kwargs: Additional comment fields
+
+    Returns:
+        Mock httpx.Response with comment data in OCS format
+    """
+    comment_data = {
+        "id": comment_id,
+        "objectId": card_id,
+        "message": message,
+        "actorId": "testuser",
+        "actorDisplayName": "Test User",
+        "actorType": "users",
+        "creationDateTime": "2024-01-01T00:00:00+00:00",
+        "mentions": [],  # Required field
+        **kwargs,
+    }
+
+    # Wrap in OCS format
+    ocs_response = {"ocs": {"meta": {"status": "ok"}, "data": comment_data}}
+
+    return create_mock_response(status_code=200, json_data=ocs_response)
+
+
+def create_mock_tables_list_response(
+    tables: list[dict] = None,
+) -> httpx.Response:
+    """Create a mock response for list of Nextcloud Tables (OCS format).
+
+    Args:
+        tables: List of table dictionaries. If None, returns empty list.
+
+    Returns:
+        Mock httpx.Response with tables list data in OCS format
+    """
+    if tables is None:
+        tables = []
+
+    ocs_response = {"ocs": {"meta": {"status": "ok"}, "data": tables}}
+
+    return create_mock_response(status_code=200, json_data=ocs_response)
+
+
+def create_mock_table_schema_response(
+    table_id: int = 1,
+    columns: list[dict] = None,
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for Nextcloud Tables schema.
+
+    Args:
+        table_id: Table ID
+        columns: List of column definitions. If None, creates sample columns.
+        **kwargs: Additional schema fields
+
+    Returns:
+        Mock httpx.Response with table schema data
+    """
+    if columns is None:
+        columns = [
+            {"id": 1, "title": "Column 1", "type": "text"},
+            {"id": 2, "title": "Column 2", "type": "number"},
+        ]
+
+    schema_data = {
+        "id": table_id,
+        "columns": columns,
+        **kwargs,
+    }
+
+    return create_mock_response(status_code=200, json_data=schema_data)
+
+
+def create_mock_table_row_response(
+    row_id: int = 1,
+    table_id: int = 1,
+    data: list[dict] = None,
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for Nextcloud Tables row.
+
+    Args:
+        row_id: Row ID
+        table_id: Table ID
+        data: List of column data dicts. If None, creates sample data.
+        **kwargs: Additional row fields
+
+    Returns:
+        Mock httpx.Response with row data
+    """
+    if data is None:
+        data = [
+            {"columnId": 1, "value": "Test value"},
+            {"columnId": 2, "value": 42},
+        ]
+
+    row_data = {
+        "id": row_id,
+        "tableId": table_id,
+        "createdBy": "testuser",
+        "createdAt": "2024-01-01T00:00:00+00:00",
+        "lastEditBy": "testuser",
+        "lastEditAt": "2024-01-01T00:00:00+00:00",
+        "data": data,
+        **kwargs,
+    }
+
+    return create_mock_response(status_code=200, json_data=row_data)
+
+
+def create_mock_table_row_ocs_response(
+    row_id: int = 1,
+    table_id: int = 1,
+    data: list[dict] = None,
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock OCS response for Nextcloud Tables row (used by create_row).
+
+    Args:
+        row_id: Row ID
+        table_id: Table ID
+        data: List of column data dicts. If None, creates sample data.
+        **kwargs: Additional row fields
+
+    Returns:
+        Mock httpx.Response with row data in OCS format
+    """
+    if data is None:
+        data = [
+            {"columnId": 1, "value": "Test value"},
+            {"columnId": 2, "value": 42},
+        ]
+
+    row_data = {
+        "id": row_id,
+        "tableId": table_id,
+        "createdBy": "testuser",
+        "createdAt": "2024-01-01T00:00:00+00:00",
+        "lastEditBy": "testuser",
+        "lastEditAt": "2024-01-01T00:00:00+00:00",
+        "data": data,
+        **kwargs,
+    }
+
+    ocs_response = {"ocs": {"meta": {"status": "ok"}, "data": row_data}}
+
+    return create_mock_response(status_code=200, json_data=ocs_response)

tests/client/cookbook/test_cookbook_api.py

@@ -1,386 +1,371 @@
-import asyncio
 import logging
-import uuid
 
+import httpx
 import pytest
-from httpx import HTTPStatusError
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.client.cookbook import CookbookClient
+from tests.client.conftest import (
+    create_mock_error_response,
+    create_mock_recipe_list_response,
+    create_mock_recipe_response,
+    create_mock_response,
+)
 
 logger = logging.getLogger(__name__)
 
-# Mark all tests in this module as integration tests
-pytestmark = pytest.mark.integration
+# Mark all tests in this module as unit tests
+pytestmark = pytest.mark.unit
 
 
-async def test_cookbook_version(nc_client: NextcloudClient):
-    """Test getting Cookbook app version."""
-    logger.info("Getting Cookbook app version")
-    version_data = await nc_client.cookbook.get_version()
+async def test_cookbook_version(mocker):
+    """Test that get_version correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data={
+            "cookbook_version": "1.0.0",
+            "api_version": "1.0.0",
+        },
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
+
+    client = CookbookClient(mock_client, "testuser")
+    version_data = await client.get_version()
 
     assert "cookbook_version" in version_data
     assert "api_version" in version_data
-    logger.info(f"Cookbook version: {version_data}")
+    assert version_data["cookbook_version"] == "1.0.0"
+
+    mock_make_request.assert_called_once_with("GET", "/apps/cookbook/api/version")
 
 
-async def test_cookbook_config(nc_client: NextcloudClient):
-    """Test getting Cookbook app configuration."""
-    logger.info("Getting Cookbook app configuration")
-    config_data = await nc_client.cookbook.get_config()
+async def test_cookbook_config(mocker):
+    """Test that get_config correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data={
+            "folder": "/recipes",
+            "update_interval": 60,
+            "print_image": True,
+        },
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
+
+    client = CookbookClient(mock_client, "testuser")
+    config_data = await client.get_config()
 
-    # Config may be empty initially, just verify we can get it
     assert isinstance(config_data, dict)
-    logger.info(f"Cookbook config: {config_data}")
+    assert config_data["folder"] == "/recipes"
+
+    mock_make_request.assert_called_once_with("GET", "/apps/cookbook/api/v1/config")
 
 
-async def test_cookbook_list_recipes(nc_client: NextcloudClient):
-    """Test listing all recipes."""
-    logger.info("Listing all recipes")
-    recipes = await nc_client.cookbook.list_recipes()
+async def test_cookbook_list_recipes(mocker):
+    """Test that list_recipes correctly parses the API response."""
+    mock_response = create_mock_recipe_list_response(
+        recipes=[
+            {"id": 1, "name": "Recipe 1", "recipeCategory": "Test"},
+            {"id": 2, "name": "Recipe 2", "recipeCategory": "Test"},
+        ]
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
+
+    client = CookbookClient(mock_client, "testuser")
+    recipes = await client.list_recipes()
 
     assert isinstance(recipes, list)
-    logger.info(f"Found {len(recipes)} recipes")
+    assert len(recipes) == 2
+    assert recipes[0]["name"] == "Recipe 1"
+
+    mock_make_request.assert_called_once_with("GET", "/apps/cookbook/api/v1/recipes")
 
 
-async def test_cookbook_create_and_read_recipe(nc_client: NextcloudClient):
-    """Test creating a recipe and reading it back."""
-    # Create a test recipe
-    recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
+async def test_cookbook_create_recipe(mocker):
+    """Test that create_recipe correctly parses the API response."""
+    # Create_recipe returns just the recipe ID
+    mock_response = create_mock_response(status_code=200, json_data=123)
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
+
+    client = CookbookClient(mock_client, "testuser")
     recipe_data = {
-        "name": recipe_name,
-        "description": "A test recipe for integration testing",
-        "recipeIngredient": ["100g flour", "2 eggs", "200ml milk"],
-        "recipeInstructions": [
-            "Mix ingredients",
-            "Cook for 20 minutes",
-            "Serve hot",
-        ],
-        "recipeCategory": "Test",
-        "keywords": "test,integration",
-        "recipeYield": 4,
-        "prepTime": "PT15M",
-        "cookTime": "PT20M",
-        "totalTime": "PT35M",
-    }
-
-    logger.info(f"Creating recipe: {recipe_name}")
-    recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
-    logger.info(f"Created recipe with ID: {recipe_id}")
-
-    try:
-        # Read the recipe back
-        logger.info(f"Reading recipe ID: {recipe_id}")
-        retrieved_recipe = await nc_client.cookbook.get_recipe(recipe_id)
-
-        assert retrieved_recipe["name"] == recipe_name
-        assert (
-            retrieved_recipe["description"] == "A test recipe for integration testing"
-        )
-        assert len(retrieved_recipe["recipeIngredient"]) == 3
-        assert len(retrieved_recipe["recipeInstructions"]) == 3
-        assert retrieved_recipe["recipeCategory"] == "Test"
-        assert retrieved_recipe["recipeYield"] == 4
-        logger.info(f"Successfully verified recipe: {recipe_name}")
-
-    finally:
-        # Clean up
-        logger.info(f"Deleting recipe ID: {recipe_id}")
-        await nc_client.cookbook.delete_recipe(recipe_id)
-        logger.info(f"Successfully deleted recipe ID: {recipe_id}")
-
-
-async def test_cookbook_update_recipe(nc_client: NextcloudClient):
-    """Test updating a recipe."""
-    # Create a test recipe
-    recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
-    recipe_data = {
-        "name": recipe_name,
-        "description": "Original description",
+        "name": "Test Recipe",
+        "description": "Test description",
         "recipeIngredient": ["100g flour"],
         "recipeInstructions": ["Mix ingredients"],
-        "recipeCategory": "Original",
     }
+    recipe_id = await client.create_recipe(recipe_data)
 
-    logger.info(f"Creating recipe for update test: {recipe_name}")
-    recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
+    assert recipe_id == 123
 
-    try:
-        # Get the current recipe first
-        current_recipe = await nc_client.cookbook.get_recipe(recipe_id)
-
-        # Update the recipe with all required fields
-        updated_data = current_recipe.copy()
-        updated_data["description"] = "Updated description"
-        updated_data["recipeIngredient"] = ["100g flour", "2 eggs"]
-        updated_data["recipeInstructions"] = ["Mix ingredients", "Cook"]
-        updated_data["recipeCategory"] = "Updated"
-
-        logger.info(f"Updating recipe ID: {recipe_id}")
-        updated_id = await nc_client.cookbook.update_recipe(recipe_id, updated_data)
-        assert updated_id == recipe_id
-
-        # Verify the update
-        await asyncio.sleep(1)  # Allow propagation
-        updated_recipe = await nc_client.cookbook.get_recipe(recipe_id)
-        assert updated_recipe["description"] == "Updated description"
-        assert len(updated_recipe["recipeIngredient"]) == 2
-        assert len(updated_recipe["recipeInstructions"]) == 2
-        assert updated_recipe["recipeCategory"] == "Updated"
-        logger.info(f"Successfully updated recipe ID: {recipe_id}")
-
-    finally:
-        # Clean up
-        logger.info(f"Deleting recipe ID: {recipe_id}")
-        await nc_client.cookbook.delete_recipe(recipe_id)
+    mock_make_request.assert_called_once_with(
+        "POST", "/apps/cookbook/api/v1/recipes", json=recipe_data
+    )
 
 
-async def test_cookbook_delete_nonexistent_recipe(nc_client: NextcloudClient):
-    """Test deleting a non-existent recipe.
+async def test_cookbook_get_recipe(mocker):
+    """Test that get_recipe correctly parses the API response."""
+    mock_response = create_mock_recipe_response(
+        recipe_id=123,
+        name="Test Recipe",
+        description="Test description",
+        recipe_category="Test",
+        keywords="test,integration",
+        recipe_yield=4,
+        recipeIngredient=["100g flour", "2 eggs"],
+        recipeInstructions=["Mix ingredients", "Cook"],
+    )
 
-    Note: The Cookbook API may return 502 or succeed silently for non-existent IDs
-    rather than 404. This test verifies the behavior."""
-    non_existent_id = 999999999
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
 
-    logger.info(f"Attempting to delete non-existent recipe ID: {non_existent_id}")
-    try:
-        result = await nc_client.cookbook.delete_recipe(non_existent_id)
-        logger.info(f"Delete returned: {result}")
-        # API may succeed silently or return an error message
-        assert isinstance(result, str)
-    except HTTPStatusError as e:
-        # API may return 404 or 502 for non-existent recipes
-        assert e.response.status_code in [404, 502]
-        logger.info(f"Delete correctly failed with {e.response.status_code}")
+    client = CookbookClient(mock_client, "testuser")
+    recipe = await client.get_recipe(recipe_id=123)
+
+    assert recipe["id"] == 123
+    assert recipe["name"] == "Test Recipe"
+    assert recipe["description"] == "Test description"
+    assert len(recipe["recipeIngredient"]) == 2
+    assert len(recipe["recipeInstructions"]) == 2
+
+    mock_make_request.assert_called_once_with(
+        "GET", "/apps/cookbook/api/v1/recipes/123"
+    )
 
 
-async def test_cookbook_import_recipe_from_url(nc_client: NextcloudClient):
-    """Test importing a recipe from a URL.
+async def test_cookbook_update_recipe(mocker):
+    """Test that update_recipe correctly parses the API response."""
+    # Update_recipe returns the recipe ID
+    mock_response = create_mock_response(status_code=200, json_data=123)
 
-    This is the key feature test - importing recipes from URLs using schema.org metadata.
-    Uses an nginx container to serve reliable, controlled test data.
-    """
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
 
-    # Use the nginx container hostname within the Docker network
-    test_url = "http://recipes/black-pepper-tofu"
-
-    logger.info(f"Importing recipe from nginx container: {test_url}")
-
-    try:
-        imported_recipe = await nc_client.cookbook.import_recipe(test_url)
-        logger.info(f"Successfully imported recipe: {imported_recipe.get('name')}")
-
-        # Verify basic recipe structure
-        assert "name" in imported_recipe
-        assert imported_recipe["name"] == "Black Pepper Tofu"
-        assert "id" in imported_recipe
-
-        # Verify schema.org fields were imported correctly
-        assert imported_recipe.get("description")
-        assert len(imported_recipe.get("recipeIngredient", [])) > 0
-        assert len(imported_recipe.get("recipeInstructions", [])) > 0
-        assert imported_recipe.get("recipeCategory") == "Main Course"
-        assert "tofu" in imported_recipe.get("keywords", "").lower()
-
-        recipe_id = int(imported_recipe["id"])
-
-        # Verify we can read it back
-        retrieved = await nc_client.cookbook.get_recipe(recipe_id)
-        assert retrieved["name"] == imported_recipe["name"]
-        logger.info(f"Verified imported recipe ID: {recipe_id}")
-
-        # Clean up
-        logger.info(f"Deleting imported recipe ID: {recipe_id}")
-        await nc_client.cookbook.delete_recipe(recipe_id)
-        logger.info("Successfully deleted imported recipe")
-
-    except HTTPStatusError as e:
-        if e.response.status_code == 409:
-            # Recipe already exists - this is acceptable in tests
-            logger.warning("Recipe already exists (409 conflict)")
-            pytest.skip("Recipe already exists in test environment")
-        elif e.response.status_code == 400:
-            # URL couldn't be imported
-            logger.error(
-                f"Failed to import recipe from nginx container: {test_url}. "
-                f"Status: {e.response.status_code}, Response: {e.response.text}"
-            )
-            raise
-        else:
-            raise
-
-
-async def test_cookbook_search_recipes(nc_client: NextcloudClient):
-    """Test searching for recipes."""
-    # Create a test recipe with unique keywords
-    unique_keyword = f"testkeyword{uuid.uuid4().hex[:8]}"
-    recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
-    recipe_data = {
-        "name": recipe_name,
-        "description": f"Recipe for testing search with {unique_keyword}",
-        "keywords": unique_keyword,
-        "recipeIngredient": ["test ingredient"],
-        "recipeInstructions": ["test instruction"],
+    client = CookbookClient(mock_client, "testuser")
+    updated_data = {
+        "name": "Updated Recipe",
+        "description": "Updated description",
+        "recipeIngredient": ["100g flour", "2 eggs", "200ml milk"],
+        "recipeInstructions": ["Mix ingredients", "Cook", "Serve"],
     }
+    updated_id = await client.update_recipe(recipe_id=123, recipe_data=updated_data)
 
-    logger.info(f"Creating recipe for search test with keyword: {unique_keyword}")
-    recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
+    assert updated_id == 123
 
-    try:
-        # Allow time for indexing
-        await asyncio.sleep(2)
-
-        # Search for the recipe
-        logger.info(f"Searching for recipes with keyword: {unique_keyword}")
-        search_results = await nc_client.cookbook.search_recipes(unique_keyword)
-
-        assert isinstance(search_results, list)
-        # Should find at least our recipe
-        assert len(search_results) > 0
-
-        # Verify our recipe is in the results
-        found = any(str(r.get("id")) == str(recipe_id) for r in search_results)
-        assert found, f"Recipe {recipe_id} not found in search results"
-        logger.info(f"Successfully found recipe {recipe_id} in search results")
-
-    finally:
-        # Clean up
-        logger.info(f"Deleting recipe ID: {recipe_id}")
-        await nc_client.cookbook.delete_recipe(recipe_id)
+    mock_make_request.assert_called_once_with(
+        "PUT", "/apps/cookbook/api/v1/recipes/123", json=updated_data
+    )
 
 
-async def test_cookbook_list_categories(nc_client: NextcloudClient):
-    """Test listing recipe categories."""
-    logger.info("Listing recipe categories")
-    categories = await nc_client.cookbook.list_categories()
+async def test_cookbook_delete_recipe(mocker):
+    """Test that delete_recipe correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200, json_data="Recipe deleted successfully"
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
+
+    client = CookbookClient(mock_client, "testuser")
+    result = await client.delete_recipe(recipe_id=123)
+
+    assert isinstance(result, str)
+    assert "deleted" in result.lower()
+
+    mock_make_request.assert_called_once_with(
+        "DELETE", "/apps/cookbook/api/v1/recipes/123"
+    )
+
+
+async def test_cookbook_delete_nonexistent_recipe(mocker):
+    """Test that deleting a non-existent recipe raises HTTPStatusError."""
+    error_response = create_mock_error_response(404, "Recipe not found")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(CookbookClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "404 Not Found",
+        request=httpx.Request("DELETE", "http://test.local"),
+        response=error_response,
+    )
+
+    client = CookbookClient(mock_client, "testuser")
+
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.delete_recipe(recipe_id=999999999)
+
+    assert excinfo.value.response.status_code == 404
+
+
+async def test_cookbook_search_recipes(mocker):
+    """Test that search_recipes correctly parses the API response."""
+    mock_response = create_mock_recipe_list_response(
+        recipes=[
+            {"id": 1, "name": "Test Recipe 1", "keywords": "test,search"},
+            {"id": 2, "name": "Test Recipe 2", "keywords": "test,search"},
+        ]
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
+
+    client = CookbookClient(mock_client, "testuser")
+    search_results = await client.search_recipes("test")
+
+    assert isinstance(search_results, list)
+    assert len(search_results) == 2
+
+    # Verify URL encoding happened
+    mock_make_request.assert_called_once()
+    call_args = mock_make_request.call_args[0]
+    assert "/apps/cookbook/api/v1/search/" in call_args[1]
+
+
+async def test_cookbook_list_categories(mocker):
+    """Test that list_categories correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data=[
+            {"name": "Desserts", "recipe_count": 5},
+            {"name": "Main Course", "recipe_count": 10},
+        ],
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
+
+    client = CookbookClient(mock_client, "testuser")
+    categories = await client.list_categories()
 
     assert isinstance(categories, list)
-    logger.info(f"Found {len(categories)} categories")
+    assert len(categories) == 2
+    assert categories[0]["name"] == "Desserts"
+    assert categories[0]["recipe_count"] == 5
 
-    # Each category should have name and recipe_count
-    if categories:
-        assert "name" in categories[0]
-        assert "recipe_count" in categories[0]
+    mock_make_request.assert_called_once_with("GET", "/apps/cookbook/api/v1/categories")
 
 
-async def test_cookbook_get_recipes_in_category(nc_client: NextcloudClient):
-    """Test getting recipes in a specific category."""
-    # Create a recipe in a test category
-    unique_category = f"TestCategory{uuid.uuid4().hex[:8]}"
-    recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
-    recipe_data = {
-        "name": recipe_name,
-        "recipeCategory": unique_category,
-        "recipeIngredient": ["test"],
-        "recipeInstructions": ["test"],
-    }
+async def test_cookbook_get_recipes_in_category(mocker):
+    """Test that get_recipes_in_category correctly parses the API response."""
+    mock_response = create_mock_recipe_list_response(
+        recipes=[
+            {"id": 1, "name": "Recipe 1", "recipeCategory": "Desserts"},
+            {"id": 2, "name": "Recipe 2", "recipeCategory": "Desserts"},
+        ]
+    )
 
-    logger.info(f"Creating recipe in category: {unique_category}")
-    recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
 
-    try:
-        # Allow time for indexing
-        await asyncio.sleep(2)
+    client = CookbookClient(mock_client, "testuser")
+    recipes_in_category = await client.get_recipes_in_category("Desserts")
 
-        # Get recipes in this category
-        logger.info(f"Getting recipes in category: {unique_category}")
-        recipes_in_category = await nc_client.cookbook.get_recipes_in_category(
-            unique_category
-        )
+    assert isinstance(recipes_in_category, list)
+    assert len(recipes_in_category) == 2
+    assert recipes_in_category[0]["recipeCategory"] == "Desserts"
 
-        assert isinstance(recipes_in_category, list)
-        assert len(recipes_in_category) > 0
-
-        # Verify our recipe is in the results
-        found = any(str(r.get("id")) == str(recipe_id) for r in recipes_in_category)
-        assert found, f"Recipe {recipe_id} not found in category {unique_category}"
-        logger.info(f"Successfully found recipe in category {unique_category}")
-
-    finally:
-        # Clean up
-        logger.info(f"Deleting recipe ID: {recipe_id}")
-        await nc_client.cookbook.delete_recipe(recipe_id)
+    # Verify URL encoding happened
+    mock_make_request.assert_called_once()
+    call_args = mock_make_request.call_args[0]
+    assert "/apps/cookbook/api/v1/category/" in call_args[1]
 
 
-async def test_cookbook_list_keywords(nc_client: NextcloudClient):
-    """Test listing recipe keywords."""
-    logger.info("Listing recipe keywords")
-    keywords = await nc_client.cookbook.list_keywords()
+async def test_cookbook_list_keywords(mocker):
+    """Test that list_keywords correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data=[
+            {"name": "vegetarian", "recipe_count": 15},
+            {"name": "quick", "recipe_count": 8},
+        ],
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
+
+    client = CookbookClient(mock_client, "testuser")
+    keywords = await client.list_keywords()
 
     assert isinstance(keywords, list)
-    logger.info(f"Found {len(keywords)} keywords")
+    assert len(keywords) == 2
+    assert keywords[0]["name"] == "vegetarian"
+    assert keywords[0]["recipe_count"] == 15
 
-    # Each keyword should have name and recipe_count
-    if keywords:
-        assert "name" in keywords[0]
-        assert "recipe_count" in keywords[0]
+    mock_make_request.assert_called_once_with("GET", "/apps/cookbook/api/v1/keywords")
 
 
-async def test_cookbook_get_recipes_with_keywords(nc_client: NextcloudClient):
-    """Test getting recipes with specific keywords.
+async def test_cookbook_get_recipes_with_keywords(mocker):
+    """Test that get_recipes_with_keywords correctly parses the API response."""
+    mock_response = create_mock_recipe_list_response(
+        recipes=[
+            {"id": 1, "name": "Recipe 1", "keywords": "vegetarian,quick"},
+            {"id": 2, "name": "Recipe 2", "keywords": "vegetarian,healthy"},
+        ]
+    )
 
-    Note: The keywords filtering may require exact keyword matches and sufficient
-    indexing time. This test uses a longer wait time."""
-    # Create a recipe with unique keywords
-    unique_keyword = f"testtag{uuid.uuid4().hex[:8]}"
-    recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
-    recipe_data = {
-        "name": recipe_name,
-        "keywords": f"{unique_keyword},integration",
-        "recipeIngredient": ["test"],
-        "recipeInstructions": ["test"],
-    }
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
 
-    logger.info(f"Creating recipe with keyword: {unique_keyword}")
-    recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
+    client = CookbookClient(mock_client, "testuser")
+    recipes_with_keywords = await client.get_recipes_with_keywords(
+        ["vegetarian", "quick"]
+    )
 
-    try:
-        # Allow extra time for indexing
-        await asyncio.sleep(3)
+    assert isinstance(recipes_with_keywords, list)
+    assert len(recipes_with_keywords) == 2
 
-        # Trigger a reindex to ensure the recipe is indexed
-        await nc_client.cookbook.reindex()
-        await asyncio.sleep(2)
-
-        # Get recipes with this keyword
-        logger.info(f"Getting recipes with keyword: {unique_keyword}")
-        recipes_with_keywords = await nc_client.cookbook.get_recipes_with_keywords(
-            [unique_keyword]
-        )
-
-        assert isinstance(recipes_with_keywords, list)
-        # Keyword filtering might not find recipes immediately due to indexing
-        # Log the results for debugging
-        logger.info(
-            f"Found {len(recipes_with_keywords)} recipes with keyword {unique_keyword}"
-        )
-
-        if len(recipes_with_keywords) > 0:
-            # Verify our recipe is in the results if any are found
-            found = any(
-                str(r.get("id")) == str(recipe_id) for r in recipes_with_keywords
-            )
-            if found:
-                logger.info(f"Successfully found recipe with keyword {unique_keyword}")
-            else:
-                logger.warning(
-                    f"Recipe {recipe_id} not in keyword results, but other recipes found"
-                )
-        else:
-            logger.warning(
-                f"No recipes found with keyword {unique_keyword} - may be indexing delay"
-            )
-
-    finally:
-        # Clean up
-        logger.info(f"Deleting recipe ID: {recipe_id}")
-        await nc_client.cookbook.delete_recipe(recipe_id)
+    # Verify URL encoding and keyword joining happened
+    mock_make_request.assert_called_once()
+    call_args = mock_make_request.call_args[0]
+    assert "/apps/cookbook/api/v1/tags/" in call_args[1]
 
 
-async def test_cookbook_reindex(nc_client: NextcloudClient):
-    """Test triggering a reindex of recipes."""
-    logger.info("Triggering recipe reindex")
-    result = await nc_client.cookbook.reindex()
+async def test_cookbook_reindex(mocker):
+    """Test that reindex correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data="Reindex completed successfully",
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        CookbookClient, "_make_request", return_value=mock_response
+    )
+
+    client = CookbookClient(mock_client, "testuser")
+    result = await client.reindex()
 
-    # Should return a success message
     assert isinstance(result, str)
-    logger.info(f"Reindex result: {result}")
+    assert "reindex" in result.lower() or "completed" in result.lower()
+
+    mock_make_request.assert_called_once_with("POST", "/apps/cookbook/api/v1/reindex")

tests/client/deck/test_deck_api.py

@@ -1,327 +1,511 @@
 import logging
-import uuid
 
+import httpx
 import pytest
-from httpx import HTTPStatusError
 
-from nextcloud_mcp_server.client import NextcloudClient
-from nextcloud_mcp_server.models.deck import DeckCard, DeckLabel, DeckStack
+from nextcloud_mcp_server.client.deck import DeckClient
+from nextcloud_mcp_server.models.deck import (
+    DeckBoard,
+    DeckCard,
+    DeckComment,
+    DeckLabel,
+    DeckStack,
+)
+from tests.client.conftest import (
+    create_mock_deck_board_response,
+    create_mock_deck_card_response,
+    create_mock_deck_comment_response,
+    create_mock_deck_label_response,
+    create_mock_deck_stack_response,
+    create_mock_error_response,
+    create_mock_response,
+)
 
 logger = logging.getLogger(__name__)
-pytestmark = pytest.mark.integration
+
+# Mark all tests in this module as unit tests
+pytestmark = pytest.mark.unit
 
 
-# Board CRUD Tests
+# Board Tests
 
 
-async def test_deck_board_crud_workflow(
-    nc_client: NextcloudClient, temporary_board: dict
-):
-    """
-    Test complete board CRUD workflow using the temporary_board fixture.
-    """
-    board_data = temporary_board
-    board_id = board_data["id"]
-    original_title = board_data["title"]
-    original_color = board_data["color"]
-
-    logger.info(f"Testing CRUD operations on board ID: {board_id}")
-
-    # Read the board
-    read_board = await nc_client.deck.get_board(board_id)
-    assert read_board.id == board_id
-    assert read_board.title == original_title
-    assert read_board.color == original_color
-    logger.info(f"Successfully read board ID: {board_id}")
-
-    # Update the board
-    updated_title = f"Updated {original_title}"
-    updated_color = "00FF00"  # Green color
-    await nc_client.deck.update_board(
-        board_id, title=updated_title, color=updated_color
+async def test_deck_get_boards(mocker):
+    """Test that get_boards correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data=[
+            {
+                "id": 1,
+                "title": "Board 1",
+                "color": "FF0000",
+                "owner": {
+                    "primaryKey": "testuser",
+                    "uid": "testuser",
+                    "displayname": "Test User",
+                },
+                "archived": False,
+                "labels": [],
+                "acl": [],
+                "permissions": {
+                    "PERMISSION_READ": True,
+                    "PERMISSION_EDIT": True,
+                    "PERMISSION_MANAGE": True,
+                    "PERMISSION_SHARE": True,
+                },
+                "users": [],
+                "deletedAt": 0,
+            },
+            {
+                "id": 2,
+                "title": "Board 2",
+                "color": "00FF00",
+                "owner": {
+                    "primaryKey": "testuser",
+                    "uid": "testuser",
+                    "displayname": "Test User",
+                },
+                "archived": False,
+                "labels": [],
+                "acl": [],
+                "permissions": {
+                    "PERMISSION_READ": True,
+                    "PERMISSION_EDIT": True,
+                    "PERMISSION_MANAGE": True,
+                    "PERMISSION_SHARE": True,
+                },
+                "users": [],
+                "deletedAt": 0,
+            },
+        ],
     )
 
-    # Verify the update
-    updated_board = await nc_client.deck.get_board(board_id)
-    assert updated_board.title == updated_title
-    assert updated_board.color == updated_color
-    logger.info(f"Successfully updated board ID: {board_id}")
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
 
+    client = DeckClient(mock_client, "testuser")
+    boards = await client.get_boards()
 
-async def test_deck_list_boards(nc_client: NextcloudClient):
-    """
-    Test listing all boards with different options.
-    """
-    # Test basic listing
-    boards = await nc_client.deck.get_boards()
     assert isinstance(boards, list)
-    logger.info(f"Found {len(boards)} boards")
+    assert len(boards) == 2
+    assert all(isinstance(b, DeckBoard) for b in boards)
+    assert boards[0].id == 1
+    assert boards[0].title == "Board 1"
 
-    # Test with details
-    detailed_boards = await nc_client.deck.get_boards(details=True)
-    assert isinstance(detailed_boards, list)
-    logger.info(f"Found {len(detailed_boards)} boards with details")
+    mock_make_request.assert_called_once()
 
 
-async def test_deck_board_operations_nonexistent(nc_client: NextcloudClient):
-    """
-    Test operations on non-existent board return appropriate errors.
-    """
-    non_existent_id = 999999999
-
-    # Test get non-existent board
-    with pytest.raises(HTTPStatusError) as excinfo:
-        await nc_client.deck.get_board(non_existent_id)
-    assert excinfo.value.response.status_code in [
-        404,
-        403,
-    ]  # 403 might be returned for access denied
-    logger.info(
-        f"Get non-existent board correctly failed with {excinfo.value.response.status_code}"
+async def test_deck_create_board(mocker):
+    """Test that create_board correctly parses the API response."""
+    mock_response = create_mock_deck_board_response(
+        board_id=123, title="New Board", color="FF0000"
     )
 
-    # Test update non-existent board
-    with pytest.raises(HTTPStatusError) as excinfo:
-        await nc_client.deck.update_board(non_existent_id, title="Should Fail")
-    assert excinfo.value.response.status_code in [
-        404,
-        403,
-        400,
-    ]  # 400 for bad request on invalid board ID
-    logger.info(
-        f"Update non-existent board correctly failed with {excinfo.value.response.status_code}"
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
     )
 
+    client = DeckClient(mock_client, "testuser")
+    board = await client.create_board(title="New Board", color="FF0000")
 
-# Stack CRUD Tests
+    assert isinstance(board, DeckBoard)
+    assert board.id == 123
+    assert board.title == "New Board"
+    assert board.color == "FF0000"
+
+    mock_make_request.assert_called_once()
+    call_args = mock_make_request.call_args
+    assert call_args[0][0] == "POST"
+    assert call_args[1]["json"]["title"] == "New Board"
 
 
-async def test_deck_stack_crud_workflow(
-    nc_client: NextcloudClient, temporary_board: dict
-):
-    """
-    Test complete stack CRUD workflow.
-    """
-    board_id = temporary_board["id"]
-    stack_title = f"Test Stack {uuid.uuid4().hex[:8]}"
-    stack_order = 1
-    stack = None
+async def test_deck_get_board(mocker):
+    """Test that get_board correctly parses the API response."""
+    mock_response = create_mock_deck_board_response(
+        board_id=123, title="Test Board", color="0000FF"
+    )
 
-    try:
-        # Create stack
-        stack = await nc_client.deck.create_stack(board_id, stack_title, stack_order)
-        assert isinstance(stack, DeckStack)
-        assert stack.title == stack_title
-        assert stack.order == stack_order
-        stack_id = stack.id
-        logger.info(f"Created stack ID: {stack_id}")
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
 
-        # Read stack
-        read_stack = await nc_client.deck.get_stack(board_id, stack_id)
-        assert read_stack.id == stack_id
-        assert read_stack.title == stack_title
-        logger.info(f"Successfully read stack ID: {stack_id}")
+    client = DeckClient(mock_client, "testuser")
+    board = await client.get_board(board_id=123)
 
-        # Update stack
-        updated_title = f"Updated {stack_title}"
-        updated_order = 2
-        await nc_client.deck.update_stack(
-            board_id, stack_id, title=updated_title, order=updated_order
-        )
+    assert isinstance(board, DeckBoard)
+    assert board.id == 123
+    assert board.title == "Test Board"
 
-        # Verify update
-        updated_stack = await nc_client.deck.get_stack(board_id, stack_id)
-        assert updated_stack.title == updated_title
-        assert updated_stack.order == updated_order
-        logger.info(f"Successfully updated stack ID: {stack_id}")
-
-        # List stacks
-        stacks = await nc_client.deck.get_stacks(board_id)
-        assert isinstance(stacks, list)
-        assert any(s.id == stack_id for s in stacks)
-        logger.info(f"Found stack ID: {stack_id} in board stacks list")
-
-    finally:
-        # Clean up - delete stack
-        if stack and hasattr(stack, "id"):
-            try:
-                await nc_client.deck.delete_stack(board_id, stack.id)
-                logger.info(f"Cleaned up stack ID: {stack.id}")
-            except Exception as e:
-                logger.warning(f"Failed to clean up stack ID: {stack.id}: {e}")
+    mock_make_request.assert_called_once()
+    assert "/boards/123" in mock_make_request.call_args[0][1]
 
 
-# Card CRUD Tests
+async def test_deck_update_board(mocker):
+    """Test that update_board makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    await client.update_board(board_id=123, title="Updated Board", color="00FF00")
+
+    mock_make_request.assert_called_once()
+    call_args = mock_make_request.call_args
+    assert call_args[0][0] == "PUT"
+    assert "/boards/123" in call_args[0][1]
+    assert call_args[1]["json"]["title"] == "Updated Board"
 
 
-async def test_deck_card_crud_workflow(
-    nc_client: NextcloudClient, temporary_board_with_stack: tuple
-):
-    """
-    Test complete card CRUD workflow.
-    """
-    board_data, stack_data = temporary_board_with_stack
-    board_id = board_data["id"]
-    stack_id = stack_data["id"]
+async def test_deck_get_board_nonexistent(mocker):
+    """Test that getting a non-existent board raises HTTPStatusError."""
+    error_response = create_mock_error_response(404, "Board not found")
 
-    card_title = f"Test Card {uuid.uuid4().hex[:8]}"
-    card_description = f"Test description for card {uuid.uuid4().hex[:8]}"
-    card = None
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(DeckClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "404 Not Found",
+        request=httpx.Request("GET", "http://test.local"),
+        response=error_response,
+    )
 
-    try:
-        # Create card
-        card = await nc_client.deck.create_card(
-            board_id, stack_id, card_title, description=card_description
-        )
-        assert isinstance(card, DeckCard)
-        assert card.title == card_title
-        assert card.description == card_description
-        card_id = card.id
-        logger.info(f"Created card ID: {card_id}")
+    client = DeckClient(mock_client, "testuser")
 
-        # Read card
-        read_card = await nc_client.deck.get_card(board_id, stack_id, card_id)
-        assert read_card.id == card_id
-        assert read_card.title == card_title
-        logger.info(f"Successfully read card ID: {card_id}")
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.get_board(board_id=999999999)
 
-        # Update card
-        updated_title = f"Updated {card_title}"
-        updated_description = f"Updated description for {card_title}"
-        await nc_client.deck.update_card(
-            board_id,
-            stack_id,
-            card_id,
-            title=updated_title,
-            description=updated_description,
-        )
-
-        # Verify update
-        updated_card = await nc_client.deck.get_card(board_id, stack_id, card_id)
-        assert updated_card.title == updated_title
-        assert updated_card.description == updated_description
-        logger.info(f"Successfully updated card ID: {card_id}")
-
-        # Archive and unarchive card
-        await nc_client.deck.archive_card(board_id, stack_id, card_id)
-        logger.info(f"Archived card ID: {card_id}")
-
-        await nc_client.deck.unarchive_card(board_id, stack_id, card_id)
-        logger.info(f"Unarchived card ID: {card_id}")
-
-    finally:
-        # Clean up - delete card
-        if card and hasattr(card, "id"):
-            try:
-                await nc_client.deck.delete_card(board_id, stack_id, card.id)
-                logger.info(f"Cleaned up card ID: {card.id}")
-            except Exception as e:
-                logger.warning(f"Failed to clean up card ID: {card.id}: {e}")
+    assert excinfo.value.response.status_code == 404
 
 
-# Label CRUD Tests
+# Stack Tests
 
 
-async def test_deck_label_crud_workflow(
-    nc_client: NextcloudClient, temporary_board: dict
-):
-    """
-    Test complete label CRUD workflow.
-    """
-    board_id = temporary_board["id"]
-    label_title = f"Test Label {uuid.uuid4().hex[:8]}"
-    label_color = "FF0000"  # Red
-    label = None
+async def test_deck_create_stack(mocker):
+    """Test that create_stack correctly parses the API response."""
+    mock_response = create_mock_deck_stack_response(
+        stack_id=456, title="Test Stack", board_id=123, order=1
+    )
 
-    try:
-        # Create label
-        label = await nc_client.deck.create_label(board_id, label_title, label_color)
-        assert isinstance(label, DeckLabel)
-        assert label.title == label_title
-        assert label.color == label_color
-        label_id = label.id
-        logger.info(f"Created label ID: {label_id}")
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
 
-        # Read label
-        read_label = await nc_client.deck.get_label(board_id, label_id)
-        assert read_label.id == label_id
-        assert read_label.title == label_title
-        logger.info(f"Successfully read label ID: {label_id}")
+    client = DeckClient(mock_client, "testuser")
+    stack = await client.create_stack(board_id=123, title="Test Stack", order=1)
 
-        # Update label
-        updated_title = f"Updated {label_title}"
-        updated_color = "00FF00"  # Green
-        await nc_client.deck.update_label(
-            board_id, label_id, title=updated_title, color=updated_color
-        )
+    assert isinstance(stack, DeckStack)
+    assert stack.id == 456
+    assert stack.title == "Test Stack"
+    assert stack.boardId == 123
 
-        # Verify update
-        updated_label = await nc_client.deck.get_label(board_id, label_id)
-        assert updated_label.title == updated_title
-        assert updated_label.color == updated_color
-        logger.info(f"Successfully updated label ID: {label_id}")
-
-    finally:
-        # Clean up - delete label
-        if label and hasattr(label, "id"):
-            try:
-                await nc_client.deck.delete_label(board_id, label.id)
-                logger.info(f"Cleaned up label ID: {label.id}")
-            except Exception as e:
-                logger.warning(f"Failed to clean up label ID: {label.id}: {e}")
+    mock_make_request.assert_called_once()
 
 
-# Configuration and Comments Tests
+async def test_deck_get_stack(mocker):
+    """Test that get_stack correctly parses the API response."""
+    mock_response = create_mock_deck_stack_response(
+        stack_id=456, title="Test Stack", board_id=123, order=1
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    stack = await client.get_stack(board_id=123, stack_id=456)
+
+    assert isinstance(stack, DeckStack)
+    assert stack.id == 456
+    assert stack.title == "Test Stack"
+
+    mock_make_request.assert_called_once()
+    assert "/boards/123/stacks/456" in mock_make_request.call_args[0][1]
 
 
-async def test_deck_config_operations(nc_client: NextcloudClient):
-    """
-    Test deck configuration operations.
-    """
-    # Get config
-    config = await nc_client.deck.get_config()
-    assert config is not None
-    logger.info(f"Retrieved deck config: {config}")
+async def test_deck_get_stacks(mocker):
+    """Test that get_stacks correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data=[
+            {"id": 1, "title": "Stack 1", "boardId": 123, "order": 1, "deletedAt": 0},
+            {"id": 2, "title": "Stack 2", "boardId": 123, "order": 2, "deletedAt": 0},
+        ],
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    stacks = await client.get_stacks(board_id=123)
+
+    assert isinstance(stacks, list)
+    assert len(stacks) == 2
+    assert all(isinstance(s, DeckStack) for s in stacks)
+
+    mock_make_request.assert_called_once()
 
 
-async def test_deck_comments_workflow(
-    nc_client: NextcloudClient, temporary_board_with_card: tuple
-):
-    """
-    Test comment operations on a card.
-    """
-    board_data, stack_data, card_data = temporary_board_with_card
-    card_id = card_data["id"]
+# Card Tests
 
-    comment_message = f"Test comment {uuid.uuid4().hex[:8]}"
-    comment = None
 
-    try:
-        # Create comment
-        comment = await nc_client.deck.create_comment(card_id, comment_message)
-        assert comment.message == comment_message
-        comment_id = comment.id
-        logger.info(f"Created comment ID: {comment_id}")
+async def test_deck_create_card(mocker):
+    """Test that create_card correctly parses the API response."""
+    mock_response = create_mock_deck_card_response(
+        card_id=789, title="Test Card", stack_id=456, description="Test description"
+    )
 
-        # List comments
-        comments = await nc_client.deck.get_comments(card_id)
-        assert isinstance(comments, list)
-        assert any(c.id == comment_id for c in comments)
-        logger.info(f"Found comment ID: {comment_id} in card comments")
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
 
-        # Update comment
-        updated_message = f"Updated {comment_message}"
-        updated_comment = await nc_client.deck.update_comment(
-            card_id, comment_id, updated_message
-        )
-        assert updated_comment.message == updated_message
-        logger.info(f"Successfully updated comment ID: {comment_id}")
+    client = DeckClient(mock_client, "testuser")
+    card = await client.create_card(
+        board_id=123, stack_id=456, title="Test Card", description="Test description"
+    )
 
-    finally:
-        # Clean up - delete comment
-        if comment and hasattr(comment, "id"):
-            try:
-                await nc_client.deck.delete_comment(card_id, comment.id)
-                logger.info(f"Cleaned up comment ID: {comment.id}")
-            except Exception as e:
-                logger.warning(f"Failed to clean up comment ID: {comment.id}: {e}")
+    assert isinstance(card, DeckCard)
+    assert card.id == 789
+    assert card.title == "Test Card"
+    assert card.description == "Test description"
+
+    mock_make_request.assert_called_once()
+
+
+async def test_deck_get_card(mocker):
+    """Test that get_card correctly parses the API response."""
+    mock_response = create_mock_deck_card_response(
+        card_id=789, title="Test Card", stack_id=456
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    card = await client.get_card(board_id=123, stack_id=456, card_id=789)
+
+    assert isinstance(card, DeckCard)
+    assert card.id == 789
+    assert card.title == "Test Card"
+
+    mock_make_request.assert_called_once()
+    assert "/boards/123/stacks/456/cards/789" in mock_make_request.call_args[0][1]
+
+
+async def test_deck_update_card(mocker):
+    """Test that update_card makes the correct API calls."""
+    # Mock get_card response (update_card calls get_card first)
+    get_response = create_mock_deck_card_response(
+        card_id=789, title="Original Card", stack_id=456
+    )
+
+    # Mock update response
+    update_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(DeckClient, "_make_request")
+    # First call returns the card, second call is the update
+    mock_make_request.side_effect = [get_response, update_response]
+
+    client = DeckClient(mock_client, "testuser")
+    await client.update_card(
+        board_id=123, stack_id=456, card_id=789, title="Updated Card"
+    )
+
+    # Should be called twice: GET then PUT
+    assert mock_make_request.call_count == 2
+
+    # Check the PUT call
+    put_call = mock_make_request.call_args_list[1]
+    assert put_call[0][0] == "PUT"
+    assert "/boards/123/stacks/456/cards/789" in put_call[0][1]
+    assert put_call[1]["json"]["title"] == "Updated Card"
+
+
+# Label Tests
+
+
+async def test_deck_create_label(mocker):
+    """Test that create_label correctly parses the API response."""
+    mock_response = create_mock_deck_label_response(
+        label_id=111, title="Test Label", color="FF0000", board_id=123
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    label = await client.create_label(board_id=123, title="Test Label", color="FF0000")
+
+    assert isinstance(label, DeckLabel)
+    assert label.id == 111
+    assert label.title == "Test Label"
+    assert label.color == "FF0000"
+
+    mock_make_request.assert_called_once()
+
+
+async def test_deck_get_label(mocker):
+    """Test that get_label correctly parses the API response."""
+    mock_response = create_mock_deck_label_response(
+        label_id=111, title="Test Label", color="FF0000", board_id=123
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    label = await client.get_label(board_id=123, label_id=111)
+
+    assert isinstance(label, DeckLabel)
+    assert label.id == 111
+    assert label.title == "Test Label"
+
+    mock_make_request.assert_called_once()
+    assert "/boards/123/labels/111" in mock_make_request.call_args[0][1]
+
+
+# Comment Tests
+
+
+async def test_deck_create_comment(mocker):
+    """Test that create_comment correctly parses the API response (OCS format)."""
+    mock_response = create_mock_deck_comment_response(
+        comment_id=222, message="Test comment", card_id=789
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    comment = await client.create_comment(card_id=789, message="Test comment")
+
+    assert isinstance(comment, DeckComment)
+    assert comment.id == 222
+    assert comment.message == "Test comment"
+
+    mock_make_request.assert_called_once()
+
+
+async def test_deck_get_comments(mocker):
+    """Test that get_comments correctly parses the API response (OCS format)."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data={
+            "ocs": {
+                "meta": {"status": "ok"},
+                "data": [
+                    {
+                        "id": 1,
+                        "objectId": 789,
+                        "message": "Comment 1",
+                        "actorId": "testuser",
+                        "actorDisplayName": "Test User",
+                        "actorType": "users",
+                        "creationDateTime": "2024-01-01T00:00:00+00:00",
+                        "mentions": [],
+                    },
+                    {
+                        "id": 2,
+                        "objectId": 789,
+                        "message": "Comment 2",
+                        "actorId": "testuser",
+                        "actorDisplayName": "Test User",
+                        "actorType": "users",
+                        "creationDateTime": "2024-01-01T00:00:00+00:00",
+                        "mentions": [],
+                    },
+                ],
+            }
+        },
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    comments = await client.get_comments(card_id=789)
+
+    assert isinstance(comments, list)
+    assert len(comments) == 2
+    assert all(isinstance(c, DeckComment) for c in comments)
+    assert comments[0].message == "Comment 1"
+
+    mock_make_request.assert_called_once()
+
+
+async def test_deck_update_comment(mocker):
+    """Test that update_comment correctly parses the API response (OCS format)."""
+    mock_response = create_mock_deck_comment_response(
+        comment_id=222, message="Updated comment", card_id=789
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    comment = await client.update_comment(
+        card_id=789, comment_id=222, message="Updated comment"
+    )
+
+    assert isinstance(comment, DeckComment)
+    assert comment.id == 222
+    assert comment.message == "Updated comment"
+
+    mock_make_request.assert_called_once()
+
+
+# Config Test
+
+
+async def test_deck_get_config(mocker):
+    """Test that get_config correctly parses the API response (OCS format)."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data={
+            "ocs": {
+                "meta": {"status": "ok"},
+                "data": {
+                    "calendar": True,
+                    "cardDetailsInModal": True,
+                    "cardIdBadge": False,
+                },
+            }
+        },
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        DeckClient, "_make_request", return_value=mock_response
+    )
+
+    client = DeckClient(mock_client, "testuser")
+    config = await client.get_config()
+
+    assert config.calendar is True
+    assert config.cardDetailsInModal is True
+    assert config.cardIdBadge is False
+
+    mock_make_request.assert_called_once()

tests/client/notes/test_notes_api.py

@@ -1,260 +1,255 @@
-import asyncio
 import logging
-import uuid  # Keep uuid if needed for generating unique data within tests
 
+import httpx
 import pytest
-from httpx import HTTPStatusError
 
-from nextcloud_mcp_server.client import NextcloudClient
-
-# Note: nc_client fixture is now session-scoped in conftest.py
+from nextcloud_mcp_server.client.notes import NotesClient
+from tests.client.conftest import create_mock_error_response, create_mock_note_response
 
 logger = logging.getLogger(__name__)
 
-# Mark all tests in this module as integration tests
-pytestmark = pytest.mark.integration
+# Mark all tests in this module as unit tests
+pytestmark = pytest.mark.unit
 
 
-async def test_notes_api_create_and_read(
-    nc_client: NextcloudClient, temporary_note: dict
-):
-    """
-    Tests creating a note via the API (using fixture) and then reading it back.
-    """
-    created_note_data = temporary_note  # Get data from fixture
-    note_id = created_note_data["id"]
-
-    logger.info(f"Reading note created by fixture, ID: {note_id}")
-    read_note = await nc_client.notes.get_note(note_id=note_id)
-
-    assert read_note["id"] == note_id
-    assert read_note["title"] == created_note_data["title"]
-    assert read_note["content"] == created_note_data["content"]
-    assert read_note["category"] == created_note_data["category"]
-    logger.info(f"Successfully read and verified note ID: {note_id}")
-
-
-async def test_notes_api_update(nc_client: NextcloudClient, temporary_note: dict):
-    """
-    Tests updating a note created by the fixture.
-    """
-    created_note_data = temporary_note
-    note_id = created_note_data["id"]
-    original_etag = created_note_data["etag"]
-    original_category = created_note_data["category"]
-
-    update_title = f"Updated Title {uuid.uuid4().hex[:8]}"
-    update_content = f"Updated Content {uuid.uuid4().hex[:8]}"
-
-    logger.info(f"Attempting to update note ID: {note_id} with etag: {original_etag}")
-    updated_note = await nc_client.notes.update(
-        note_id=note_id,
-        etag=original_etag,
-        title=update_title,
-        content=update_content,
-        # category=original_category # Explicitly pass category if required by update
+async def test_notes_api_get_note(mocker):
+    """Test that get_note correctly parses the API response."""
+    # Create mock response
+    mock_response = create_mock_note_response(
+        note_id=123,
+        title="Test Note",
+        content="Test content",
+        category="Test",
+        etag="abc123",
     )
-    logger.info(f"Note updated: {updated_note}")
 
-    assert updated_note["id"] == note_id
-    assert updated_note["title"] == update_title
-    assert updated_note["content"] == update_content
-    assert (
-        updated_note["category"] == original_category
-    )  # Verify category didn't change
-    assert "etag" in updated_note
-    assert updated_note["etag"] != original_etag  # Etag must change
-
-    # Optional: Verify update by reading again
-    await asyncio.sleep(1)  # Allow potential propagation delay
-    read_updated_note = await nc_client.notes.get_note(note_id=note_id)
-    assert read_updated_note["title"] == update_title
-    assert read_updated_note["content"] == update_content
-    logger.info(f"Successfully updated and verified note ID: {note_id}")
-
-
-async def test_notes_api_update_conflict(
-    nc_client: NextcloudClient, temporary_note: dict
-):
-    """
-    Tests that attempting to update with an old etag fails with 412.
-    """
-    created_note_data = temporary_note
-    note_id = created_note_data["id"]
-    original_etag = created_note_data["etag"]
-
-    # Perform a first update to change the etag
-    first_update_title = f"First Update {uuid.uuid4().hex[:8]}"
-    logger.info(f"Performing first update on note ID: {note_id} to change etag.")
-    first_updated_note = await nc_client.notes.update(
-        note_id=note_id,
-        etag=original_etag,
-        title=first_update_title,
-        content="First update content",
-        # category=created_note_data["category"] # Pass category if required
+    # Mock the _make_request method
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NotesClient, "_make_request", return_value=mock_response
     )
-    new_etag = first_updated_note["etag"]
-    assert new_etag != original_etag
-    logger.info(f"Note ID: {note_id} updated, new etag: {new_etag}")
-    await asyncio.sleep(1)
 
-    # Now attempt update with the *original* etag
-    logger.info(
-        f"Attempting second update on note ID: {note_id} with OLD etag: {original_etag}"
+    # Create client and test
+    client = NotesClient(mock_client, "testuser")
+    note = await client.get_note(note_id=123)
+
+    # Verify the response was parsed correctly
+    assert note["id"] == 123
+    assert note["title"] == "Test Note"
+    assert note["content"] == "Test content"
+    assert note["category"] == "Test"
+    assert note["etag"] == "abc123"
+
+    # Verify the correct API endpoint was called
+    mock_make_request.assert_called_once_with("GET", "/apps/notes/api/v1/notes/123")
+
+
+async def test_notes_api_create_note(mocker):
+    """Test that create_note correctly parses the API response."""
+    mock_response = create_mock_note_response(
+        note_id=456,
+        title="New Note",
+        content="New content",
+        category="Category",
+        etag="def456",
     )
-    with pytest.raises(HTTPStatusError) as excinfo:
-        await nc_client.notes.update(
-            note_id=note_id,
-            etag=original_etag,  # Use the stale etag
-            title="This update should fail due to conflict",
-            # category=created_note_data["category"] # Pass category if required
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NotesClient, "_make_request", return_value=mock_response
+    )
+
+    client = NotesClient(mock_client, "testuser")
+    note = await client.create_note(
+        title="New Note", content="New content", category="Category"
+    )
+
+    assert note["id"] == 456
+    assert note["title"] == "New Note"
+    assert note["content"] == "New content"
+    assert note["category"] == "Category"
+
+    # Verify the correct API call was made
+    mock_make_request.assert_called_once_with(
+        "POST",
+        "/apps/notes/api/v1/notes",
+        json={"title": "New Note", "content": "New content", "category": "Category"},
+    )
+
+
+async def test_notes_api_update(mocker):
+    """Test that update correctly parses the API response and handles etag."""
+    # Mock the update response (no category passed, so no GET call happens)
+    update_response = create_mock_note_response(
+        note_id=123,
+        title="Updated Title",
+        content="Updated content",
+        category="Test",
+        etag="new_etag",
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+
+    # Mock _make_request to return the update response
+    mock_make_request = mocker.patch.object(NotesClient, "_make_request")
+    mock_make_request.return_value = update_response
+
+    client = NotesClient(mock_client, "testuser")
+    updated_note = await client.update(
+        note_id=123,
+        etag="abc123",
+        title="Updated Title",
+        content="Updated content",
+    )
+
+    assert updated_note["id"] == 123
+    assert updated_note["title"] == "Updated Title"
+    assert updated_note["content"] == "Updated content"
+    assert updated_note["etag"] == "new_etag"
+
+    # Verify the PUT request was made with the correct etag header (only 1 call since no category)
+    assert mock_make_request.call_count == 1
+    put_call = mock_make_request.call_args_list[0]
+    assert put_call[0] == ("PUT", "/apps/notes/api/v1/notes/123")
+    assert put_call[1]["headers"]["If-Match"] == '"abc123"'
+
+
+async def test_notes_api_update_conflict(mocker):
+    """Test that update raises HTTPStatusError on 412 conflict."""
+    # Mock the 412 error response
+    error_response = create_mock_error_response(412, "Precondition Failed")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(NotesClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "412 Precondition Failed",
+        request=httpx.Request("PUT", "http://test.local"),
+        response=error_response,
+    )
+
+    client = NotesClient(mock_client, "testuser")
+
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.update(
+            note_id=123,
+            etag="old_etag",
+            title="This should fail",
         )
-    assert excinfo.value.response.status_code == 412  # Precondition Failed
-    logger.info("Update with old etag correctly failed with 412 Precondition Failed.")
+
+    assert excinfo.value.response.status_code == 412
 
 
-async def test_notes_api_delete_nonexistent(nc_client: NextcloudClient):
-    """
-    Tests deleting a note that doesn't exist fails with 404.
-    """
-    non_existent_id = 999999999  # Use an ID highly unlikely to exist
-    logger.info(f"\nAttempting to delete non-existent note ID: {non_existent_id}")
-    with pytest.raises(HTTPStatusError) as excinfo:
-        await nc_client.notes.delete_note(note_id=non_existent_id)
+async def test_notes_api_delete_note(mocker):
+    """Test that delete_note makes the correct API call."""
+    # Mock get_note response (to fetch category for cleanup)
+    get_response = create_mock_note_response(note_id=123, category="Test")
+
+    # Mock delete response
+    delete_response = create_mock_note_response(note_id=123)
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(NotesClient, "_make_request")
+    mock_make_request.side_effect = [get_response, delete_response]
+
+    client = NotesClient(mock_client, "testuser")
+    await client.delete_note(note_id=123)
+
+    # Verify DELETE was called
+    assert any(call[0][0] == "DELETE" for call in mock_make_request.call_args_list)
+
+
+async def test_notes_api_delete_nonexistent(mocker):
+    """Test that deleting a non-existent note raises 404."""
+    # Mock 404 error when fetching note details
+    error_response = create_mock_error_response(404, "Not Found")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(NotesClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "404 Not Found",
+        request=httpx.Request("GET", "http://test.local"),
+        response=error_response,
+    )
+
+    client = NotesClient(mock_client, "testuser")
+
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.delete_note(note_id=999999999)
+
     assert excinfo.value.response.status_code == 404
-    logger.info(
-        f"Deleting non-existent note ID: {non_existent_id} correctly failed with 404."
+
+
+async def test_notes_api_append_content(mocker):
+    """Test that append_content correctly appends to existing content."""
+    # Mock get_note response (to fetch current content)
+    get_response = create_mock_note_response(
+        note_id=123,
+        content="Original content",
+        etag="old_etag",
     )
 
-
-async def test_notes_api_append_content_to_existing_note(
-    nc_client: NextcloudClient, temporary_note: dict
-):
-    """
-    Tests appending content to an existing note using the new append functionality.
-    """
-    created_note_data = temporary_note
-    note_id = created_note_data["id"]
-    original_content = created_note_data["content"]
-
-    append_text = f"Appended content {uuid.uuid4().hex[:8]}"
-
-    logger.info(f"Appending content to note ID: {note_id}")
-    updated_note = await nc_client.notes.append_content(
-        note_id=note_id, content=append_text
+    # Mock update response with appended content
+    update_response = create_mock_note_response(
+        note_id=123,
+        content="Original content\n---\nAppended content",
+        etag="new_etag",
     )
-    logger.info(f"Note after append: {updated_note}")
 
-    # Verify the note was updated
-    assert updated_note["id"] == note_id
-    assert "etag" in updated_note
-    assert updated_note["etag"] != created_note_data["etag"]  # Etag must change
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(NotesClient, "_make_request")
+    # First call: GET (from get_note), second call: PUT (from update)
+    mock_make_request.side_effect = [get_response, update_response]
 
-    # Verify content has the separator and appended text
-    expected_content = original_content + "\n---\n" + append_text
-    assert updated_note["content"] == expected_content
+    client = NotesClient(mock_client, "testuser")
+    updated_note = await client.append_content(note_id=123, content="Appended content")
 
-    # Verify by reading the note again
-    await asyncio.sleep(1)  # Allow potential propagation delay
-    read_note = await nc_client.notes.get_note(note_id=note_id)
-    assert read_note["content"] == expected_content
-    logger.info(f"Successfully appended content to note ID: {note_id}")
+    assert updated_note["content"] == "Original content\n---\nAppended content"
+    assert updated_note["etag"] == "new_etag"
 
 
-async def test_notes_api_append_content_to_empty_note(nc_client: NextcloudClient):
-    """
-    Tests appending content to an empty note (no separator should be added).
-    """
-    # Create an empty note
-    test_title = f"Empty Note {uuid.uuid4().hex[:8]}"
-    test_category = "Test"
-
-    logger.info("Creating empty note for append test")
-    empty_note = await nc_client.notes.create_note(
-        title=test_title,
+async def test_notes_api_append_content_to_empty_note(mocker):
+    """Test that appending to empty note doesn't add separator."""
+    # Mock get_note response with empty content
+    get_response = create_mock_note_response(
+        note_id=123,
         content="",
-        category=test_category,  # Empty content
-    )
-    note_id = empty_note["id"]
-
-    try:
-        append_text = f"First content {uuid.uuid4().hex[:8]}"
-
-        logger.info(f"Appending content to empty note ID: {note_id}")
-        updated_note = await nc_client.notes.append_content(
-            note_id=note_id, content=append_text
-        )
-
-        # For empty notes, content should just be the appended text (no separator)
-        assert updated_note["content"] == append_text
-
-        # Verify by reading the note again
-        await asyncio.sleep(1)
-        read_note = await nc_client.notes.get_note(note_id=note_id)
-        assert read_note["content"] == append_text
-        logger.info(f"Successfully appended content to empty note ID: {note_id}")
-
-    finally:
-        # Clean up the test note
-        try:
-            await nc_client.notes.delete_note(note_id=note_id)
-            logger.info(f"Cleaned up test note ID: {note_id}")
-        except Exception as e:
-            logger.warning(f"Failed to clean up test note ID: {note_id}: {e}")
-
-
-async def test_notes_api_append_content_multiple_times(
-    nc_client: NextcloudClient, temporary_note: dict
-):
-    """
-    Tests appending content multiple times to verify separator behavior.
-    """
-    created_note_data = temporary_note
-    note_id = created_note_data["id"]
-    original_content = created_note_data["content"]
-
-    first_append = f"First append {uuid.uuid4().hex[:8]}"
-    second_append = f"Second append {uuid.uuid4().hex[:8]}"
-
-    logger.info(f"Performing multiple appends to note ID: {note_id}")
-
-    # First append
-    updated_note = await nc_client.notes.append_content(
-        note_id=note_id, content=first_append
+        etag="old_etag",
     )
 
-    expected_content_after_first = original_content + "\n---\n" + first_append
-    assert updated_note["content"] == expected_content_after_first
-
-    # Second append
-    updated_note = await nc_client.notes.append_content(
-        note_id=note_id, content=second_append
+    # Mock update response with just the appended text (no separator)
+    update_response = create_mock_note_response(
+        note_id=123,
+        content="First content",
+        etag="new_etag",
     )
 
-    expected_content_after_second = (
-        expected_content_after_first + "\n---\n" + second_append
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(NotesClient, "_make_request")
+    # First call: GET (from get_note), second call: PUT (from update)
+    mock_make_request.side_effect = [get_response, update_response]
+
+    client = NotesClient(mock_client, "testuser")
+    updated_note = await client.append_content(note_id=123, content="First content")
+
+    # For empty notes, no separator should be added
+    assert updated_note["content"] == "First content"
+
+
+async def test_notes_api_append_content_nonexistent_note(mocker):
+    """Test that appending to a non-existent note raises 404."""
+    error_response = create_mock_error_response(404, "Not Found")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(NotesClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "404 Not Found",
+        request=httpx.Request("GET", "http://test.local"),
+        response=error_response,
     )
-    assert updated_note["content"] == expected_content_after_second
 
-    # Verify by reading the note again
-    await asyncio.sleep(1)
-    read_note = await nc_client.notes.get_note(note_id=note_id)
-    assert read_note["content"] == expected_content_after_second
-    logger.info(f"Successfully performed multiple appends to note ID: {note_id}")
+    client = NotesClient(mock_client, "testuser")
 
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.append_content(note_id=999999999, content="This should fail")
 
-async def test_notes_api_append_content_nonexistent_note(nc_client: NextcloudClient):
-    """
-    Tests that appending to a non-existent note fails with 404.
-    """
-    non_existent_id = 999999999
-
-    logger.info(f"Attempting to append to non-existent note ID: {non_existent_id}")
-    with pytest.raises(HTTPStatusError) as excinfo:
-        await nc_client.notes.append_content(
-            note_id=non_existent_id, content="This should fail"
-        )
     assert excinfo.value.response.status_code == 404
-    logger.info(
-        f"Appending to non-existent note ID: {non_existent_id} correctly failed with 404."
-    )

tests/client/tables/test_tables_api.py

@@ -1,535 +1,326 @@
-import asyncio
 import logging
-import uuid
-from typing import Any, Dict
 
+import httpx
 import pytest
-from httpx import HTTPStatusError
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.client.tables import TablesClient
+from tests.client.conftest import (
+    create_mock_error_response,
+    create_mock_response,
+    create_mock_table_row_ocs_response,
+    create_mock_table_row_response,
+    create_mock_table_schema_response,
+    create_mock_tables_list_response,
+)
 
 logger = logging.getLogger(__name__)
 
-# Mark all tests in this module as integration tests
-pytestmark = pytest.mark.integration
+# Mark all tests in this module as unit tests
+pytestmark = pytest.mark.unit
 
 
-@pytest.fixture(scope="module")
-async def sample_table_info(nc_client: NextcloudClient) -> Dict[str, Any]:
-    """
-    Fixture to get information about the sample table that comes with Nextcloud Tables.
-    This assumes that the sample table exists in the Nextcloud instance.
-    """
-    logger.info("Looking for sample table in Nextcloud Tables app")
+async def test_tables_list_tables(mocker):
+    """Test that list_tables correctly parses the API response (OCS format)."""
+    mock_response = create_mock_tables_list_response(
+        tables=[
+            {"id": 1, "title": "Table 1"},
+            {"id": 2, "title": "Table 2"},
+        ]
+    )
 
-    # Get all tables
-    tables = await nc_client.tables.list_tables()
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        TablesClient, "_make_request", return_value=mock_response
+    )
 
-    # Look for a sample table (usually created by default)
-    sample_table = None
-    for table in tables:
-        # Common names for sample tables
-        if any(
-            keyword in table.get("title", "").lower()
-            for keyword in ["sample", "demo", "example", "test"]
-        ):
-            sample_table = table
-            break
-
-    if not sample_table and tables:
-        # If no sample table found, use the first available table
-        sample_table = tables[0]
-        logger.info(
-            f"No sample table found, using first available table: {sample_table.get('title')}"
-        )
-
-    if not sample_table:
-        pytest.skip(
-            "No tables found in Nextcloud Tables app. Please ensure Tables app is installed and has at least one table."
-        )
-
-    # Get the schema for the sample table
-    table_id = sample_table["id"]
-    schema = await nc_client.tables.get_table_schema(table_id)
-
-    logger.info(f"Using sample table: {sample_table.get('title')} (ID: {table_id})")
-
-    return {
-        "table": sample_table,
-        "schema": schema,
-        "table_id": table_id,
-        "columns": schema.get("columns", []),
-    }
-
-
-@pytest.fixture
-async def temporary_table_row(
-    nc_client: NextcloudClient, sample_table_info: Dict[str, Any]
-):
-    """
-    Fixture to create a temporary row in the sample table for testing.
-    Yields the created row data and cleans up afterward.
-    """
-    table_id = sample_table_info["table_id"]
-    columns = sample_table_info["columns"]
-
-    # Create test data based on the table schema
-    test_data = {}
-    unique_suffix = uuid.uuid4().hex[:8]
-
-    for column in columns:
-        column_id = column["id"]
-        column_type = column.get("type", "text")
-        column_title = column.get("title", f"column_{column_id}")
-
-        # Generate test data based on column type
-        if column_type == "text":
-            test_data[column_id] = f"Test {column_title} {unique_suffix}"
-        elif column_type == "number":
-            test_data[column_id] = 42
-        elif column_type == "datetime":
-            test_data[column_id] = "2024-01-01T12:00:00Z"
-        elif column_type == "select":
-            # For select columns, use the first option if available
-            options = column.get("selectOptions", [])
-            if options:
-                test_data[column_id] = options[0].get("label", "Option 1")
-            else:
-                test_data[column_id] = "Test Option"
-        else:
-            # Default to text for unknown types
-            test_data[column_id] = f"Test {column_title} {unique_suffix}"
-
-    logger.info(f"Creating temporary row in table {table_id} with data: {test_data}")
-
-    created_row = None
-    try:
-        created_row = await nc_client.tables.create_row(table_id, test_data)
-        row_id = created_row.get("id")
-
-        if not row_id:
-            pytest.fail("Failed to get ID from created temporary row.")
-
-        logger.info(f"Temporary row created with ID: {row_id}")
-        yield created_row
-
-    finally:
-        if created_row and created_row.get("id"):
-            row_id = created_row["id"]
-            logger.info(f"Cleaning up temporary row ID: {row_id}")
-            try:
-                await nc_client.tables.delete_row(row_id)
-                logger.info(f"Successfully deleted temporary row ID: {row_id}")
-            except HTTPStatusError as e:
-                # Ignore 404 if row was already deleted by the test itself
-                if e.response.status_code != 404:
-                    logger.error(f"HTTP error deleting temporary row {row_id}: {e}")
-                else:
-                    logger.warning(f"Temporary row {row_id} already deleted (404).")
-            except Exception as e:
-                logger.error(f"Unexpected error deleting temporary row {row_id}: {e}")
-
-
-async def test_tables_list_tables(nc_client: NextcloudClient):
-    """
-    Test listing all tables available to the user.
-    """
-    logger.info("Testing list_tables functionality")
-
-    tables = await nc_client.tables.list_tables()
+    client = TablesClient(mock_client, "testuser")
+    tables = await client.list_tables()
 
     assert isinstance(tables, list)
-    assert len(tables) > 0, "Expected at least one table to be available"
+    assert len(tables) == 2
+    assert tables[0]["id"] == 1
+    assert tables[0]["title"] == "Table 1"
 
-    # Check that each table has required fields
-    for table in tables:
-        assert "id" in table
-        assert "title" in table
-        assert isinstance(table["id"], int)
-        assert isinstance(table["title"], str)
-
-    logger.info(f"Successfully listed {len(tables)} tables")
+    mock_make_request.assert_called_once()
 
 
-async def test_tables_get_schema(
-    nc_client: NextcloudClient, sample_table_info: Dict[str, Any]
-):
-    """
-    Test getting the schema/structure of a specific table.
-    """
-    table_id = sample_table_info["table_id"]
+async def test_tables_get_schema(mocker):
+    """Test that get_table_schema correctly parses the API response."""
+    mock_response = create_mock_table_schema_response(
+        table_id=123,
+        columns=[
+            {"id": 1, "title": "Name", "type": "text"},
+            {"id": 2, "title": "Age", "type": "number"},
+            {"id": 3, "title": "Email", "type": "text"},
+        ],
+    )
 
-    logger.info(f"Testing get_table_schema for table ID: {table_id}")
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        TablesClient, "_make_request", return_value=mock_response
+    )
 
-    schema = await nc_client.tables.get_table_schema(table_id)
+    client = TablesClient(mock_client, "testuser")
+    schema = await client.get_table_schema(table_id=123)
 
     assert isinstance(schema, dict)
     assert "columns" in schema
-    assert isinstance(schema["columns"], list)
-    assert len(schema["columns"]) > 0, "Expected at least one column in the table"
+    assert len(schema["columns"]) == 3
+    assert schema["columns"][0]["title"] == "Name"
 
-    # Check that each column has required fields
-    for column in schema["columns"]:
-        assert "id" in column
-        assert "title" in column
-        assert "type" in column
-        assert isinstance(column["id"], int)
-        assert isinstance(column["title"], str)
-        assert isinstance(column["type"], str)
-
-    logger.info(f"Successfully retrieved schema with {len(schema['columns'])} columns")
+    mock_make_request.assert_called_once()
+    assert "/tables/123/scheme" in mock_make_request.call_args[0][1]
 
 
-async def test_tables_read_table(
-    nc_client: NextcloudClient, sample_table_info: Dict[str, Any]
-):
-    """
-    Test reading rows from a table.
-    """
-    table_id = sample_table_info["table_id"]
+async def test_tables_get_rows(mocker):
+    """Test that get_table_rows correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data=[
+            {
+                "id": 1,
+                "tableId": 123,
+                "data": [
+                    {"columnId": 1, "value": "John"},
+                    {"columnId": 2, "value": 30},
+                ],
+                "createdBy": "testuser",
+                "createdAt": "2024-01-01T00:00:00+00:00",
+                "lastEditBy": "testuser",
+                "lastEditAt": "2024-01-01T00:00:00+00:00",
+            },
+            {
+                "id": 2,
+                "tableId": 123,
+                "data": [
+                    {"columnId": 1, "value": "Jane"},
+                    {"columnId": 2, "value": 25},
+                ],
+                "createdBy": "testuser",
+                "createdAt": "2024-01-01T00:00:00+00:00",
+                "lastEditBy": "testuser",
+                "lastEditAt": "2024-01-01T00:00:00+00:00",
+            },
+        ],
+    )
 
-    logger.info(f"Testing get_table_rows for table ID: {table_id}")
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        TablesClient, "_make_request", return_value=mock_response
+    )
 
-    # Test without pagination
-    rows = await nc_client.tables.get_table_rows(table_id)
+    client = TablesClient(mock_client, "testuser")
+    rows = await client.get_table_rows(table_id=123)
 
     assert isinstance(rows, list)
-    # Note: The table might be empty, so we don't assert len > 0
+    assert len(rows) == 2
+    assert rows[0]["id"] == 1
+    assert rows[0]["tableId"] == 123
 
-    # Test with pagination
-    rows_limited = await nc_client.tables.get_table_rows(table_id, limit=5, offset=0)
-
-    assert isinstance(rows_limited, list)
-    assert len(rows_limited) <= 5
-
-    # If there are rows, check their structure
-    if rows:
-        row = rows[0]
-        assert "id" in row
-        assert "tableId" in row
-        assert "data" in row
-        assert isinstance(row["id"], int)
-        assert isinstance(row["tableId"], int)
-        assert isinstance(row["data"], list)
-
-    logger.info(f"Successfully read {len(rows)} rows from table")
+    mock_make_request.assert_called_once()
 
 
-async def test_tables_create_row(
-    nc_client: NextcloudClient, sample_table_info: Dict[str, Any]
-):
-    """
-    Test creating a new row in a table.
-    """
-    table_id = sample_table_info["table_id"]
-    columns = sample_table_info["columns"]
+async def test_tables_get_rows_with_pagination(mocker):
+    """Test that get_table_rows correctly handles pagination parameters."""
+    mock_response = create_mock_response(
+        status_code=200,
+        json_data=[
+            {
+                "id": 1,
+                "tableId": 123,
+                "data": [],
+                "createdBy": "testuser",
+                "createdAt": "2024-01-01T00:00:00+00:00",
+                "lastEditBy": "testuser",
+                "lastEditAt": "2024-01-01T00:00:00+00:00",
+            },
+        ],
+    )
 
-    # Create test data based on the table schema
-    test_data = {}
-    unique_suffix = uuid.uuid4().hex[:8]
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        TablesClient, "_make_request", return_value=mock_response
+    )
 
-    for column in columns:
-        column_id = column["id"]
-        column_type = column.get("type", "text")
-        column_title = column.get("title", f"column_{column_id}")
+    client = TablesClient(mock_client, "testuser")
+    rows = await client.get_table_rows(table_id=123, limit=5, offset=10)
 
-        # Generate test data based on column type
-        if column_type == "text":
-            test_data[column_id] = f"Test Create {column_title} {unique_suffix}"
-        elif column_type == "number":
-            test_data[column_id] = 123
-        elif column_type == "datetime":
-            test_data[column_id] = "2024-01-01T12:00:00Z"
-        elif column_type == "select":
-            # For select columns, use the first option if available
-            options = column.get("selectOptions", [])
-            if options:
-                test_data[column_id] = options[0].get("label", "Option 1")
-            else:
-                test_data[column_id] = "Test Option"
-        else:
-            # Default to text for unknown types
-            test_data[column_id] = f"Test Create {column_title} {unique_suffix}"
+    assert isinstance(rows, list)
 
-    logger.info(f"Testing create_row for table ID: {table_id} with data: {test_data}")
-
-    created_row = None
-    try:
-        created_row = await nc_client.tables.create_row(table_id, test_data)
-
-        assert isinstance(created_row, dict)
-        assert "id" in created_row
-        assert "tableId" in created_row
-        assert isinstance(created_row["id"], int)
-        assert created_row["tableId"] == table_id
-
-        # Verify the row was created by reading it back
-        await asyncio.sleep(1)  # Allow potential propagation delay
-        rows = await nc_client.tables.get_table_rows(table_id)
-        created_row_id = created_row["id"]
-
-        # Find the created row in the results
-        found_row = None
-        for row in rows:
-            if row["id"] == created_row_id:
-                found_row = row
-                break
-
-        assert found_row is not None, (
-            f"Created row with ID {created_row_id} not found in table"
-        )
-
-        logger.info(f"Successfully created row with ID: {created_row_id}")
-
-    finally:
-        # Clean up the created row
-        if created_row and created_row.get("id"):
-            try:
-                await nc_client.tables.delete_row(created_row["id"])
-                logger.info(f"Cleaned up created row ID: {created_row['id']}")
-            except Exception as e:
-                logger.warning(f"Failed to clean up created row: {e}")
+    # Verify pagination parameters were passed
+    call_args = mock_make_request.call_args
+    assert call_args[1]["params"]["limit"] == 5
+    assert call_args[1]["params"]["offset"] == 10
 
 
-async def test_tables_update_row(
-    nc_client: NextcloudClient,
-    temporary_table_row: Dict[str, Any],
-    sample_table_info: Dict[str, Any],
-):
-    """
-    Test updating an existing row in a table.
-    """
-    row_id = temporary_table_row["id"]
-    columns = sample_table_info["columns"]
+async def test_tables_create_row(mocker):
+    """Test that create_row correctly parses the API response (OCS format)."""
+    mock_response = create_mock_table_row_ocs_response(
+        row_id=456,
+        table_id=123,
+        data=[
+            {"columnId": 1, "value": "Test Name"},
+            {"columnId": 2, "value": 99},
+        ],
+    )
 
-    # Create updated data
-    update_data = {}
-    unique_suffix = uuid.uuid4().hex[:8]
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        TablesClient, "_make_request", return_value=mock_response
+    )
 
-    for column in columns:
-        column_id = column["id"]
-        column_type = column.get("type", "text")
-        column_title = column.get("title", f"column_{column_id}")
+    client = TablesClient(mock_client, "testuser")
+    test_data = {1: "Test Name", 2: 99}
+    created_row = await client.create_row(table_id=123, data=test_data)
 
-        # Generate updated test data based on column type
-        if column_type == "text":
-            update_data[column_id] = f"Updated {column_title} {unique_suffix}"
-        elif column_type == "number":
-            update_data[column_id] = 456
-        elif column_type == "datetime":
-            update_data[column_id] = "2024-12-31T23:59:59Z"
-        elif column_type == "select":
-            # For select columns, use the first option if available
-            options = column.get("selectOptions", [])
-            if options:
-                update_data[column_id] = options[0].get("label", "Option 1")
-            else:
-                update_data[column_id] = "Updated Option"
-        else:
-            # Default to text for unknown types
-            update_data[column_id] = f"Updated {column_title} {unique_suffix}"
+    assert isinstance(created_row, dict)
+    assert created_row["id"] == 456
+    assert created_row["tableId"] == 123
 
-    logger.info(f"Testing update_row for row ID: {row_id} with data: {update_data}")
+    # Verify the data was transformed to string keys
+    call_args = mock_make_request.call_args
+    assert call_args[1]["json"]["data"]["1"] == "Test Name"
+    assert call_args[1]["json"]["data"]["2"] == 99
 
-    updated_row = await nc_client.tables.update_row(row_id, update_data)
+
+async def test_tables_update_row(mocker):
+    """Test that update_row correctly parses the API response."""
+    mock_response = create_mock_table_row_response(
+        row_id=456,
+        table_id=123,
+        data=[
+            {"columnId": 1, "value": "Updated Name"},
+            {"columnId": 2, "value": 100},
+        ],
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        TablesClient, "_make_request", return_value=mock_response
+    )
+
+    client = TablesClient(mock_client, "testuser")
+    update_data = {1: "Updated Name", 2: 100}
+    updated_row = await client.update_row(row_id=456, data=update_data)
 
     assert isinstance(updated_row, dict)
-    assert "id" in updated_row
-    assert updated_row["id"] == row_id
+    assert updated_row["id"] == 456
 
-    # Verify the row was updated by reading it back
-    await asyncio.sleep(1)  # Allow potential propagation delay
-    table_id = sample_table_info["table_id"]
-    rows = await nc_client.tables.get_table_rows(table_id)
-
-    # Find the updated row in the results
-    found_row = None
-    for row in rows:
-        if row["id"] == row_id:
-            found_row = row
-            break
-
-    assert found_row is not None, f"Updated row with ID {row_id} not found in table"
-
-    logger.info(f"Successfully updated row with ID: {row_id}")
+    # Verify the PUT request was made
+    call_args = mock_make_request.call_args
+    assert call_args[0][0] == "PUT"
+    assert "/rows/456" in call_args[0][1]
 
 
-async def test_tables_delete_row(
-    nc_client: NextcloudClient, sample_table_info: Dict[str, Any]
-):
-    """
-    Test deleting a row from a table.
-    """
-    table_id = sample_table_info["table_id"]
-    columns = sample_table_info["columns"]
-
-    # First create a row to delete
-    test_data = {}
-    unique_suffix = uuid.uuid4().hex[:8]
-
-    for column in columns:
-        column_id = column["id"]
-        column_type = column.get("type", "text")
-        column_title = column.get("title", f"column_{column_id}")
-
-        if column_type == "text":
-            test_data[column_id] = f"Test Delete {column_title} {unique_suffix}"
-        elif column_type == "number":
-            test_data[column_id] = 789
-        elif column_type == "datetime":
-            test_data[column_id] = "2024-06-15T10:30:00Z"
-        elif column_type == "select":
-            options = column.get("selectOptions", [])
-            if options:
-                test_data[column_id] = options[0].get("label", "Option 1")
-            else:
-                test_data[column_id] = "Delete Option"
-        else:
-            test_data[column_id] = f"Test Delete {column_title} {unique_suffix}"
-
-    logger.info(f"Creating row for delete test in table ID: {table_id}")
-
-    created_row = await nc_client.tables.create_row(table_id, test_data)
-    row_id = created_row["id"]
-
-    logger.info(f"Testing delete_row for row ID: {row_id}")
-
-    # Delete the row
-    delete_result = await nc_client.tables.delete_row(row_id)
-
-    assert isinstance(delete_result, dict)
-    # The delete response might vary, but it should be successful
-
-    # Verify the row was deleted by trying to find it
-    await asyncio.sleep(1)  # Allow potential propagation delay
-    rows = await nc_client.tables.get_table_rows(table_id)
-
-    # Ensure the deleted row is not in the results
-    found_row = None
-    for row in rows:
-        if row["id"] == row_id:
-            found_row = row
-            break
-
-    assert found_row is None, f"Deleted row with ID {row_id} still found in table"
-
-    logger.info(f"Successfully deleted row with ID: {row_id}")
-
-
-async def test_tables_delete_nonexistent_row(nc_client: NextcloudClient):
-    """
-    Test that deleting a non-existent row fails appropriately.
-    """
-    non_existent_id = 999999999  # Use an ID highly unlikely to exist
-
-    logger.info(f"Testing delete_row for non-existent row ID: {non_existent_id}")
-
-    with pytest.raises(HTTPStatusError) as excinfo:
-        await nc_client.tables.delete_row(non_existent_id)
-
-    # Accept both 404 and 500 as valid error responses for non-existent rows
-    # The API behavior may vary between Nextcloud versions
-    assert excinfo.value.response.status_code in [404, 500]
-    logger.info(
-        f"Deleting non-existent row ID: {non_existent_id} correctly failed with {excinfo.value.response.status_code}."
+async def test_tables_delete_row(mocker):
+    """Test that delete_row correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200, json_data={"message": "Row deleted"}
     )
 
-
-async def test_tables_transform_row_data(
-    nc_client: NextcloudClient, sample_table_info: Dict[str, Any]
-):
-    """
-    Test the transform_row_data utility method.
-    """
-    table_id = sample_table_info["table_id"]
-    columns = sample_table_info["columns"]
-
-    logger.info(f"Testing transform_row_data for table ID: {table_id}")
-
-    # Get some rows to transform
-    rows = await nc_client.tables.get_table_rows(table_id, limit=5)
-
-    if not rows:
-        logger.info("No rows to transform, skipping transform_row_data test")
-        return
-
-    # Transform the rows
-    transformed_rows = nc_client.tables.transform_row_data(rows, columns)
-
-    assert isinstance(transformed_rows, list)
-    assert len(transformed_rows) == len(rows)
-
-    # Check the structure of transformed rows
-    for i, transformed_row in enumerate(transformed_rows):
-        original_row = rows[i]
-
-        assert "id" in transformed_row
-        assert "tableId" in transformed_row
-        assert "data" in transformed_row
-        assert transformed_row["id"] == original_row["id"]
-        assert transformed_row["tableId"] == original_row["tableId"]
-        assert isinstance(transformed_row["data"], dict)
-
-        # Check that column IDs were transformed to column names
-        for column in columns:
-            column_title = column["title"]
-            # The transformed data should have column names as keys
-            # (though the column might not have data in this row)
-            if any(item["columnId"] == column["id"] for item in original_row["data"]):
-                assert column_title in transformed_row["data"]
-
-    logger.info(f"Successfully transformed {len(transformed_rows)} rows")
-
-
-async def test_tables_get_nonexistent_table_schema(nc_client: NextcloudClient):
-    """
-    Test that getting schema for a non-existent table fails appropriately.
-    """
-    non_existent_id = 999999999  # Use an ID highly unlikely to exist
-
-    logger.info(
-        f"Testing get_table_schema for non-existent table ID: {non_existent_id}"
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        TablesClient, "_make_request", return_value=mock_response
     )
 
-    with pytest.raises(HTTPStatusError) as excinfo:
-        await nc_client.tables.get_table_schema(non_existent_id)
+    client = TablesClient(mock_client, "testuser")
+    result = await client.delete_row(row_id=456)
+
+    assert isinstance(result, dict)
+
+    # Verify the DELETE request was made
+    call_args = mock_make_request.call_args
+    assert call_args[0][0] == "DELETE"
+    assert "/rows/456" in call_args[0][1]
+
+
+async def test_tables_delete_nonexistent_row(mocker):
+    """Test that deleting a non-existent row raises HTTPStatusError."""
+    error_response = create_mock_error_response(404, "Row not found")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(TablesClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "404 Not Found",
+        request=httpx.Request("DELETE", "http://test.local"),
+        response=error_response,
+    )
+
+    client = TablesClient(mock_client, "testuser")
+
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.delete_row(row_id=999999999)
 
     assert excinfo.value.response.status_code == 404
-    logger.info(
-        f"Getting schema for non-existent table ID: {non_existent_id} correctly failed with 404."
+
+
+async def test_tables_get_nonexistent_schema(mocker):
+    """Test that getting schema for non-existent table raises HTTPStatusError."""
+    error_response = create_mock_error_response(404, "Table not found")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(TablesClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "404 Not Found",
+        request=httpx.Request("GET", "http://test.local"),
+        response=error_response,
     )
 
+    client = TablesClient(mock_client, "testuser")
 
-async def test_tables_read_nonexistent_table(nc_client: NextcloudClient):
-    """
-    Test that reading from a non-existent table fails appropriately.
-    """
-    non_existent_id = 999999999  # Use an ID highly unlikely to exist
-
-    logger.info(f"Testing get_table_rows for non-existent table ID: {non_existent_id}")
-
-    with pytest.raises(HTTPStatusError) as excinfo:
-        await nc_client.tables.get_table_rows(non_existent_id)
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.get_table_schema(table_id=999999999)
 
     assert excinfo.value.response.status_code == 404
-    logger.info(
-        f"Reading from non-existent table ID: {non_existent_id} correctly failed with 404."
-    )
 
 
-async def test_tables_create_row_invalid_table(nc_client: NextcloudClient):
-    """
-    Test that creating a row in a non-existent table fails appropriately.
-    """
-    non_existent_id = 999999999  # Use an ID highly unlikely to exist
-    test_data = {1: "test value"}
+def test_tables_transform_row_data():
+    """Test the transform_row_data utility method (synchronous)."""
+    # This is a pure function, no mocking needed
+    client = TablesClient(None, "testuser")  # Client not used for this method
 
-    logger.info(f"Testing create_row for non-existent table ID: {non_existent_id}")
+    raw_rows = [
+        {
+            "id": 1,
+            "tableId": 123,
+            "createdBy": "testuser",
+            "createdAt": "2024-01-01T00:00:00+00:00",
+            "lastEditBy": "testuser",
+            "lastEditAt": "2024-01-01T00:00:00+00:00",
+            "data": [
+                {"columnId": 1, "value": "John Doe"},
+                {"columnId": 2, "value": 30},
+                {"columnId": 3, "value": "john@example.com"},
+            ],
+        },
+        {
+            "id": 2,
+            "tableId": 123,
+            "createdBy": "testuser",
+            "createdAt": "2024-01-01T00:00:00+00:00",
+            "lastEditBy": "testuser",
+            "lastEditAt": "2024-01-01T00:00:00+00:00",
+            "data": [
+                {"columnId": 1, "value": "Jane Smith"},
+                {"columnId": 2, "value": 25},
+                {"columnId": 3, "value": "jane@example.com"},
+            ],
+        },
+    ]
 
-    with pytest.raises(HTTPStatusError) as excinfo:
-        await nc_client.tables.create_row(non_existent_id, test_data)
+    columns = [
+        {"id": 1, "title": "Name", "type": "text"},
+        {"id": 2, "title": "Age", "type": "number"},
+        {"id": 3, "title": "Email", "type": "text"},
+    ]
 
-    assert excinfo.value.response.status_code == 404
-    logger.info(
-        f"Creating row in non-existent table ID: {non_existent_id} correctly failed with 404."
-    )
+    transformed = client.transform_row_data(raw_rows, columns)
+
+    assert len(transformed) == 2
+    assert transformed[0]["id"] == 1
+    assert transformed[0]["data"]["Name"] == "John Doe"
+    assert transformed[0]["data"]["Age"] == 30
+    assert transformed[0]["data"]["Email"] == "john@example.com"
+
+    assert transformed[1]["data"]["Name"] == "Jane Smith"
+    assert transformed[1]["data"]["Age"] == 25

tests/client/test_sharing_api.py

@@ -9,7 +9,6 @@ logger = logging.getLogger(__name__)
 pytestmark = pytest.mark.integration
 
 
-@pytest.mark.anyio
 async def test_create_and_delete_share(nc_client):
     """Test creating and deleting a file share."""
     # Create a test user to share with
@@ -68,7 +67,6 @@ async def test_create_and_delete_share(nc_client):
             pass
 
 
-@pytest.mark.anyio
 async def test_update_share_permissions(nc_client):
     """Test updating share permissions."""
     # Create a test user to share with
@@ -120,7 +118,6 @@ async def test_update_share_permissions(nc_client):
             pass
 
 
-@pytest.mark.anyio
 async def test_list_shares(nc_client):
     """Test listing all shares."""
     # Create a test user to share with

tests/conftest.py

@@ -1,9 +1,9 @@
-import asyncio
 import logging
 import os
 import uuid
 from typing import Any, AsyncGenerator
 
+import anyio
 import httpx
 import pytest
 from httpx import HTTPStatusError
@@ -14,6 +14,48 @@ from nextcloud_mcp_server.client import NextcloudClient
 
 logger = logging.getLogger(__name__)
 
+# Default scopes for OAuth testing - all app-specific read/write scopes
+DEFAULT_FULL_SCOPES = (
+    "openid profile email "
+    "notes:read notes:write "
+    "calendar:read calendar:write "
+    "todo:read todo:write "
+    "contacts:read contacts:write "
+    "cookbook:read cookbook:write "
+    "deck:read deck:write "
+    "tables:read tables:write "
+    "files:read files:write "
+    "sharing:read sharing:write"
+)
+
+# Read-only scopes (all read scopes across apps) - should match DEFAULT_FULL_SCOPES read portion
+DEFAULT_READ_SCOPES = (
+    "openid profile email "
+    "notes:read "
+    "calendar:read "
+    "todo:read "
+    "contacts:read "
+    "cookbook:read "
+    "deck:read "
+    "tables:read "
+    "files:read "
+    "sharing:read"
+)
+
+# Write-only scopes (all write scopes across apps) - should match DEFAULT_FULL_SCOPES write portion
+DEFAULT_WRITE_SCOPES = (
+    "openid profile email "
+    "notes:write "
+    "calendar:write "
+    "todo:write "
+    "contacts:write "
+    "cookbook:write "
+    "deck:write "
+    "tables:write "
+    "files:write "
+    "sharing:write"
+)
+
 
 @pytest.fixture(scope="session")
 def anyio_backend():
@@ -56,7 +98,7 @@ async def wait_for_nextcloud(
                 logger.info(
                     f"Nextcloud not ready yet, waiting {delay}s... (attempt {attempt}/{max_attempts})"
                 )
-                await asyncio.sleep(delay)
+                await anyio.sleep(delay)
 
     logger.error(
         f"Nextcloud server at {host} did not become ready after {max_attempts} attempts"
@@ -191,18 +233,18 @@ async def nc_mcp_oauth_jwt_client(
 ) -> AsyncGenerator[ClientSession, Any]:
     """
     Fixture to create an MCP client session for JWT OAuth integration tests.
-    Connects to the JWT OAuth-enabled MCP server on port 8002 with OAuth authentication.
+    Connects to the OAuth-enabled MCP server on port 8001 with JWT token authentication.
 
-    This server uses JWT tokens (RFC 9068) instead of opaque tokens, enabling:
-    - Token introspection via JWT signature verification
+    Uses JWT tokens (RFC 9068) which provide:
+    - Token validation via JWT signature verification (JWKS)
     - Scope information embedded in token claims
-    - Offline token validation without userinfo endpoint
+    - Faster validation without userinfo endpoint call
 
     Uses headless browser automation suitable for CI/CD.
     Uses anyio pytest plugin for proper async fixture handling.
     """
     async for session in create_mcp_client_session(
-        url="http://localhost:8002/mcp",
+        url="http://localhost:8001/mcp",
         token=playwright_oauth_token_jwt,
         client_name="OAuth JWT MCP (Playwright)",
     ):
@@ -215,17 +257,17 @@ async def nc_mcp_oauth_client_read_only(
     playwright_oauth_token_read_only: str,
 ) -> AsyncGenerator[ClientSession, Any]:
     """
-    Fixture to create an MCP client session with only nc:read scope.
-    Connects to the JWT OAuth-enabled MCP server on port 8002.
+    Fixture to create an MCP client session with only read scopes.
+    Connects to the OAuth-enabled MCP server on port 8001.
 
     This client should only see read tools and should get 403 errors
     when attempting to call write tools.
 
-    Uses JWT MCP server because JWT tokens embed scope information in claims,
-    enabling proper scope-based filtering.
+    Uses JWT tokens because they embed scope information in claims,
+    enabling proper scope-based tool filtering.
     """
     async for session in create_mcp_client_session(
-        url="http://localhost:8002/mcp",
+        url="http://localhost:8001/mcp",
         token=playwright_oauth_token_read_only,
         client_name="OAuth JWT MCP Read-Only (Playwright)",
     ):
@@ -238,17 +280,17 @@ async def nc_mcp_oauth_client_write_only(
     playwright_oauth_token_write_only: str,
 ) -> AsyncGenerator[ClientSession, Any]:
     """
-    Fixture to create an MCP client session with only nc:write scope.
-    Connects to the JWT OAuth-enabled MCP server on port 8002.
+    Fixture to create an MCP client session with only write scopes.
+    Connects to the OAuth-enabled MCP server on port 8001.
 
     This client should only see write tools and should get 403 errors
     when attempting to call read tools.
 
-    Uses JWT MCP server because JWT tokens embed scope information in claims,
-    enabling proper scope-based filtering.
+    Uses JWT tokens because they embed scope information in claims,
+    enabling proper scope-based tool filtering.
     """
     async for session in create_mcp_client_session(
-        url="http://localhost:8002/mcp",
+        url="http://localhost:8001/mcp",
         token=playwright_oauth_token_write_only,
         client_name="OAuth JWT MCP Write-Only (Playwright)",
     ):
@@ -261,16 +303,16 @@ async def nc_mcp_oauth_client_full_access(
     playwright_oauth_token_full_access: str,
 ) -> AsyncGenerator[ClientSession, Any]:
     """
-    Fixture to create an MCP client session with both nc:read and nc:write scopes.
-    Connects to the JWT OAuth-enabled MCP server on port 8002.
+    Fixture to create an MCP client session with both read and write scopes.
+    Connects to the OAuth-enabled MCP server on port 8001.
 
     This client should see all tools and be able to call all operations.
 
-    Uses JWT MCP server because JWT tokens embed scope information in claims,
-    enabling proper scope-based filtering.
+    Uses JWT tokens because they embed scope information in claims,
+    enabling proper scope-based tool filtering.
     """
     async for session in create_mcp_client_session(
-        url="http://localhost:8002/mcp",
+        url="http://localhost:8001/mcp",
         token=playwright_oauth_token_full_access,
         client_name="OAuth JWT MCP Full Access (Playwright)",
     ):
@@ -284,18 +326,18 @@ async def nc_mcp_oauth_client_no_custom_scopes(
 ) -> AsyncGenerator[ClientSession, Any]:
     """
     Fixture to create an MCP client session with NO custom scopes.
-    Connects to the JWT OAuth-enabled MCP server on port 8002.
+    Connects to the OAuth-enabled MCP server on port 8001.
 
     This client has only OIDC default scopes (openid, profile, email) without
-    application-specific scopes (nc:read, nc:write).
+    application-specific scopes (notes:read, notes:write, etc.).
 
     Expected behavior: Should see 0 tools (all tools require custom scopes).
 
-    Uses JWT MCP server because JWT tokens embed scope information in claims,
-    enabling proper scope-based filtering.
+    Uses JWT tokens because they embed scope information in claims,
+    enabling proper scope-based tool filtering.
     """
     async for session in create_mcp_client_session(
-        url="http://localhost:8002/mcp",
+        url="http://localhost:8001/mcp",
         token=playwright_oauth_token_no_custom_scopes,
         client_name="OAuth JWT MCP No Custom Scopes (Playwright)",
     ):
@@ -682,10 +724,9 @@ async def shared_calendar_2(
     try:
         # Wait for first calendar to fully initialize to avoid Nextcloud rate limiting
         # When creating multiple calendars rapidly, Nextcloud may not register them all
-        import asyncio
 
         logger.info("Waiting before creating second calendar to avoid rate limiting...")
-        await asyncio.sleep(3)  # Increased from 2 to 3 seconds
+        await anyio.sleep(3)  # Increased from 2 to 3 seconds
 
         # Create a test calendar
         logger.info(f"Creating second shared test calendar: {calendar_name}")
@@ -703,9 +744,8 @@ async def shared_calendar_2(
 
         # Verify calendar was created by listing calendars
         # Add small delay to allow calendar to propagate in the system
-        import asyncio
 
-        await asyncio.sleep(1.0)  # Allow time for calendar to propagate
+        await anyio.sleep(1.0)  # Allow time for calendar to propagate
 
         calendars = await nc_client.calendar.list_calendars()
         calendar_names = [cal["name"] for cal in calendars]
@@ -714,7 +754,7 @@ async def shared_calendar_2(
                 f"Calendar {calendar_name} not found immediately after creation. Available: {calendar_names}"
             )
             # Try one more time after a longer delay
-            await asyncio.sleep(3)  # Additional wait for calendar synchronization
+            await anyio.sleep(3)  # Additional wait for calendar synchronization
             calendars = await nc_client.calendar.list_calendars()
             calendar_names = [cal["name"] for cal in calendars]
             if calendar_name not in calendar_names:
@@ -912,9 +952,13 @@ async def shared_oauth_client_credentials(anyio_backend, oauth_callback_server):
     server (port 8001). While opaque tokens don't embed scopes, the allowed_scopes
     configuration ensures tokens have proper scopes when introspected.
 
+    The client is automatically deleted from Nextcloud after the test session completes.
+
     Returns:
         Tuple of (client_id, client_secret, callback_url, token_endpoint, authorization_endpoint)
     """
+    from nextcloud_mcp_server.auth.client_registration import delete_client
+
     nextcloud_host = os.getenv("NEXTCLOUD_HOST")
     if not nextcloud_host:
         pytest.skip("Shared OAuth client requires NEXTCLOUD_HOST")
@@ -942,40 +986,68 @@ async def shared_oauth_client_credentials(anyio_backend, oauth_callback_server):
 
         # Create opaque token client with allowed_scopes (not JWT)
         # This ensures the token has proper scopes even though they're not embedded
-        # Cache to file to avoid creating new client on every test run
-        client_id, client_secret = await _create_oauth_client_with_scopes(
+        client_info = await _create_oauth_client_with_scopes(
             callback_url=callback_url,
             client_name="Pytest - Shared Test Client (Opaque)",
-            allowed_scopes="openid profile email nc:read nc:write",
+            allowed_scopes=DEFAULT_FULL_SCOPES,
             token_type="Bearer",  # Opaque tokens for port 8001
-            cache_file=".nextcloud_oauth_shared_test_client.json",
         )
 
-        logger.info(f"Shared OAuth client ready: {client_id[:16]}...")
+        logger.info(f"Shared OAuth client ready: {client_info.client_id[:16]}...")
         logger.info(
             "This opaque token client with full scopes will be reused for all test user authentications"
         )
 
-        return (
-            client_id,
-            client_secret,
+        yield (
+            client_info.client_id,
+            client_info.client_secret,
             callback_url,
             token_endpoint,
             authorization_endpoint,
         )
 
+        # Cleanup: Delete OAuth client from Nextcloud using RFC 7592
+        try:
+            logger.info(
+                f"Cleaning up shared OAuth client: {client_info.client_id[:16]}..."
+            )
+            success = await delete_client(
+                nextcloud_url=nextcloud_host,
+                client_id=client_info.client_id,
+                registration_access_token=client_info.registration_access_token,
+                client_secret=client_info.client_secret,
+                registration_client_uri=client_info.registration_client_uri,
+            )
+            if success:
+                logger.info(
+                    f"Successfully deleted shared OAuth client: {client_info.client_id[:16]}..."
+                )
+            else:
+                logger.warning(
+                    f"Failed to delete shared OAuth client: {client_info.client_id[:16]}..."
+                )
+        except Exception as e:
+            logger.warning(
+                f"Error cleaning up shared OAuth client {client_info.client_id[:16]}...: {e}"
+            )
+
 
 @pytest.fixture(scope="session")
 async def shared_jwt_oauth_client_credentials(anyio_backend, oauth_callback_server):
     """
-    Fixture to obtain shared JWT OAuth client credentials for JWT MCP server.
+    Fixture to obtain shared JWT OAuth client credentials for testing JWT token behavior.
 
-    Creates a JWT OAuth client with full scopes (nc:read and nc:write) for use with
-    the JWT MCP server (port 8002) that validates JWT tokens locally.
+    Creates a JWT OAuth client with full scopes (all app read/write scopes). The client
+    is configured with token_type="JWT" to request JWT-formatted access tokens from the
+    OIDC server (instead of opaque tokens).
+
+    The client is automatically deleted from Nextcloud after the test session completes.
 
     Returns:
         Tuple of (client_id, client_secret, callback_url, token_endpoint, authorization_endpoint)
     """
+    from nextcloud_mcp_server.auth.client_registration import delete_client
+
     nextcloud_host = os.getenv("NEXTCLOUD_HOST")
     if not nextcloud_host:
         pytest.skip("Shared JWT OAuth client requires NEXTCLOUD_HOST")
@@ -1001,76 +1073,73 @@ async def shared_jwt_oauth_client_credentials(anyio_backend, oauth_callback_serv
                 "OIDC discovery missing required endpoints (token_endpoint or authorization_endpoint)"
             )
 
-        # Create JWT client with full scopes (nc:read and nc:write)
-        # Cache to file to avoid creating new client on every test run
-        client_id, client_secret = await _create_oauth_client_with_scopes(
+        # Create JWT client with full scopes (all app read/write scopes)
+        client_info = await _create_oauth_client_with_scopes(
             callback_url=callback_url,
             client_name="Pytest - Shared JWT Test Client",
-            allowed_scopes="openid profile email nc:read nc:write",
+            allowed_scopes=DEFAULT_FULL_SCOPES,
             token_type="JWT",  # Explicitly set JWT token type
-            cache_file=".nextcloud_oauth_shared_jwt_test_client.json",
         )
 
-        logger.info(f"Shared JWT OAuth client ready: {client_id[:16]}...")
+        logger.info(f"Shared JWT OAuth client ready: {client_info.client_id[:16]}...")
         logger.info(
             "This JWT client with full scopes will be reused for JWT MCP server tests"
         )
 
-        return (
-            client_id,
-            client_secret,
+        yield (
+            client_info.client_id,
+            client_info.client_secret,
             callback_url,
             token_endpoint,
             authorization_endpoint,
         )
 
+        # Cleanup: Delete OAuth client from Nextcloud using RFC 7592
+        try:
+            logger.info(
+                f"Cleaning up shared JWT OAuth client: {client_info.client_id[:16]}..."
+            )
+            success = await delete_client(
+                nextcloud_url=nextcloud_host,
+                client_id=client_info.client_id,
+                registration_access_token=client_info.registration_access_token,
+                client_secret=client_info.client_secret,
+                registration_client_uri=client_info.registration_client_uri,
+            )
+            if success:
+                logger.info(
+                    f"Successfully deleted shared JWT OAuth client: {client_info.client_id[:16]}..."
+                )
+            else:
+                logger.warning(
+                    f"Failed to delete shared JWT OAuth client: {client_info.client_id[:16]}..."
+                )
+        except Exception as e:
+            logger.warning(
+                f"Error cleaning up shared JWT OAuth client {client_info.client_id[:16]}...: {e}"
+            )
+
 
 async def _create_oauth_client_with_scopes(
     callback_url: str,
     client_name: str,
     allowed_scopes: str,
     token_type: str = "JWT",
-    cache_file: str | None = None,
-) -> tuple[str, str]:
+):
     """
     Helper function to create an OAuth client with specific allowed_scopes using DCR.
 
-    Supports optional file-based caching to avoid creating duplicate clients.
-
     Args:
         callback_url: OAuth callback URL
         client_name: Name of the OAuth client
         allowed_scopes: Space-separated list of allowed scopes
         token_type: Either "JWT" or "Bearer" (default: "JWT")
-        cache_file: Optional path to cache file (e.g., ".nextcloud_oauth_shared_test_client.json")
 
     Returns:
-        Tuple of (client_id, client_secret)
+        ClientInfo object with full registration details including registration_access_token
     """
-    import json
-    from pathlib import Path
-
     from nextcloud_mcp_server.auth.client_registration import register_client
 
-    # Try to load from cache if specified
-    if cache_file:
-        cache_path = Path(cache_file)
-        if cache_path.exists():
-            try:
-                with open(cache_path, "r") as f:
-                    cached_data = json.load(f)
-
-                client_id = cached_data.get("client_id")
-                client_secret = cached_data.get("client_secret")
-
-                if client_id and client_secret:
-                    logger.info(
-                        f"Loaded cached OAuth client from {cache_file}: {client_id[:16]}..."
-                    )
-                    return client_id, client_secret
-            except (json.JSONDecodeError, KeyError, OSError) as e:
-                logger.warning(f"Failed to load cached client from {cache_file}: {e}")
-
     logger.info(
         f"Creating {token_type} OAuth client '{client_name}' with scopes: {allowed_scopes} using DCR"
     )
@@ -1101,50 +1170,31 @@ async def _create_oauth_client_with_scopes(
         token_type=token_type,
     )
 
-    client_id = client_info.client_id
-    client_secret = client_info.client_secret
-
     logger.info(
-        f"Created OAuth client via DCR: {client_id[:16]}... with scopes: {allowed_scopes}"
+        f"Created OAuth client via DCR: {client_info.client_id[:16]}... with scopes: {allowed_scopes}"
     )
+    if client_info.registration_access_token:
+        logger.info(
+            "RFC 7592 registration_access_token received - client can be deleted"
+        )
+    else:
+        logger.warning("No registration_access_token - client deletion may fail")
 
-    # Save to cache if specified
-    if cache_file:
-        cache_path = Path(cache_file)
-        try:
-            # Create parent directory if needed
-            cache_path.parent.mkdir(parents=True, exist_ok=True)
-
-            # Save client data
-            with open(cache_path, "w") as f:
-                json.dump(
-                    {
-                        "client_id": client_id,
-                        "client_secret": client_secret,
-                        "redirect_uris": [callback_url],
-                    },
-                    f,
-                    indent=2,
-                )
-
-            # Set restrictive permissions
-            cache_path.chmod(0o600)
-
-            logger.info(f"Cached OAuth client to {cache_file}")
-        except OSError as e:
-            logger.warning(f"Failed to cache client to {cache_file}: {e}")
-
-    return client_id, client_secret
+    return client_info
 
 
 @pytest.fixture(scope="session")
 async def read_only_oauth_client_credentials(anyio_backend, oauth_callback_server):
     """
-    Fixture for OAuth client with only nc:read scope.
+    Fixture for OAuth client with only read scopes.
+
+    The client is automatically deleted from Nextcloud after the test session completes.
 
     Returns:
         Tuple of (client_id, client_secret, callback_url, token_endpoint, authorization_endpoint)
     """
+    from nextcloud_mcp_server.auth.client_registration import delete_client
+
     nextcloud_host = os.getenv("NEXTCLOUD_HOST")
     if not nextcloud_host:
         pytest.skip("Read-only OAuth client requires NEXTCLOUD_HOST")
@@ -1161,30 +1211,59 @@ async def read_only_oauth_client_credentials(anyio_backend, oauth_callback_serve
         authorization_endpoint = oidc_config.get("authorization_endpoint")
 
         # Create JWT client with READ-ONLY scopes
-        client_id, client_secret = await _create_oauth_client_with_scopes(
+        client_info = await _create_oauth_client_with_scopes(
             callback_url=callback_url,
             client_name="Test Client Read Only",
-            allowed_scopes="openid profile email nc:read",
+            allowed_scopes=DEFAULT_READ_SCOPES,
             token_type="JWT",  # JWT tokens for scope validation
         )
 
-        return (
-            client_id,
-            client_secret,
+        yield (
+            client_info.client_id,
+            client_info.client_secret,
             callback_url,
             token_endpoint,
             authorization_endpoint,
         )
 
+        # Cleanup: Delete OAuth client from Nextcloud using RFC 7592
+        try:
+            logger.info(
+                f"Cleaning up read-only OAuth client: {client_info.client_id[:16]}..."
+            )
+            success = await delete_client(
+                nextcloud_url=nextcloud_host,
+                client_id=client_info.client_id,
+                registration_access_token=client_info.registration_access_token,
+                client_secret=client_info.client_secret,
+                registration_client_uri=client_info.registration_client_uri,
+            )
+            if success:
+                logger.info(
+                    f"Successfully deleted read-only OAuth client: {client_info.client_id[:16]}..."
+                )
+            else:
+                logger.warning(
+                    f"Failed to delete read-only OAuth client: {client_info.client_id[:16]}..."
+                )
+        except Exception as e:
+            logger.warning(
+                f"Error cleaning up read-only OAuth client {client_info.client_id[:16]}...: {e}"
+            )
+
 
 @pytest.fixture(scope="session")
 async def write_only_oauth_client_credentials(anyio_backend, oauth_callback_server):
     """
-    Fixture for OAuth client with only nc:write scope.
+    Fixture for OAuth client with only write scopes.
+
+    The client is automatically deleted from Nextcloud after the test session completes.
 
     Returns:
         Tuple of (client_id, client_secret, callback_url, token_endpoint, authorization_endpoint)
     """
+    from nextcloud_mcp_server.auth.client_registration import delete_client
+
     nextcloud_host = os.getenv("NEXTCLOUD_HOST")
     if not nextcloud_host:
         pytest.skip("Write-only OAuth client requires NEXTCLOUD_HOST")
@@ -1201,30 +1280,59 @@ async def write_only_oauth_client_credentials(anyio_backend, oauth_callback_serv
         authorization_endpoint = oidc_config.get("authorization_endpoint")
 
         # Create JWT client with WRITE-ONLY scopes
-        client_id, client_secret = await _create_oauth_client_with_scopes(
+        client_info = await _create_oauth_client_with_scopes(
             callback_url=callback_url,
             client_name="Test Client Write Only",
-            allowed_scopes="openid profile email nc:write",
+            allowed_scopes=DEFAULT_WRITE_SCOPES,
             token_type="JWT",  # JWT tokens for scope validation
         )
 
-        return (
-            client_id,
-            client_secret,
+        yield (
+            client_info.client_id,
+            client_info.client_secret,
             callback_url,
             token_endpoint,
             authorization_endpoint,
         )
 
+        # Cleanup: Delete OAuth client from Nextcloud using RFC 7592
+        try:
+            logger.info(
+                f"Cleaning up write-only OAuth client: {client_info.client_id[:16]}..."
+            )
+            success = await delete_client(
+                nextcloud_url=nextcloud_host,
+                client_id=client_info.client_id,
+                registration_access_token=client_info.registration_access_token,
+                client_secret=client_info.client_secret,
+                registration_client_uri=client_info.registration_client_uri,
+            )
+            if success:
+                logger.info(
+                    f"Successfully deleted write-only OAuth client: {client_info.client_id[:16]}..."
+                )
+            else:
+                logger.warning(
+                    f"Failed to delete write-only OAuth client: {client_info.client_id[:16]}..."
+                )
+        except Exception as e:
+            logger.warning(
+                f"Error cleaning up write-only OAuth client {client_info.client_id[:16]}...: {e}"
+            )
+
 
 @pytest.fixture(scope="session")
 async def full_access_oauth_client_credentials(anyio_backend, oauth_callback_server):
     """
-    Fixture for OAuth client with both nc:read and nc:write scopes.
+    Fixture for OAuth client with both read and write scopes.
+
+    The client is automatically deleted from Nextcloud after the test session completes.
 
     Returns:
         Tuple of (client_id, client_secret, callback_url, token_endpoint, authorization_endpoint)
     """
+    from nextcloud_mcp_server.auth.client_registration import delete_client
+
     nextcloud_host = os.getenv("NEXTCLOUD_HOST")
     if not nextcloud_host:
         pytest.skip("Full-access OAuth client requires NEXTCLOUD_HOST")
@@ -1241,21 +1349,46 @@ async def full_access_oauth_client_credentials(anyio_backend, oauth_callback_ser
         authorization_endpoint = oidc_config.get("authorization_endpoint")
 
         # Create JWT client with FULL ACCESS (both read and write scopes)
-        client_id, client_secret = await _create_oauth_client_with_scopes(
+        client_info = await _create_oauth_client_with_scopes(
             callback_url=callback_url,
             client_name="Test Client Full Access",
-            allowed_scopes="openid profile email nc:read nc:write",
+            allowed_scopes=DEFAULT_FULL_SCOPES,
             token_type="JWT",  # JWT tokens for scope validation
         )
 
-        return (
-            client_id,
-            client_secret,
+        yield (
+            client_info.client_id,
+            client_info.client_secret,
             callback_url,
             token_endpoint,
             authorization_endpoint,
         )
 
+        # Cleanup: Delete OAuth client from Nextcloud using RFC 7592
+        try:
+            logger.info(
+                f"Cleaning up full-access OAuth client: {client_info.client_id[:16]}..."
+            )
+            success = await delete_client(
+                nextcloud_url=nextcloud_host,
+                client_id=client_info.client_id,
+                registration_access_token=client_info.registration_access_token,
+                client_secret=client_info.client_secret,
+                registration_client_uri=client_info.registration_client_uri,
+            )
+            if success:
+                logger.info(
+                    f"Successfully deleted full-access OAuth client: {client_info.client_id[:16]}..."
+                )
+            else:
+                logger.warning(
+                    f"Failed to delete full-access OAuth client: {client_info.client_id[:16]}..."
+                )
+        except Exception as e:
+            logger.warning(
+                f"Error cleaning up full-access OAuth client {client_info.client_id[:16]}...: {e}"
+            )
+
 
 @pytest.fixture(scope="session")
 async def no_custom_scopes_oauth_client_credentials(
@@ -1265,11 +1398,15 @@ async def no_custom_scopes_oauth_client_credentials(
     Fixture for OAuth client with NO custom scopes (only OIDC defaults).
 
     Tests the security behavior when a user grants only the default OIDC scopes
-    (openid, profile, email) but declines custom application scopes (nc:read, nc:write).
+    (openid, profile, email) but declines custom application scopes (notes:read, notes:write, etc.).
+
+    The client is automatically deleted from Nextcloud after the test session completes.
 
     Returns:
         Tuple of (client_id, client_secret, callback_url, token_endpoint, authorization_endpoint)
     """
+    from nextcloud_mcp_server.auth.client_registration import delete_client
+
     nextcloud_host = os.getenv("NEXTCLOUD_HOST")
     if not nextcloud_host:
         pytest.skip("No-custom-scopes OAuth client requires NEXTCLOUD_HOST")
@@ -1286,21 +1423,46 @@ async def no_custom_scopes_oauth_client_credentials(
         authorization_endpoint = oidc_config.get("authorization_endpoint")
 
         # Create JWT client with NO custom scopes (only OIDC defaults)
-        client_id, client_secret = await _create_oauth_client_with_scopes(
+        client_info = await _create_oauth_client_with_scopes(
             callback_url=callback_url,
             client_name="Test Client No Custom Scopes",
-            allowed_scopes="openid profile email",  # No nc:read or nc:write
+            allowed_scopes="openid profile email",  # No app-specific scopes (no app access)
             token_type="JWT",  # JWT tokens for scope validation
         )
 
-        return (
-            client_id,
-            client_secret,
+        yield (
+            client_info.client_id,
+            client_info.client_secret,
             callback_url,
             token_endpoint,
             authorization_endpoint,
         )
 
+        # Cleanup: Delete OAuth client from Nextcloud using RFC 7592
+        try:
+            logger.info(
+                f"Cleaning up no-custom-scopes OAuth client: {client_info.client_id[:16]}..."
+            )
+            success = await delete_client(
+                nextcloud_url=nextcloud_host,
+                client_id=client_info.client_id,
+                registration_access_token=client_info.registration_access_token,
+                client_secret=client_info.client_secret,
+                registration_client_uri=client_info.registration_client_uri,
+            )
+            if success:
+                logger.info(
+                    f"Successfully deleted no-custom-scopes OAuth client: {client_info.client_id[:16]}..."
+                )
+            else:
+                logger.warning(
+                    f"Failed to delete no-custom-scopes OAuth client: {client_info.client_id[:16]}..."
+                )
+        except Exception as e:
+            logger.warning(
+                f"Error cleaning up no-custom-scopes OAuth client {client_info.client_id[:16]}...: {e}"
+            )
+
 
 @pytest.fixture(scope="session")
 async def playwright_oauth_token(
@@ -1363,7 +1525,7 @@ async def playwright_oauth_token(
         f"client_id={client_id}&"
         f"redirect_uri={quote(callback_url, safe='')}&"
         f"state={state}&"
-        f"scope=openid%20profile%20email%20nc:read%20nc:write"
+        f"scope=openid%20profile%20email%20notes:read%20notes:write%20calendar:read%20calendar:write%20contacts:read%20contacts:write%20cookbook:read%20cookbook:write%20deck:read%20deck:write%20tables:read%20tables:write%20files:read%20files:write%20sharing:read%20sharing:write"
     )
 
     # Async browser automation using pytest-playwright's browser fixture
@@ -1420,7 +1582,7 @@ async def playwright_oauth_token(
                 raise TimeoutError(
                     f"Timeout waiting for OAuth callback (state={state[:16]}...)"
                 )
-            await asyncio.sleep(0.5)
+            await anyio.sleep(0.5)
 
         auth_code = auth_states[state]
         logger.info(f"Successfully received authorization code: {auth_code[:20]}...")
@@ -1460,7 +1622,7 @@ async def playwright_oauth_token_jwt(
     """
     Fixture to obtain a JWT OAuth access token for the JWT MCP server.
 
-    Uses a JWT OAuth client with full scopes (nc:read and nc:write) to ensure
+    Uses a JWT OAuth client with full scopes (all app read/write scopes) to ensure
     the access token includes proper scope claims that the JWT MCP server can validate.
 
     Returns:
@@ -1470,7 +1632,7 @@ async def playwright_oauth_token_jwt(
         browser,
         shared_jwt_oauth_client_credentials,
         oauth_callback_server,
-        scopes="openid profile email nc:read nc:write",
+        scopes=DEFAULT_FULL_SCOPES,
     )
 
 
@@ -1591,7 +1753,7 @@ async def _get_oauth_token_with_scopes(
         browser: Playwright browser instance
         shared_oauth_client_credentials: Tuple of OAuth client credentials
         oauth_callback_server: OAuth callback server fixture
-        scopes: Space-separated list of scopes (e.g., "openid profile email nc:read")
+        scopes: Space-separated list of scopes (e.g., "openid profile email notes:read")
 
     Returns:
         OAuth access token string with requested scopes
@@ -1688,7 +1850,7 @@ async def _get_oauth_token_with_scopes(
                 auth_code = auth_states[state]
                 logger.info("Auth code received from callback server")
                 break
-            await asyncio.sleep(0.1)
+            await anyio.sleep(0.1)
         else:
             raise TimeoutError(
                 f"Auth code not received within {timeout}s. State: {state[:16]}..."
@@ -1727,18 +1889,18 @@ async def playwright_oauth_token_read_only(
     anyio_backend, browser, read_only_oauth_client_credentials, oauth_callback_server
 ) -> str:
     """
-    Fixture to obtain an OAuth access token with only nc:read scope.
+    Fixture to obtain an OAuth access token with only read scopes.
 
     This token will only be able to perform read operations and should
     have write tools filtered out from the tool list.
 
-    Uses a dedicated OAuth client with allowed_scopes="openid profile email nc:read"
+    Uses a dedicated OAuth client with allowed_scopes=DEFAULT_READ_SCOPES
     """
     return await _get_oauth_token_with_scopes(
         browser,
         read_only_oauth_client_credentials,
         oauth_callback_server,
-        scopes="openid profile email nc:read",
+        scopes=DEFAULT_READ_SCOPES,
     )
 
 
@@ -1747,18 +1909,18 @@ async def playwright_oauth_token_write_only(
     anyio_backend, browser, write_only_oauth_client_credentials, oauth_callback_server
 ) -> str:
     """
-    Fixture to obtain an OAuth access token with only nc:write scope.
+    Fixture to obtain an OAuth access token with only write scopes.
 
     This token will only be able to perform write operations and should
     have read tools filtered out from the tool list.
 
-    Uses a dedicated OAuth client with allowed_scopes="openid profile email nc:write"
+    Uses a dedicated OAuth client with allowed_scopes=DEFAULT_WRITE_SCOPES
     """
     return await _get_oauth_token_with_scopes(
         browser,
         write_only_oauth_client_credentials,
         oauth_callback_server,
-        scopes="openid profile email nc:write",
+        scopes=DEFAULT_WRITE_SCOPES,
     )
 
 
@@ -1767,17 +1929,17 @@ async def playwright_oauth_token_full_access(
     anyio_backend, browser, full_access_oauth_client_credentials, oauth_callback_server
 ) -> str:
     """
-    Fixture to obtain an OAuth access token with both nc:read and nc:write scopes.
+    Fixture to obtain an OAuth access token with both read and write scopes.
 
     This token will be able to perform all operations.
 
-    Uses a dedicated JWT OAuth client with allowed_scopes="openid profile email nc:read nc:write"
+    Uses a dedicated JWT OAuth client with allowed_scopes=DEFAULT_FULL_SCOPES
     """
     return await _get_oauth_token_with_scopes(
         browser,
         full_access_oauth_client_credentials,
         oauth_callback_server,
-        scopes="openid profile email nc:read nc:write",
+        scopes=DEFAULT_FULL_SCOPES,
     )
 
 
@@ -1795,7 +1957,7 @@ async def playwright_oauth_token_no_custom_scopes(
     (openid, profile, email) but declines application-specific scopes.
 
     Expected: JWT token will contain only default scopes, and all MCP tools
-    should be filtered out since they all require nc:read or nc:write.
+    should be filtered out since they all require app-specific scopes.
 
     Uses a dedicated JWT OAuth client with allowed_scopes="openid profile email"
     """
@@ -1967,7 +2129,7 @@ async def _get_oauth_token_for_user(
         f"client_id={client_id}&"
         f"redirect_uri={quote(callback_url, safe='')}&"
         f"state={state}&"
-        f"scope=openid%20profile%20email%20nc:read%20nc:write"
+        f"scope=openid%20profile%20email%20notes:read%20notes:write%20calendar:read%20calendar:write%20contacts:read%20contacts:write%20cookbook:read%20cookbook:write%20deck:read%20deck:write%20tables:read%20tables:write%20files:read%20files:write%20sharing:read%20sharing:write"
     )
 
     logger.info(f"Performing browser OAuth flow for {username}...")
@@ -2013,7 +2175,7 @@ async def _get_oauth_token_for_user(
                 raise TimeoutError(
                     f"Timeout waiting for OAuth callback for {username} (state={state[:16]}...)"
                 )
-            await asyncio.sleep(0.5)
+            await anyio.sleep(0.5)
 
         auth_code = auth_states[state]
         logger.info(f"Got auth code for {username}: {auth_code[:20]}...")
@@ -2064,7 +2226,6 @@ async def all_oauth_tokens(
     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
@@ -2077,7 +2238,7 @@ async def all_oauth_tokens(
     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)
+            await anyio.sleep(delay)
         return await _get_oauth_token_for_user(
             browser,
             shared_oauth_client_credentials,
@@ -2087,17 +2248,30 @@ async def all_oauth_tokens(
         )
 
     # Create tasks for all users with staggered starts (0.5s apart)
-    tasks = {
-        username: get_token_with_delay(username, config, idx * 0.5)
-        for idx, (username, config) in enumerate(test_users_setup.items())
-    }
-
-    # Run all token fetches concurrently
-    results = await asyncio.gather(*tasks.values(), return_exceptions=True)
-
-    # Build result dict, handling any errors
+    user_list = list(test_users_setup.items())
     tokens = {}
-    for username, result in zip(tasks.keys(), results):
+
+    # Run all token fetches concurrently using anyio task groups
+    async with anyio.create_task_group() as tg:
+        # Create a dict to store results as they complete
+        results = {}
+
+        def create_task_wrapper(username: str, config: dict, idx: int):
+            async def task():
+                try:
+                    token = await get_token_with_delay(username, config, idx * 0.5)
+                    results[username] = token
+                except Exception as e:
+                    results[username] = e
+
+            return task
+
+        for idx, (username, config) in enumerate(user_list):
+            tg.start_soon(create_task_wrapper(username, config, idx))
+
+    # Build token dict, handling any errors
+    for username in results:
+        result = results[username]
         if isinstance(result, Exception):
             logger.error(f"Failed to get OAuth token for {username}: {result}")
             raise result

tests/integration/client/test_document_processing_progress.py

@@ -0,0 +1,143 @@
+"""Integration tests for document processing with progress notifications."""
+
+import io
+
+import pytest
+from PIL import Image
+
+pytestmark = pytest.mark.integration
+
+
+class TestDocumentProcessingProgress:
+    """Test document processing with progress notifications."""
+
+    async def test_unstructured_processor_with_progress_callback(self, nc_client):
+        """Test that UnstructuredProcessor calls progress callback during processing."""
+        import os
+
+        # Skip if unstructured is not enabled
+        if os.getenv("ENABLE_UNSTRUCTURED", "false").lower() != "true":
+            pytest.skip("Unstructured processor not enabled")
+
+        from nextcloud_mcp_server.document_processors.unstructured import (
+            UnstructuredProcessor,
+        )
+
+        # Track progress callback invocations
+        progress_updates = []
+
+        async def track_progress(progress: float, total: float | None, message: str):
+            progress_updates.append(
+                {"progress": progress, "total": total, "message": message}
+            )
+
+        # Create processor configured to use local unstructured service
+        processor = UnstructuredProcessor(
+            api_url=os.getenv("UNSTRUCTURED_API_URL", "http://unstructured:8000"),
+            timeout=120,
+            progress_interval=2,  # 2 second intervals for testing
+        )
+
+        # Create a simple test image (which requires OCR processing)
+        # This should take long enough to trigger at least one progress update
+        img = Image.new("RGB", (400, 200), color=(73, 109, 137))
+        buffer = io.BytesIO()
+        img.save(buffer, format="PNG")
+        test_image = buffer.getvalue()
+
+        # Process with progress callback
+        result = await processor.process(
+            content=test_image,
+            content_type="image/png",
+            filename="test.png",
+            progress_callback=track_progress,
+        )
+
+        # Verify processing succeeded
+        assert result.success is True
+        assert result.processor == "unstructured"
+        assert isinstance(result.text, str)
+
+        # Note: Progress updates may or may not occur depending on processing speed
+        # If updates occurred, verify their structure
+        if progress_updates:
+            for update in progress_updates:
+                assert isinstance(update["progress"], float)
+                assert update["total"] is None  # Unknown total
+                assert "Processing document with unstructured" in update["message"]
+                assert "elapsed" in update["message"]
+
+    async def test_webdav_read_file_sends_progress_notifications(
+        self, nc_mcp_client, nc_client
+    ):
+        """Test that reading a document via WebDAV MCP tool sends progress notifications."""
+        import os
+
+        # Skip if document processing is not enabled
+        if os.getenv("ENABLE_DOCUMENT_PROCESSING", "false").lower() != "true":
+            pytest.skip("Document processing not enabled")
+
+        # Create a test image file in Nextcloud via WebDAV
+        from PIL import Image
+
+        img = Image.new("RGB", (400, 200), color=(100, 150, 200))
+        buffer = io.BytesIO()
+        img.save(buffer, format="PNG")
+        test_image = buffer.getvalue()
+
+        # Upload test file
+        test_path = "test_progress.png"
+        await nc_client.webdav.write_file(test_path, test_image, "image/png")
+
+        try:
+            # Read file via MCP tool (which should trigger document processing)
+            # The MCP client will automatically track progress notifications
+            result = await nc_mcp_client.call_tool(
+                "nc_webdav_read_file", arguments={"path": test_path}
+            )
+
+            # Note: FastMCP progress notifications are sent automatically by ctx.report_progress
+            # We can't easily capture them in this test without mocking the MCP transport layer
+            # The important thing is that the code path is exercised without errors
+            assert result.isError is False
+
+        finally:
+            # Cleanup
+            try:
+                await nc_client.webdav.delete_resource(test_path)
+            except Exception:
+                pass  # Ignore cleanup errors
+
+    async def test_progress_callback_not_required(self, nc_client):
+        """Test that processing works without progress callback (backward compatibility)."""
+        import os
+
+        if os.getenv("ENABLE_UNSTRUCTURED", "false").lower() != "true":
+            pytest.skip("Unstructured processor not enabled")
+
+        from nextcloud_mcp_server.document_processors.unstructured import (
+            UnstructuredProcessor,
+        )
+
+        processor = UnstructuredProcessor(
+            api_url=os.getenv("UNSTRUCTURED_API_URL", "http://unstructured:8000"),
+            timeout=120,
+        )
+
+        # Create simple test image
+        img = Image.new("RGB", (200, 100), color=(50, 100, 150))
+        buffer = io.BytesIO()
+        img.save(buffer, format="PNG")
+        test_image = buffer.getvalue()
+
+        # Process WITHOUT progress callback
+        result = await processor.process(
+            content=test_image,
+            content_type="image/png",
+            filename="test.png",
+            progress_callback=None,  # Explicitly None
+        )
+
+        # Should still work
+        assert result.success is True
+        assert result.processor == "unstructured"

tests/integration/test_unstructured_api.py

@@ -0,0 +1,155 @@
+"""Integration tests for Unstructured API functionality."""
+
+import json
+import logging
+import os
+import uuid
+from io import BytesIO
+
+import pytest
+from mcp.client.session import ClientSession
+from reportlab.lib.pagesizes import letter
+from reportlab.pdfgen import canvas
+
+from nextcloud_mcp_server.client import NextcloudClient
+
+logger = logging.getLogger(__name__)
+
+
+@pytest.fixture
+async def test_base_path(nc_client: NextcloudClient):
+    """Base path for test files/directories."""
+    test_dir = f"mcp_test_unstructured_{uuid.uuid4().hex[:8]}"
+    await nc_client.webdav.create_directory(test_dir)
+    yield test_dir
+    try:
+        await nc_client.webdav.delete_resource(test_dir)
+    except Exception:
+        pass  # Ignore cleanup errors
+
+
+def create_test_pdf(text: str) -> bytes:
+    """Create a simple PDF document with the given text."""
+    buffer = BytesIO()
+    c = canvas.Canvas(buffer, pagesize=letter)
+    c.drawString(100, 750, text)
+    c.save()
+    buffer.seek(0)
+    return buffer.getvalue()
+
+
+@pytest.mark.skipif(
+    condition=os.getenv("ENABLE_UNSTRUCTURED", "false") != "true",
+    reason="Unstructured is not enabled",
+)
+async def test_unstructured_api_enabled_parsing(
+    nc_client: NextcloudClient, test_base_path: str, nc_mcp_client: ClientSession
+):
+    """Test that documents are parsed using the Unstructured API when enabled."""
+    test_file = f"{test_base_path}/test_unstructured_pdf.pdf"
+    test_text = "This is a test PDF document for Unstructured API parsing"
+
+    try:
+        # Create a simple PDF
+        pdf_content = create_test_pdf(test_text)
+
+        # Upload the PDF
+        await nc_client.webdav.write_file(
+            test_file, pdf_content, content_type="application/pdf"
+        )
+        logger.info(f"Uploaded PDF file: {test_file}")
+
+        # Read the PDF using MCP tool (should parse via Unstructured API)
+        mcp_result = await nc_mcp_client.call_tool(
+            "nc_webdav_read_file", arguments={"path": test_file}
+        )
+
+        # Extract content from the MCP result
+        if hasattr(mcp_result.content[0], "text"):
+            result_text = mcp_result.content[0].text
+        else:
+            # Fallback for other content types
+            result_text = str(mcp_result.content[0])
+
+        # Parse the JSON response
+        result = json.loads(result_text)
+
+        # Verify the result structure
+        assert "path" in result
+        assert "content" in result
+        assert "content_type" in result
+        assert "parsed" in result  # Should be present when parsing succeeds
+
+        # The content should be readable text, not base64
+        content = result["content"]
+        assert isinstance(content, str)
+        assert len(content) > 0
+        assert "test" in content.lower()  # Should contain our test text
+
+        # Should have parsing metadata
+        assert "parsing_metadata" in result
+        parsing_metadata = result["parsing_metadata"]
+        assert parsing_metadata["parsing_method"] == "unstructured_api"
+
+        logger.info("Successfully parsed PDF using Unstructured API")
+
+    finally:
+        # Clean up
+        try:
+            await nc_client.webdav.delete_resource(test_file)
+        except Exception:
+            pass  # Ignore cleanup errors
+
+
+@pytest.mark.skipif(
+    condition=os.getenv("ENABLE_UNSTRUCTURED", "false") != "true",
+    reason="Unstructured is not enabled",
+)
+async def test_unstructured_api_with_docx(
+    nc_client: NextcloudClient, test_base_path: str, nc_mcp_client: ClientSession
+):
+    """Test Unstructured API with DOCX files."""
+    test_file = f"{test_base_path}/test_unstructured_docx.docx"
+    try:
+        # Create a simple DOCX-like file for testing purposes
+        # Since we're removing python-docx dependency, we'll create a simple file
+        docx_content = (
+            b"This is a mock DOCX file content for testing Unstructured API parsing"
+        )
+
+        # Upload the file
+        await nc_client.webdav.write_file(
+            test_file,
+            docx_content,
+            content_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        )
+        logger.info(f"Uploaded DOCX file: {test_file}")
+
+        # Read the file using MCP tool
+        mcp_result = await nc_mcp_client.call_tool(
+            "nc_webdav_read_file", arguments={"path": test_file}
+        )
+
+        # Extract content from the MCP result
+        if hasattr(mcp_result.content[0], "text"):
+            result_text = mcp_result.content[0].text
+        else:
+            # Fallback for other content types
+            result_text = str(mcp_result.content[0])
+
+        # Parse the JSON response
+        result = json.loads(result_text)
+
+        # Verify the result structure
+        assert "path" in result
+        assert "content" in result
+        assert "content_type" in result
+
+        logger.info("Successfully processed DOCX file with Unstructured API")
+
+    finally:
+        # Clean up
+        try:
+            await nc_client.webdav.delete_resource(test_file)
+        except Exception:
+            pass  # Ignore cleanup errors

tests/load/oauth_pool.py

@@ -4,11 +4,11 @@ OAuth User Pool Management for Load Testing.
 Manages multiple OAuth-authenticated users for realistic multi-user load testing scenarios.
 """
 
-import asyncio
 import logging
 from dataclasses import dataclass
 from typing import Any
 
+import anyio
 import httpx
 from mcp import ClientSession
 from mcp.client.streamable_http import streamablehttp_client
@@ -394,7 +394,7 @@ class OAuthUserPool:
                     raise TimeoutError(
                         f"Timeout waiting for OAuth callback for {username}"
                     )
-                await asyncio.sleep(0.5)
+                await anyio.sleep(0.5)
 
             auth_code = auth_states[state]
             logger.info(f"Received auth code for {username}")

tests/load/oauth_workloads.py

@@ -5,7 +5,6 @@ Defines coordinated workflows that span multiple users, simulating realistic
 collaborative scenarios like note sharing, file collaboration, and permission management.
 """
 
-import asyncio
 import json
 import logging
 import random
@@ -15,6 +14,8 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import Any, Awaitable, Callable
 
+import anyio
+
 from tests.load.oauth_pool import UserSessionWrapper
 
 logger = logging.getLogger(__name__)
@@ -299,7 +300,9 @@ class CollaborativeEditWorkflow(Workflow):
                     )
                 )
 
-            await asyncio.gather(*read_tasks)
+            async with anyio.create_task_group() as tg:
+                for task in read_tasks:
+                    tg.start_soon(task)
 
             # Step 3: Append content concurrently by all collaborators
             append_tasks = []
@@ -318,7 +321,9 @@ class CollaborativeEditWorkflow(Workflow):
                     )
                 )
 
-            await asyncio.gather(*append_tasks)
+            async with anyio.create_task_group() as tg:
+                for task in append_tasks:
+                    tg.start_soon(task)
 
             # Step 4: Owner verifies final state
             await self._execute_step(

tests/server/oauth/__init__.py

@@ -0,0 +1 @@
+"""OAuth-specific integration tests."""

tests/server/oauth/test_dcr_deletion_methods.py

@@ -0,0 +1,190 @@
+"""
+Test DCR deletion endpoint with different authentication methods.
+
+This simplified test focuses only on testing the deletion endpoint
+with various authentication methods to answer the question:
+"Does the 401 issue occur for both basic auth and credentials in the body?"
+"""
+
+import logging
+import os
+
+import httpx
+import pytest
+
+from nextcloud_mcp_server.auth.client_registration import register_client
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+@pytest.mark.integration
+async def test_dcr_deletion_authentication_methods(
+    anyio_backend,
+    oauth_callback_server,
+):
+    """
+    Test DCR deletion with different authentication methods.
+
+    Tests:
+    1. HTTP Basic Auth (client_id:client_secret)
+    2. Credentials in JSON body
+    3. Credentials in query parameters
+
+    This answers: Does the 401 issue occur with all authentication methods?
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    auth_states, callback_url = oauth_callback_server
+
+    # Discover OIDC endpoints
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+        discovery_response = await client.get(discovery_url)
+        discovery_response.raise_for_status()
+        oidc_config = discovery_response.json()
+
+        registration_endpoint = oidc_config.get("registration_endpoint")
+
+    # Register a client for testing
+    logger.info("Registering test client...")
+    client_info = await register_client(
+        nextcloud_url=nextcloud_host,
+        registration_endpoint=registration_endpoint,
+        client_name="DCR Auth Methods Test",
+        redirect_uris=[callback_url],
+        scopes="openid profile email",
+        token_type="Bearer",
+    )
+
+    deletion_endpoint = f"{nextcloud_host}/apps/oidc/register/{client_info.client_id}"
+    logger.info(f"\nTesting deletion endpoint: {deletion_endpoint}")
+    logger.info(f"Client ID: {client_info.client_id}")
+    logger.info(f"Client Secret (first 16 chars): {client_info.client_secret[:16]}...")
+
+    results = {}
+
+    async with httpx.AsyncClient(timeout=30.0) as test_client:
+        # Method 1: HTTP Basic Auth
+        logger.info("\n=== Method 1: HTTP Basic Auth ===")
+        try:
+            response = await test_client.delete(
+                deletion_endpoint,
+                auth=(client_info.client_id, client_info.client_secret),
+            )
+            results["basic_auth"] = {
+                "status": response.status_code,
+                "body": response.text[:200],
+            }
+            logger.info(f"Status: {response.status_code}")
+            logger.info(f"Body: {response.text[:200]}")
+        except Exception as e:
+            results["basic_auth"] = {"status": "error", "error": str(e)}
+            logger.error(f"Error: {e}")
+
+        # Method 2: Credentials in JSON body
+        logger.info("\n=== Method 2: Credentials in JSON Body ===")
+        try:
+            response = await test_client.delete(
+                deletion_endpoint,
+                json={
+                    "client_id": client_info.client_id,
+                    "client_secret": client_info.client_secret,
+                },
+            )
+            results["json_body"] = {
+                "status": response.status_code,
+                "body": response.text[:200],
+            }
+            logger.info(f"Status: {response.status_code}")
+            logger.info(f"Body: {response.text[:200]}")
+        except Exception as e:
+            results["json_body"] = {"status": "error", "error": str(e)}
+            logger.error(f"Error: {e}")
+
+        # Method 3: Credentials in query parameters
+        logger.info("\n=== Method 3: Credentials in Query Parameters ===")
+        try:
+            response = await test_client.delete(
+                deletion_endpoint,
+                params={
+                    "client_id": client_info.client_id,
+                    "client_secret": client_info.client_secret,
+                },
+            )
+            results["query_params"] = {
+                "status": response.status_code,
+                "body": response.text[:200],
+            }
+            logger.info(f"Status: {response.status_code}")
+            logger.info(f"Body: {response.text[:200]}")
+        except Exception as e:
+            results["query_params"] = {"status": "error", "error": str(e)}
+            logger.error(f"Error: {e}")
+
+        # Method 4: No authentication (baseline)
+        logger.info("\n=== Method 4: No Authentication (Baseline) ===")
+        try:
+            response = await test_client.delete(deletion_endpoint)
+            results["no_auth"] = {
+                "status": response.status_code,
+                "body": response.text[:200],
+            }
+            logger.info(f"Status: {response.status_code}")
+            logger.info(f"Body: {response.text[:200]}")
+        except Exception as e:
+            results["no_auth"] = {"status": "error", "error": str(e)}
+            logger.error(f"Error: {e}")
+
+    # Print summary
+    logger.info("\n" + "=" * 70)
+    logger.info("SUMMARY: DCR Deletion Authentication Methods")
+    logger.info("=" * 70)
+
+    for method, result in results.items():
+        status = result.get("status", "unknown")
+        logger.info(f"{method:20s} → Status: {status}")
+
+    # Analysis
+    logger.info("\n" + "=" * 70)
+    logger.info("ANALYSIS")
+    logger.info("=" * 70)
+
+    all_401 = all(
+        r.get("status") == 401 for r in results.values() if r.get("status") != "error"
+    )
+    any_204 = any(r.get("status") == 204 for r in results.values())
+
+    if all_401:
+        logger.info("✗ ALL authentication methods return 401 Unauthorized")
+        logger.info(
+            "  This indicates the deletion endpoint does not accept any form of credentials."
+        )
+        logger.info(
+            "  Likely cause: RFC 7592 not fully implemented (missing registration_access_token)"
+        )
+    elif any_204:
+        logger.info("✓ At least one authentication method succeeded (204 No Content)")
+        for method, result in results.items():
+            if result.get("status") == 204:
+                logger.info(f"  Working method: {method}")
+    else:
+        logger.info("? Mixed results - further investigation needed")
+        for method, result in results.items():
+            logger.info(f"  {method}: {result.get('status')}")
+
+    # Document the finding
+    assert all_401 or any_204, (
+        f"Expected either all 401s (not implemented) or at least one 204 (working). "
+        f"Got: {results}"
+    )
+
+    if all_401:
+        logger.info(
+            "\n✓ Test confirms: DCR deletion returns 401 with ALL authentication methods"
+        )
+    else:
+        logger.info("\n✓ Test confirms: DCR deletion works with at least one method")

tests/server/oauth/test_dcr_lifecycle.py

@@ -0,0 +1,471 @@
+"""
+Tests for Dynamic Client Registration (DCR) lifecycle - register and delete.
+
+These tests verify the complete lifecycle of DCR clients:
+1. Registration via RFC 7591
+2. Token acquisition and use
+3. Deletion via RFC 7592
+4. Error handling for deletion edge cases
+
+This is critical for ensuring the fixture cleanup code works reliably.
+"""
+
+import logging
+import os
+import secrets
+import time
+from urllib.parse import quote
+
+import anyio
+import httpx
+import pytest
+
+from nextcloud_mcp_server.auth.client_registration import delete_client, register_client
+
+from ...conftest import _handle_oauth_consent_screen
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+async def get_oauth_token_with_client(
+    browser,
+    client_id: str,
+    client_secret: str,
+    token_endpoint: str,
+    authorization_endpoint: str,
+    callback_url: str,
+    auth_states: dict,
+    scopes: str = "openid profile email notes:read notes:write",
+) -> str:
+    """
+    Helper to obtain OAuth access token using existing client credentials.
+
+    Args:
+        browser: Playwright browser instance
+        client_id: OAuth client ID
+        client_secret: OAuth client secret
+        token_endpoint: Token endpoint URL
+        authorization_endpoint: Authorization endpoint URL
+        callback_url: Callback URL for OAuth redirect
+        auth_states: Dict for storing auth codes (from callback server)
+        scopes: Space-separated list of scopes to request
+
+    Returns:
+        Access token string
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    username = os.getenv("NEXTCLOUD_USERNAME")
+    password = os.getenv("NEXTCLOUD_PASSWORD")
+
+    if not all([nextcloud_host, username, password]):
+        pytest.skip(
+            "OAuth requires NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, and NEXTCLOUD_PASSWORD"
+        )
+
+    # Generate unique state parameter
+    state = secrets.token_urlsafe(32)
+
+    # URL-encode scopes
+    scopes_encoded = quote(scopes, safe="")
+
+    # Construct authorization URL
+    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={scopes_encoded}"
+    )
+
+    # Browser automation
+    context = await browser.new_context(ignore_https_errors=True)
+    page = await context.new_page()
+
+    try:
+        await page.goto(auth_url, wait_until="networkidle", timeout=60000)
+        current_url = page.url
+
+        # Login if needed
+        if "/login" in current_url or "/index.php/login" in current_url:
+            logger.info("Logging in for DCR lifecycle test...")
+            await page.wait_for_selector('input[name="user"]', timeout=10000)
+            await page.fill('input[name="user"]', username)
+            await page.fill('input[name="password"]', password)
+            await page.click('button[type="submit"]')
+            await page.wait_for_load_state("networkidle", timeout=60000)
+
+        # Handle consent screen if present
+        try:
+            await _handle_oauth_consent_screen(page, username)
+        except Exception as e:
+            logger.debug(f"No consent screen or already authorized: {e}")
+
+        # Wait for callback
+        logger.info("Waiting for OAuth callback...")
+        timeout_seconds = 30
+        start_time = time.time()
+        while state not in auth_states:
+            if time.time() - start_time > timeout_seconds:
+                raise TimeoutError(
+                    f"Timeout waiting for OAuth callback (state={state[:16]}...)"
+                )
+            await anyio.sleep(0.5)
+
+        auth_code = auth_states[state]
+        logger.info(f"Got auth code: {auth_code[:20]}...")
+
+    finally:
+        await context.close()
+
+    # Exchange code for token
+    logger.info("Exchanging authorization code for access token...")
+    async with httpx.AsyncClient(timeout=30.0) as http_client:
+        token_response = await http_client.post(
+            token_endpoint,
+            data={
+                "grant_type": "authorization_code",
+                "code": auth_code,
+                "redirect_uri": callback_url,
+                "client_id": client_id,
+                "client_secret": client_secret,
+            },
+        )
+
+        token_response.raise_for_status()
+        token_data = token_response.json()
+        access_token = token_data.get("access_token")
+
+        if not access_token:
+            raise ValueError(f"No access_token in response: {token_data}")
+
+        logger.info("Successfully obtained access token")
+        return access_token
+
+
+@pytest.mark.integration
+async def test_dcr_register_and_delete_lifecycle(
+    anyio_backend,
+    browser,
+    oauth_callback_server,
+):
+    """
+    Test the complete DCR lifecycle: register → use → delete.
+
+    This verifies:
+    1. Client registration succeeds
+    2. Client can obtain tokens and make API calls
+    3. Client deletion succeeds (returns 204)
+    4. Deleted client cannot be used again (tokens are revoked)
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    auth_states, callback_url = oauth_callback_server
+
+    # Discover OIDC endpoints
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+        discovery_response = await client.get(discovery_url)
+        discovery_response.raise_for_status()
+        oidc_config = discovery_response.json()
+
+        registration_endpoint = oidc_config.get("registration_endpoint")
+        token_endpoint = oidc_config.get("token_endpoint")
+        authorization_endpoint = oidc_config.get("authorization_endpoint")
+
+    # Step 1: Register client (and capture full response including registration_access_token)
+    logger.info("Step 1: Registering OAuth client...")
+
+    # Register manually to capture full response
+    client_metadata = {
+        "client_name": "DCR Lifecycle Test Client",
+        "redirect_uris": [callback_url],
+        "token_endpoint_auth_method": "client_secret_post",
+        "grant_types": ["authorization_code", "refresh_token"],
+        "response_types": ["code"],
+        "scope": "openid profile email notes:read",
+        "token_type": "Bearer",
+    }
+
+    async with httpx.AsyncClient(timeout=30.0) as reg_client:
+        reg_response = await reg_client.post(
+            registration_endpoint,
+            json=client_metadata,
+            headers={"Content-Type": "application/json"},
+        )
+        reg_response.raise_for_status()
+        full_client_info = reg_response.json()
+
+    logger.info(f"Full registration response keys: {list(full_client_info.keys())}")
+    logger.info(f"Registration response: {full_client_info}")
+
+    # Use the register_client function for the ClientInfo object
+    client_info = await register_client(
+        nextcloud_url=nextcloud_host,
+        registration_endpoint=registration_endpoint,
+        client_name="DCR Lifecycle Test Client 2",
+        redirect_uris=[callback_url],
+        scopes="openid profile email notes:read",
+        token_type="Bearer",
+    )
+
+    # Store RFC 7592 fields if present
+    registration_access_token = full_client_info.get("registration_access_token")
+    registration_client_uri = full_client_info.get("registration_client_uri")
+    logger.info(
+        f"Registration access token present: {registration_access_token is not None}"
+    )
+    logger.info(
+        f"Registration client URI present: {registration_client_uri is not None}"
+    )
+
+    logger.info(f"✅ Client registered: {client_info.client_id[:16]}...")
+
+    # Step 2: Obtain token and verify client works
+    logger.info("Step 2: Obtaining OAuth token with registered client...")
+    access_token = await get_oauth_token_with_client(
+        browser=browser,
+        client_id=client_info.client_id,
+        client_secret=client_info.client_secret,
+        token_endpoint=token_endpoint,
+        authorization_endpoint=authorization_endpoint,
+        callback_url=callback_url,
+        auth_states=auth_states,
+        scopes="openid profile email notes:read",
+    )
+
+    assert access_token, "Failed to obtain access token"
+    logger.info(f"✅ Access token obtained: {access_token[:30]}...")
+
+    # Step 3: Delete the client using RFC 7592
+    logger.info("Step 3: Deleting OAuth client...")
+    logger.info(f"Client ID: {client_info.client_id}")
+    logger.info(f"Client secret (first 16 chars): {client_info.client_secret[:16]}...")
+    logger.info(
+        f"Registration access token: {registration_access_token[:16] if registration_access_token else 'None'}..."
+    )
+
+    # Use delete_client() which prefers RFC 7592 Bearer token, falls back to Basic Auth
+    success = await delete_client(
+        nextcloud_url=nextcloud_host,
+        client_id=client_info.client_id,
+        registration_access_token=registration_access_token,
+        client_secret=client_info.client_secret,
+        registration_client_uri=registration_client_uri,
+    )
+
+    assert success, (
+        "Client deletion should succeed with RFC 7592 Bearer token or Basic Auth"
+    )
+    logger.info(f"✅ Client deleted successfully: {client_info.client_id[:16]}...")
+
+    # Step 4: Verify deleted client cannot obtain new tokens
+    logger.info("Step 4: Verifying deleted client cannot obtain new tokens...")
+
+    # Try to use the deleted client to get a token
+    # This should fail because the client no longer exists
+    async with httpx.AsyncClient(timeout=30.0) as http_client:
+        try:
+            # Try to use client credentials grant (should fail)
+            token_response = await http_client.post(
+                token_endpoint,
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": client_info.client_id,
+                    "client_secret": client_info.client_secret,
+                },
+            )
+
+            # If we get here, check the status code
+            # Accept either 400 (Bad Request) or 401 (Unauthorized) as valid rejection
+            if token_response.status_code in [400, 401]:
+                logger.info(
+                    f"✅ Deleted client correctly rejected ({token_response.status_code})"
+                )
+            else:
+                # Unexpected success - client should be deleted
+                pytest.fail(
+                    f"Deleted client should not be able to obtain tokens, "
+                    f"but got status {token_response.status_code}"
+                )
+
+        except httpx.HTTPStatusError as e:
+            # Expected - client should be rejected
+            if e.response.status_code == 401:
+                logger.info("✅ Deleted client correctly rejected (401 Unauthorized)")
+            else:
+                # Re-raise if it's a different error
+                raise
+
+    logger.info("✅ Complete DCR lifecycle test passed!")
+
+
+@pytest.mark.integration
+async def test_dcr_delete_with_wrong_credentials(
+    anyio_backend,
+    oauth_callback_server,
+):
+    """
+    Test that deletion fails with wrong registration_access_token (401 Unauthorized).
+
+    This verifies:
+    1. Client registration succeeds and returns registration_access_token
+    2. Deletion with wrong registration_access_token returns 401
+    3. Deletion with correct registration_access_token succeeds (RFC 7592)
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    auth_states, callback_url = oauth_callback_server
+
+    # Discover OIDC endpoints
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+        discovery_response = await client.get(discovery_url)
+        discovery_response.raise_for_status()
+        oidc_config = discovery_response.json()
+
+        registration_endpoint = oidc_config.get("registration_endpoint")
+
+    # Register client
+    logger.info("Registering OAuth client for credential test...")
+    client_info = await register_client(
+        nextcloud_url=nextcloud_host,
+        registration_endpoint=registration_endpoint,
+        client_name="DCR Wrong Credentials Test",
+        redirect_uris=[callback_url],
+        scopes="openid profile email",
+        token_type="Bearer",
+    )
+
+    logger.info(f"Client registered: {client_info.client_id[:16]}...")
+
+    # Try to delete with wrong registration_access_token (RFC 7592 Bearer token)
+    logger.info("Attempting deletion with wrong registration_access_token...")
+    wrong_token = "wrong_token_" + secrets.token_urlsafe(32)
+
+    success = await delete_client(
+        nextcloud_url=nextcloud_host,
+        client_id=client_info.client_id,
+        registration_access_token=wrong_token,
+        client_secret=client_info.client_secret,  # Should not be used if token is present
+    )
+
+    assert not success, "Deletion with wrong credentials should fail"
+    logger.info("✅ Deletion correctly failed with wrong credentials")
+
+    # Clean up: Delete with correct RFC 7592 Bearer token
+    logger.info("Cleaning up: deleting with correct registration_access_token...")
+    success = await delete_client(
+        nextcloud_url=nextcloud_host,
+        client_id=client_info.client_id,
+        registration_access_token=client_info.registration_access_token,
+        client_secret=client_info.client_secret,
+        registration_client_uri=client_info.registration_client_uri,
+    )
+
+    assert success, "Deletion with correct credentials should succeed"
+    logger.info("✅ Cleanup successful with correct credentials")
+
+
+@pytest.mark.integration
+async def test_dcr_delete_nonexistent_client(
+    anyio_backend,
+):
+    """
+    Test that deleting a non-existent client fails gracefully.
+
+    This verifies:
+    1. Deletion of fake client_id returns False (not 204)
+    2. No exceptions are raised (graceful failure)
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    # Try to delete a client that doesn't exist
+    fake_client_id = "nonexistent_" + secrets.token_urlsafe(16)
+    fake_client_secret = secrets.token_urlsafe(32)
+
+    logger.info(f"Attempting to delete non-existent client: {fake_client_id[:16]}...")
+
+    success = await delete_client(
+        nextcloud_url=nextcloud_host,
+        client_id=fake_client_id,
+        client_secret=fake_client_secret,
+    )
+
+    assert not success, "Deletion of non-existent client should fail"
+    logger.info("✅ Non-existent client deletion correctly failed")
+
+
+@pytest.mark.integration
+async def test_dcr_deletion_is_idempotent(
+    anyio_backend,
+    oauth_callback_server,
+):
+    """
+    Test that deleting the same client twice fails gracefully on second attempt.
+
+    This verifies:
+    1. First deletion succeeds (204)
+    2. Second deletion fails gracefully (returns False, not an exception)
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    auth_states, callback_url = oauth_callback_server
+
+    # Discover OIDC endpoints
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+        discovery_response = await client.get(discovery_url)
+        discovery_response.raise_for_status()
+        oidc_config = discovery_response.json()
+
+        registration_endpoint = oidc_config.get("registration_endpoint")
+
+    # Register client
+    logger.info("Registering OAuth client for idempotency test...")
+    client_info = await register_client(
+        nextcloud_url=nextcloud_host,
+        registration_endpoint=registration_endpoint,
+        client_name="DCR Idempotency Test",
+        redirect_uris=[callback_url],
+        scopes="openid profile email",
+        token_type="Bearer",
+    )
+
+    logger.info(f"Client registered: {client_info.client_id[:16]}...")
+
+    # First deletion with RFC 7592 Bearer token
+    logger.info("First deletion attempt...")
+    success = await delete_client(
+        nextcloud_url=nextcloud_host,
+        client_id=client_info.client_id,
+        registration_access_token=client_info.registration_access_token,
+        client_secret=client_info.client_secret,
+        registration_client_uri=client_info.registration_client_uri,
+    )
+
+    assert success, "First deletion should succeed"
+    logger.info("✅ First deletion succeeded")
+
+    # Second deletion (should fail gracefully - token no longer valid after first deletion)
+    logger.info("Second deletion attempt (should fail)...")
+    success = await delete_client(
+        nextcloud_url=nextcloud_host,
+        client_id=client_info.client_id,
+        registration_access_token=client_info.registration_access_token,
+        client_secret=client_info.client_secret,
+        registration_client_uri=client_info.registration_client_uri,
+    )
+
+    assert not success, "Second deletion should fail (client already deleted)"
+    logger.info("✅ Second deletion correctly failed (client already deleted)")

tests/server/oauth/test_dcr_new_implementation.py

@@ -0,0 +1,232 @@
+"""
+Test the new DCR deletion implementation.
+
+This test verifies that the recently implemented DCR deletion branch works correctly.
+"""
+
+import logging
+import os
+
+import httpx
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+@pytest.mark.integration
+async def test_new_dcr_registration_includes_access_token(
+    anyio_backend,
+    oauth_callback_server,
+):
+    """
+    Test that registration now includes registration_access_token.
+
+    The new DCR deletion implementation should provide a registration_access_token
+    in the registration response per RFC 7592.
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    auth_states, callback_url = oauth_callback_server
+
+    # Discover OIDC endpoints
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+        discovery_response = await client.get(discovery_url)
+        discovery_response.raise_for_status()
+        oidc_config = discovery_response.json()
+
+        registration_endpoint = oidc_config.get("registration_endpoint")
+
+    # Register a client and inspect the full response
+    client_metadata = {
+        "client_name": "DCR New Implementation Test",
+        "redirect_uris": [callback_url],
+        "token_endpoint_auth_method": "client_secret_post",
+        "grant_types": ["authorization_code", "refresh_token"],
+        "response_types": ["code"],
+        "scope": "openid profile email",
+        "token_type": "Bearer",
+    }
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        logger.info("Registering client to check for registration_access_token...")
+        response = await client.post(
+            registration_endpoint,
+            json=client_metadata,
+            headers={"Content-Type": "application/json"},
+        )
+        response.raise_for_status()
+        registration_data = response.json()
+
+    # Log the full response
+    logger.info(f"\n{'=' * 70}")
+    logger.info("REGISTRATION RESPONSE")
+    logger.info(f"{'=' * 70}")
+    logger.info(f"Response keys: {sorted(registration_data.keys())}")
+    logger.info("\nFull response:")
+    for key, value in sorted(registration_data.items()):
+        if key in ["client_secret", "registration_access_token"]:
+            # Truncate secrets for security
+            logger.info(f"  {key}: {value[:20]}... (truncated)")
+        else:
+            logger.info(f"  {key}: {value}")
+
+    # Check for RFC 7592 required fields
+    logger.info(f"\n{'=' * 70}")
+    logger.info("RFC 7592 COMPLIANCE CHECK")
+    logger.info(f"{'=' * 70}")
+
+    has_token = "registration_access_token" in registration_data
+    has_uri = "registration_client_uri" in registration_data
+
+    logger.info(f"registration_access_token present: {has_token}")
+    logger.info(f"registration_client_uri present: {has_uri}")
+
+    if has_token and has_uri:
+        logger.info(
+            "\n✓ PASS: Registration response includes RFC 7592 management fields!"
+        )
+        logger.info(
+            "  This means DCR deletion should now work with Bearer token authentication."
+        )
+
+        # Store these for deletion test
+        client_id = registration_data["client_id"]
+        registration_access_token = registration_data["registration_access_token"]
+        registration_client_uri = registration_data.get("registration_client_uri")
+
+        # Now test deletion with the registration_access_token
+        logger.info(f"\n{'=' * 70}")
+        logger.info("TESTING DCR DELETION WITH REGISTRATION_ACCESS_TOKEN")
+        logger.info(f"{'=' * 70}")
+
+        deletion_endpoint = (
+            registration_client_uri
+            or f"{nextcloud_host}/apps/oidc/register/{client_id}"
+        )
+        logger.info(f"Deletion endpoint: {deletion_endpoint}")
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            # Try deletion with Bearer token (RFC 7592 standard)
+            logger.info("\nAttempting deletion with Bearer token...")
+            delete_response = await client.delete(
+                deletion_endpoint,
+                headers={"Authorization": f"Bearer {registration_access_token}"},
+            )
+
+            logger.info(f"Response status: {delete_response.status_code}")
+            logger.info(f"Response body: {delete_response.text[:200]}")
+
+            if delete_response.status_code == 204:
+                logger.info(
+                    "\n✓✓✓ SUCCESS! DCR deletion works with new implementation!"
+                )
+                logger.info("    RFC 7592 deletion is now fully functional.")
+                assert True
+            elif delete_response.status_code == 401:
+                logger.error(
+                    "\n✗ FAIL: Still getting 401 even with registration_access_token"
+                )
+                logger.error(
+                    "  The token may not be recognized or there's a middleware issue."
+                )
+                pytest.fail(
+                    "DCR deletion failed with 401 even with registration_access_token"
+                )
+            else:
+                logger.warning(
+                    f"\n? UNEXPECTED: Got status {delete_response.status_code}"
+                )
+                pytest.fail(
+                    f"Unexpected status code: {delete_response.status_code}, body: {delete_response.text[:500]}"
+                )
+
+    else:
+        logger.warning(
+            "\n✗ FAIL: Registration response still missing RFC 7592 management fields"
+        )
+        logger.warning(
+            "  The new DCR deletion implementation may not be active or needs configuration."
+        )
+        pytest.fail(
+            f"Registration response missing RFC 7592 fields. "
+            f"Has token: {has_token}, Has URI: {has_uri}"
+        )
+
+
+@pytest.mark.integration
+async def test_dcr_deletion_with_basic_auth_new_impl(
+    anyio_backend,
+    oauth_callback_server,
+):
+    """
+    Verify whether HTTP Basic Auth is now supported for deletion.
+
+    Some implementations support both Bearer token and Basic Auth.
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    auth_states, callback_url = oauth_callback_server
+
+    # Discover and register
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+        discovery_response = await client.get(discovery_url)
+        discovery_response.raise_for_status()
+        oidc_config = discovery_response.json()
+        registration_endpoint = oidc_config.get("registration_endpoint")
+
+        # Register
+        client_metadata = {
+            "client_name": "DCR Basic Auth Test",
+            "redirect_uris": [callback_url],
+            "token_endpoint_auth_method": "client_secret_post",
+            "grant_types": ["authorization_code"],
+            "response_types": ["code"],
+            "scope": "openid profile email",
+            "token_type": "Bearer",
+        }
+
+        response = await client.post(
+            registration_endpoint,
+            json=client_metadata,
+        )
+        response.raise_for_status()
+        reg_data = response.json()
+
+    client_id = reg_data["client_id"]
+    client_secret = reg_data["client_secret"]
+    deletion_endpoint = f"{nextcloud_host}/apps/oidc/register/{client_id}"
+
+    logger.info(f"\n{'=' * 70}")
+    logger.info("TESTING DCR DELETION WITH HTTP BASIC AUTH")
+    logger.info(f"{'=' * 70}")
+    logger.info(f"Endpoint: {deletion_endpoint}")
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        response = await client.delete(
+            deletion_endpoint,
+            auth=(client_id, client_secret),
+        )
+
+        logger.info(f"Status: {response.status_code}")
+        logger.info(f"Body: {response.text[:200]}")
+
+        if response.status_code == 204:
+            logger.info("\n✓ SUCCESS: HTTP Basic Auth works for deletion!")
+        elif response.status_code == 401:
+            logger.info(
+                "\n✗ HTTP Basic Auth not supported - use registration_access_token instead"
+            )
+        else:
+            logger.warning(f"\n? Unexpected status: {response.status_code}")
+
+    # This test is informational - we don't fail if Basic Auth doesn't work
+    # as long as Bearer token works
+    assert True

tests/server/oauth/test_dcr_token_type.py

@@ -0,0 +1,395 @@
+"""
+Tests for Dynamic Client Registration (DCR) token_type parameter.
+
+These tests verify that the Nextcloud OIDC server properly honors the token_type
+parameter during client registration, issuing the correct type of access tokens:
+- token_type="JWT" → JWT-formatted tokens (RFC 9068)
+- token_type="Bearer" → Opaque tokens (standard OAuth2)
+
+This is critical for ensuring:
+1. Client choice is respected by the OIDC server
+2. JWT tokens embed scope information in claims
+3. Opaque tokens require introspection for scope information
+"""
+
+import base64
+import json
+import logging
+import os
+import secrets
+import time
+from urllib.parse import quote
+
+import anyio
+import httpx
+import pytest
+
+from nextcloud_mcp_server.auth.client_registration import register_client
+
+from ...conftest import _handle_oauth_consent_screen
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+def is_jwt_format(token: str) -> bool:
+    """
+    Check if a token is in JWT format (three base64-encoded parts separated by dots).
+
+    Args:
+        token: The access token to check
+
+    Returns:
+        True if token appears to be JWT format, False otherwise
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        return False
+
+    # Try to decode the header and payload to verify it's valid base64
+    try:
+        # Add padding if needed
+        header_part = parts[0] + "=" * (4 - len(parts[0]) % 4)
+        payload_part = parts[1] + "=" * (4 - len(parts[1]) % 4)
+
+        # Decode
+        base64.urlsafe_b64decode(header_part)
+        base64.urlsafe_b64decode(payload_part)
+
+        return True
+    except Exception:
+        return False
+
+
+def decode_jwt_payload(token: str) -> dict:
+    """
+    Decode the payload of a JWT token without verification.
+
+    Args:
+        token: The JWT token
+
+    Returns:
+        Dict containing the decoded payload
+
+    Raises:
+        ValueError: If token is not valid JWT format
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError(f"Invalid JWT format: expected 3 parts, got {len(parts)}")
+
+    # Decode payload (second part)
+    payload_part = parts[1] + "=" * (4 - len(parts[1]) % 4)
+    payload_bytes = base64.urlsafe_b64decode(payload_part)
+    return json.loads(payload_bytes)
+
+
+async def get_oauth_token_with_client(
+    browser,
+    client_id: str,
+    client_secret: str,
+    token_endpoint: str,
+    authorization_endpoint: str,
+    callback_url: str,
+    auth_states: dict,
+    scopes: str = "openid profile email notes:read notes:write",
+) -> str:
+    """
+    Helper to obtain OAuth access token using existing client credentials.
+
+    Args:
+        browser: Playwright browser instance
+        client_id: OAuth client ID
+        client_secret: OAuth client secret
+        token_endpoint: Token endpoint URL
+        authorization_endpoint: Authorization endpoint URL
+        callback_url: Callback URL for OAuth redirect
+        auth_states: Dict for storing auth codes (from callback server)
+        scopes: Space-separated list of scopes to request
+
+    Returns:
+        Access token string
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    username = os.getenv("NEXTCLOUD_USERNAME")
+    password = os.getenv("NEXTCLOUD_PASSWORD")
+
+    if not all([nextcloud_host, username, password]):
+        pytest.skip(
+            "OAuth requires NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, and NEXTCLOUD_PASSWORD"
+        )
+
+    # Generate unique state parameter
+    state = secrets.token_urlsafe(32)
+
+    # URL-encode scopes
+    scopes_encoded = quote(scopes, safe="")
+
+    # Construct authorization URL
+    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={scopes_encoded}"
+    )
+
+    # Browser automation
+    context = await browser.new_context(ignore_https_errors=True)
+    page = await context.new_page()
+
+    try:
+        await page.goto(auth_url, wait_until="networkidle", timeout=60000)
+        current_url = page.url
+
+        # Login if needed
+        if "/login" in current_url or "/index.php/login" in current_url:
+            logger.info("Logging in for DCR test...")
+            await page.wait_for_selector('input[name="user"]', timeout=10000)
+            await page.fill('input[name="user"]', username)
+            await page.fill('input[name="password"]', password)
+            await page.click('button[type="submit"]')
+            await page.wait_for_load_state("networkidle", timeout=60000)
+
+        # Handle consent screen if present
+        try:
+            await _handle_oauth_consent_screen(page, username)
+        except Exception as e:
+            logger.debug(f"No consent screen or already authorized: {e}")
+
+        # Wait for callback
+        logger.info("Waiting for OAuth callback...")
+        timeout_seconds = 30
+        start_time = time.time()
+        while state not in auth_states:
+            if time.time() - start_time > timeout_seconds:
+                raise TimeoutError(
+                    f"Timeout waiting for OAuth callback (state={state[:16]}...)"
+                )
+            await anyio.sleep(0.5)
+
+        auth_code = auth_states[state]
+        logger.info(f"Got auth code: {auth_code[:20]}...")
+
+    finally:
+        await context.close()
+
+    # Exchange code for token
+    logger.info("Exchanging authorization code for access token...")
+    async with httpx.AsyncClient(timeout=30.0) as http_client:
+        token_response = await http_client.post(
+            token_endpoint,
+            data={
+                "grant_type": "authorization_code",
+                "code": auth_code,
+                "redirect_uri": callback_url,
+                "client_id": client_id,
+                "client_secret": client_secret,
+            },
+        )
+
+        token_response.raise_for_status()
+        token_data = token_response.json()
+        access_token = token_data.get("access_token")
+
+        if not access_token:
+            raise ValueError(f"No access_token in response: {token_data}")
+
+        logger.info("Successfully obtained access token")
+        return access_token
+
+
+@pytest.mark.integration
+async def test_dcr_respects_jwt_token_type(
+    anyio_backend,
+    browser,
+    oauth_callback_server,
+):
+    """
+    Test that DCR honors token_type=JWT and issues JWT-formatted tokens.
+
+    This verifies:
+    1. Client registration with token_type="JWT" succeeds
+    2. Tokens obtained via this client are JWT format (base64.base64.signature)
+    3. JWT payload contains expected claims (sub, iss, scope, etc.)
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    auth_states, callback_url = oauth_callback_server
+
+    # Discover OIDC endpoints
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+        discovery_response = await client.get(discovery_url)
+        discovery_response.raise_for_status()
+        oidc_config = discovery_response.json()
+
+        registration_endpoint = oidc_config.get("registration_endpoint")
+        token_endpoint = oidc_config.get("token_endpoint")
+        authorization_endpoint = oidc_config.get("authorization_endpoint")
+
+    # Register client with token_type="JWT"
+    logger.info("Registering OAuth client with token_type=JWT...")
+    client_info = await register_client(
+        nextcloud_url=nextcloud_host,
+        registration_endpoint=registration_endpoint,
+        client_name="DCR Test - JWT Token Type",
+        redirect_uris=[callback_url],
+        scopes="openid profile email notes:read notes:write",
+        token_type="JWT",
+    )
+
+    logger.info(f"Registered JWT client: {client_info.client_id[:16]}...")
+
+    # Obtain token via OAuth flow
+    access_token = await get_oauth_token_with_client(
+        browser=browser,
+        client_id=client_info.client_id,
+        client_secret=client_info.client_secret,
+        token_endpoint=token_endpoint,
+        authorization_endpoint=authorization_endpoint,
+        callback_url=callback_url,
+        auth_states=auth_states,
+    )
+
+    # Verify token is JWT format
+    assert is_jwt_format(access_token), (
+        f"Expected JWT format token (3 parts separated by dots), "
+        f"but got token with {len(access_token.split('.'))} parts"
+    )
+
+    # Decode and verify JWT payload
+    payload = decode_jwt_payload(access_token)
+
+    # Verify standard JWT claims
+    assert "sub" in payload, "JWT payload missing 'sub' claim (subject/user ID)"
+    assert "iss" in payload, "JWT payload missing 'iss' claim (issuer)"
+    assert "exp" in payload, "JWT payload missing 'exp' claim (expiration)"
+    assert "iat" in payload, "JWT payload missing 'iat' claim (issued at)"
+
+    # Verify scope claim exists (critical for MCP tool filtering)
+    assert "scope" in payload, "JWT payload missing 'scope' claim"
+    scopes = payload["scope"].split()
+    assert "notes:read" in scopes, "JWT scope claim missing notes:read"
+    assert "notes:write" in scopes, "JWT scope claim missing notes:write"
+
+    logger.info(
+        f"✅ DCR with token_type=JWT works correctly! "
+        f"Token is JWT format with scope claim: {payload['scope']}"
+    )
+
+
+@pytest.mark.integration
+async def test_dcr_respects_bearer_token_type(
+    anyio_backend,
+    browser,
+    oauth_callback_server,
+):
+    """
+    Test that DCR honors token_type=Bearer and issues opaque tokens.
+
+    This verifies:
+    1. Client registration with token_type="Bearer" succeeds
+    2. Tokens obtained via this client are opaque (NOT JWT format)
+    3. Opaque tokens are simple strings, not base64-encoded structures
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    auth_states, callback_url = oauth_callback_server
+
+    # Discover OIDC endpoints
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+        discovery_response = await client.get(discovery_url)
+        discovery_response.raise_for_status()
+        oidc_config = discovery_response.json()
+
+        registration_endpoint = oidc_config.get("registration_endpoint")
+        token_endpoint = oidc_config.get("token_endpoint")
+        authorization_endpoint = oidc_config.get("authorization_endpoint")
+
+    # Register client with token_type="Bearer" (opaque tokens)
+    logger.info("Registering OAuth client with token_type=Bearer...")
+    client_info = await register_client(
+        nextcloud_url=nextcloud_host,
+        registration_endpoint=registration_endpoint,
+        client_name="DCR Test - Bearer Token Type",
+        redirect_uris=[callback_url],
+        scopes="openid profile email notes:read notes:write",
+        token_type="Bearer",
+    )
+
+    logger.info(f"Registered Bearer client: {client_info.client_id[:16]}...")
+
+    # Obtain token via OAuth flow
+    access_token = await get_oauth_token_with_client(
+        browser=browser,
+        client_id=client_info.client_id,
+        client_secret=client_info.client_secret,
+        token_endpoint=token_endpoint,
+        authorization_endpoint=authorization_endpoint,
+        callback_url=callback_url,
+        auth_states=auth_states,
+    )
+
+    # Verify token is NOT JWT format
+    assert not is_jwt_format(access_token), (
+        f"Expected opaque token (not JWT format), "
+        f"but got token that looks like JWT: {access_token[:50]}..."
+    )
+
+    # Opaque tokens should be simple strings (not parseable as JWT)
+    try:
+        decode_jwt_payload(access_token)
+        pytest.fail("Opaque token should not be decodable as JWT")
+    except ValueError:
+        # Expected - opaque tokens are not JWT format
+        pass
+
+    logger.info(
+        f"✅ DCR with token_type=Bearer works correctly! "
+        f"Token is opaque (not JWT format): {access_token[:30]}..."
+    )
+
+
+@pytest.mark.integration
+async def test_jwt_tokens_embed_scopes_in_payload():
+    """
+    Test that JWT tokens contain scope information in the payload.
+
+    This is critical for MCP server's dynamic tool filtering, which extracts
+    scopes from JWT token claims without making additional API calls.
+
+    Note: Uses existing shared JWT OAuth client fixture.
+    """
+    from ...conftest import (
+        DEFAULT_FULL_SCOPES,
+    )
+
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("Test requires NEXTCLOUD_HOST")
+
+    # This test leverages the existing JWT client creation helper
+    # to verify that JWT tokens contain scope claims
+
+    # The test verifies that when we create a JWT client with specific scopes,
+    # and obtain a token, the token's payload contains those scopes
+
+    # This is already tested implicitly by the scope authorization tests,
+    # but we document the behavior explicitly here for reference
+
+    logger.info(
+        "✅ JWT token scope embedding verified. "
+        f"Expected scopes in JWT payload: {DEFAULT_FULL_SCOPES}"
+    )
+
+    # This test primarily serves as documentation
+    # Actual verification happens in test_dcr_respects_jwt_token_type
+    assert True

tests/server/oauth/test_introspection_authorization.py

@@ -0,0 +1,479 @@
+"""
+Integration tests for token introspection authorization.
+
+These tests verify that the introspection endpoint properly enforces
+authorization rules:
+1. Client authentication is required (401 if missing)
+2. Only the token owner can introspect its own tokens
+3. Only the designated resource server can introspect tokens
+4. Other clients cannot introspect tokens they don't own or aren't the audience for
+"""
+
+import logging
+import os
+import secrets
+
+# Import helpers from conftest
+import time
+from typing import AsyncGenerator
+from urllib.parse import quote
+
+import anyio
+import httpx
+import pytest
+
+# Import from the root tests/ conftest.py using relative import
+from ...conftest import _handle_oauth_consent_screen
+
+logger = logging.getLogger(__name__)
+
+
+@pytest.fixture(scope="module")
+def nextcloud_host() -> str:
+    """Get Nextcloud host from environment."""
+    host = os.getenv("NEXTCLOUD_HOST", "http://localhost:8080")
+    return host
+
+
+@pytest.fixture(scope="module")
+async def oidc_endpoints(nextcloud_host: str) -> dict[str, str]:
+    """Discover OIDC endpoints."""
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+        response = await client.get(discovery_url)
+        response.raise_for_status()
+        config = response.json()
+
+        return {
+            "token_endpoint": config["token_endpoint"],
+            "authorization_endpoint": config.get("authorization_endpoint"),
+            "introspection_endpoint": config.get("introspection_endpoint"),
+            "registration_endpoint": config.get("registration_endpoint"),
+        }
+
+
+@pytest.fixture(scope="module")
+async def test_oauth_clients(
+    nextcloud_host: str, oidc_endpoints: dict[str, str], oauth_callback_server
+) -> AsyncGenerator[dict[str, tuple[str, str]], None]:
+    """
+    Create multiple OAuth clients for introspection testing.
+
+    Returns a dict mapping client names to (client_id, client_secret) tuples.
+    """
+    from nextcloud_mcp_server.auth.client_registration import register_client
+
+    clients = {}
+    registration_endpoint = oidc_endpoints["registration_endpoint"]
+
+    # Get the correct callback URL from the oauth_callback_server fixture
+    auth_states, callback_url = oauth_callback_server
+
+    # Create client A (will be the token owner)
+    logger.info("Creating OAuth client A for introspection testing")
+    client_a = await register_client(
+        nextcloud_url=nextcloud_host,
+        registration_endpoint=registration_endpoint,
+        client_name="Introspection Test Client A",
+        redirect_uris=[callback_url],
+        scopes="openid profile email",
+        token_type="Bearer",  # Use opaque tokens for this test
+    )
+    clients["clientA"] = (client_a.client_id, client_a.client_secret)
+    logger.info(f"Created client A: {client_a.client_id[:16]}...")
+
+    # Create client B (will attempt to introspect client A's tokens)
+    logger.info("Creating OAuth client B for introspection testing")
+    client_b = await register_client(
+        nextcloud_url=nextcloud_host,
+        registration_endpoint=registration_endpoint,
+        client_name="Introspection Test Client B",
+        redirect_uris=[callback_url],
+        scopes="openid profile email",
+        token_type="Bearer",
+    )
+    clients["clientB"] = (client_b.client_id, client_b.client_secret)
+    logger.info(f"Created client B: {client_b.client_id[:16]}...")
+
+    # Create client C (third party, should not be able to introspect)
+    logger.info("Creating OAuth client C for introspection testing")
+    client_c = await register_client(
+        nextcloud_url=nextcloud_host,
+        registration_endpoint=registration_endpoint,
+        client_name="Introspection Test Client C",
+        redirect_uris=[callback_url],
+        scopes="openid profile email",
+        token_type="Bearer",
+    )
+    clients["clientC"] = (client_c.client_id, client_c.client_secret)
+    logger.info(f"Created client C: {client_c.client_id[:16]}...")
+
+    yield clients
+
+    # Cleanup is handled by Nextcloud - clients will be removed when tests are done
+    logger.info("Test OAuth clients fixture complete")
+
+
+@pytest.mark.integration
+async def test_introspection_requires_client_authentication(
+    oidc_endpoints: dict[str, str],
+):
+    """
+    Test that the introspection endpoint requires client authentication.
+
+    Expected: 401 UNAUTHORIZED when credentials are missing or invalid.
+    """
+    introspection_endpoint = oidc_endpoints["introspection_endpoint"]
+    if not introspection_endpoint:
+        pytest.skip("Introspection endpoint not available")
+
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        # Test 1: No credentials
+        response = await client.post(
+            introspection_endpoint,
+            data={"token": "some_token"},
+        )
+        assert response.status_code == 401, "Should return 401 without credentials"
+        data = response.json()
+        assert data.get("error") == "invalid_client"
+
+        # Test 2: Invalid credentials
+        response = await client.post(
+            introspection_endpoint,
+            data={"token": "some_token"},
+            auth=("invalid_client", "invalid_secret"),
+        )
+        assert response.status_code == 401, "Should return 401 with invalid credentials"
+        data = response.json()
+        logger.info(f"Invalid client response: {data}")
+        # Response may be either {"error": "invalid_client"} or {"message": "..."}
+        # Both are acceptable as long as we get 401
+        assert "error" in data or "message" in data, "Should return error information"
+
+
+async def _obtain_token_for_client(
+    browser,
+    oauth_callback_server,
+    client_id: str,
+    client_secret: str,
+    token_endpoint: str,
+    authorization_endpoint: str,
+    scope: str = "openid profile email",
+    resource: str | None = None,
+) -> str:
+    """
+    Helper to obtain an OAuth token using existing callback server and playwright automation.
+
+    Reuses the pattern from conftest.py's playwright_oauth_token fixture.
+    """
+    username = os.getenv("NEXTCLOUD_USERNAME", "admin")
+    password = os.getenv("NEXTCLOUD_PASSWORD", "admin")
+
+    # Get callback server from fixture
+    auth_states, callback_url = oauth_callback_server
+
+    # Generate unique state parameter
+    state = secrets.token_urlsafe(32)
+
+    # Construct authorization URL
+    auth_url_parts = [
+        f"{authorization_endpoint}?",
+        "response_type=code&",
+        f"client_id={client_id}&",
+        f"redirect_uri={quote(callback_url, safe='')}&",
+        f"state={state}&",
+        f"scope={quote(scope, safe='')}",
+    ]
+
+    if resource:
+        auth_url_parts.append(f"&resource={quote(resource, safe='')}")
+
+    auth_url = "".join(auth_url_parts)
+
+    logger.info(f"Obtaining token for client {client_id[:16]}... with scopes={scope}")
+    if resource:
+        logger.info(f"  Resource parameter: {resource[:16]}...")
+
+    # Browser automation (same pattern as conftest.py)
+    context = await browser.new_context(ignore_https_errors=True)
+    page = await context.new_page()
+
+    try:
+        logger.debug(f"Navigating to: {auth_url[:100]}...")
+        await page.goto(auth_url, wait_until="networkidle", timeout=60000)
+        current_url = page.url
+        logger.debug(f"Current URL after navigation: {current_url}")
+
+        # Handle login if needed
+        if "/login" in current_url or "/index.php/login" in current_url:
+            logger.info("Login page detected, filling credentials...")
+            await page.wait_for_selector('input[name="user"]', timeout=10000)
+            await page.fill('input[name="user"]', username)
+            await page.fill('input[name="password"]', password)
+            await page.click('button[type="submit"]')
+            await page.wait_for_load_state("networkidle", timeout=60000)
+            current_url = page.url
+            logger.info(f"After login: {current_url}")
+
+        # Wait a bit for page to fully render after login
+        await anyio.sleep(2)
+        current_url = page.url
+        logger.info(f"After waiting, current URL: {current_url}")
+
+        # Check page content for debugging
+        page_content = await page.content()
+        has_consent_div = "#oidc-consent" in page_content
+        logger.info(f"Page has #oidc-consent div: {has_consent_div}")
+
+        # Handle consent screen using the helper from conftest
+        try:
+            consent_handled = await _handle_oauth_consent_screen(page, username)
+            logger.info(f"Consent screen handled: {consent_handled}")
+        except Exception as e:
+            logger.warning(f"Error handling consent screen: {e}")
+            # Take screenshot for debugging
+            await page.screenshot(path=f"/tmp/consent_error_{state[:8]}.png")
+            logger.error("Consent error screenshot saved")
+            raise
+
+        # Wait for callback server to receive auth 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:
+                screenshot_path = (
+                    f"/tmp/oauth_introspection_test_timeout_{state[:8]}.png"
+                )
+                await page.screenshot(path=screenshot_path)
+                logger.error(f"Timeout! Screenshot saved to {screenshot_path}")
+                logger.error(f"Current URL: {page.url}")
+                raise TimeoutError(
+                    f"Timeout waiting for OAuth callback (state={state[:16]}...)"
+                )
+            await anyio.sleep(0.5)
+
+        auth_code = auth_states[state]
+        logger.info(f"Successfully received auth code: {auth_code[:20]}...")
+
+    finally:
+        await context.close()
+
+    # Exchange code for token
+    logger.debug("Exchanging authorization code for access token...")
+    async with httpx.AsyncClient(timeout=30.0) as http_client:
+        token_response = await http_client.post(
+            token_endpoint,
+            data={
+                "grant_type": "authorization_code",
+                "code": auth_code,
+                "redirect_uri": callback_url,
+                "client_id": client_id,
+                "client_secret": client_secret,
+            },
+        )
+
+        token_response.raise_for_status()
+        token_data = token_response.json()
+        access_token = token_data.get("access_token")
+
+        if not access_token:
+            raise ValueError(f"No access_token in response: {token_data}")
+
+        logger.info("Successfully obtained access token")
+        return access_token
+
+
+@pytest.mark.integration
+async def test_client_cannot_introspect_other_clients_tokens(
+    playwright_oauth_token: str,
+    shared_oauth_client_credentials: tuple,
+    test_oauth_clients: dict[str, tuple[str, str]],
+    oidc_endpoints: dict[str, str],
+):
+    """
+    Test that one client cannot introspect tokens owned by another client.
+
+    This test uses a pre-authorized shared OAuth client (with existing token)
+    and verifies that a different client cannot introspect that token.
+
+    Expected: introspection returns {active: false} to not reveal token existence.
+    """
+    introspection_endpoint = oidc_endpoints["introspection_endpoint"]
+    if not introspection_endpoint:
+        pytest.skip("Introspection endpoint not available")
+
+    # Use the shared OAuth client's token (pre-authorized, working)
+    access_token = playwright_oauth_token
+    shared_client_id, shared_client_secret, _, _, _ = shared_oauth_client_credentials
+
+    # Get a different client to try to introspect
+    different_client_id, different_client_secret = test_oauth_clients["clientB"]
+
+    logger.info(
+        f"Testing introspection with shared client token: {access_token[:16]}..."
+    )
+    logger.info(f"Shared client ID: {shared_client_id[:16]}...")
+    logger.info(f"Different client ID: {different_client_id[:16]}...")
+
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        # Test 1: The owning client (shared client) can introspect its own token
+        response = await client.post(
+            introspection_endpoint,
+            data={"token": access_token},
+            auth=(shared_client_id, shared_client_secret),
+        )
+        assert response.status_code == 200
+        data = response.json()
+        logger.info(f"Owner client introspection response: {data}")
+        assert data.get("active") is True, (
+            "Owner client should be able to introspect its own token"
+        )
+
+        # Test 2: A different client CANNOT introspect the shared client's token
+        response = await client.post(
+            introspection_endpoint,
+            data={"token": access_token},
+            auth=(different_client_id, different_client_secret),
+        )
+        assert response.status_code == 200
+        data = response.json()
+        logger.info(f"Different client introspection response: {data}")
+        assert data.get("active") is False, (
+            "Different client should NOT be able to introspect another client's token"
+        )
+
+
+@pytest.mark.integration
+async def test_introspection_with_resource_parameter(
+    browser,
+    oauth_callback_server,
+    test_oauth_clients: dict[str, tuple[str, str]],
+    oidc_endpoints: dict[str, str],
+    nextcloud_host: str,
+):
+    """
+    Test that the resource server (specified via 'resource' parameter) can introspect tokens.
+
+    This test verifies that when a token is issued with resource=clientB,
+    clientB can introspect it even though it's owned by clientA.
+
+    This requires obtaining a token with the 'resource' parameter set via authorization code grant.
+
+    Uses playwright automation to obtain real tokens.
+    """
+    introspection_endpoint = oidc_endpoints["introspection_endpoint"]
+    if not introspection_endpoint:
+        pytest.skip("Introspection endpoint not available")
+
+    client_a_id, client_a_secret = test_oauth_clients["clientA"]
+    client_b_id, client_b_secret = test_oauth_clients["clientB"]
+    client_c_id, client_c_secret = test_oauth_clients["clientC"]
+
+    token_endpoint = oidc_endpoints["token_endpoint"]
+    authorization_endpoint = oidc_endpoints.get("authorization_endpoint")
+    if not authorization_endpoint:
+        pytest.skip("Authorization endpoint not available")
+
+    # Obtain a token for client A with resource parameter set to client B
+    try:
+        access_token = await _obtain_token_for_client(
+            browser=browser,
+            oauth_callback_server=oauth_callback_server,
+            client_id=client_a_id,
+            client_secret=client_a_secret,
+            token_endpoint=token_endpoint,
+            authorization_endpoint=authorization_endpoint,
+            scope="openid profile email",
+            resource=client_b_id,  # Set client B as the resource server
+        )
+    except Exception as e:
+        logger.error(f"Failed to obtain token with resource parameter: {e}")
+        pytest.skip(f"Cannot obtain test token with resource parameter: {e}")
+
+    logger.info(
+        f"Obtained access token from client A with resource={client_b_id}: {access_token[:16]}..."
+    )
+
+    # Test introspection
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        # Test 1: Client A (owner) can introspect its own token
+        response = await client.post(
+            introspection_endpoint,
+            data={"token": access_token},
+            auth=(client_a_id, client_a_secret),
+        )
+        assert response.status_code == 200
+        data = response.json()
+        logger.info(f"Client A (owner) introspection response: {data}")
+        assert data.get("active") is True, (
+            "Client A (owner) should be able to introspect its own token"
+        )
+
+        # Test 2: Client B (resource server) can introspect the token
+        response = await client.post(
+            introspection_endpoint,
+            data={"token": access_token},
+            auth=(client_b_id, client_b_secret),
+        )
+        assert response.status_code == 200
+        data = response.json()
+        logger.info(f"Client B (resource server) introspection response: {data}")
+        assert data.get("active") is True, (
+            "Client B (resource server) should be able to introspect token intended for it"
+        )
+
+        # Verify the resource field in the response matches client B
+        logger.info(f"Full introspection response from Client B: {data}")
+
+        # Test 3: Client C CANNOT introspect the token (not owner, not resource server)
+        response = await client.post(
+            introspection_endpoint,
+            data={"token": access_token},
+            auth=(client_c_id, client_c_secret),
+        )
+        assert response.status_code == 200
+        data = response.json()
+        logger.info(f"Client C (third party) introspection response: {data}")
+        assert data.get("active") is False, (
+            "Client C should NOT be able to introspect token (not owner or resource server)"
+        )
+
+
+@pytest.mark.integration
+async def test_introspection_returns_inactive_for_invalid_token(
+    test_oauth_clients: dict[str, tuple[str, str]],
+    oidc_endpoints: dict[str, str],
+):
+    """
+    Test that introspection returns {active: false} for invalid/unknown tokens.
+
+    This is important for security - we shouldn't reveal whether a token exists or not.
+    """
+    introspection_endpoint = oidc_endpoints["introspection_endpoint"]
+    if not introspection_endpoint:
+        pytest.skip("Introspection endpoint not available")
+
+    client_a_id, client_a_secret = test_oauth_clients["clientA"]
+
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        # Test with a fake token
+        response = await client.post(
+            introspection_endpoint,
+            data={"token": "completely_fake_token_12345"},
+            auth=(client_a_id, client_a_secret),
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        logger.info(f"Introspection response for fake token: {data}")
+        assert data.get("active") is False, (
+            "Should return active=false for invalid token"
+        )
+        # Should NOT return any other information
+        assert len(data) == 1, "Should only return 'active' field for invalid token"
+
+
+if __name__ == "__main__":
+    # Run with: uv run pytest tests/server/test_introspection_authorization.py -v -s
+    pytest.main([__file__, "-v", "-s", "-m", "integration"])

tests/server/oauth/test_oauth_core.py

@@ -0,0 +1,262 @@
+"""Core OAuth integration tests.
+
+Consolidated from:
+- test_mcp_oauth.py: Basic OAuth connectivity
+- test_mcp_oauth_jwt.py: JWT-specific operations
+- test_jwt_tokens.py: JWT token structure validation
+
+Tests verify:
+1. OAuth server connectivity and tool listing
+2. Tool execution with OAuth tokens
+3. JWT token structure and claims
+4. Multiple operations with same token (persistence)
+5. Error handling with OAuth
+"""
+
+import base64
+import json
+import logging
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+def decode_jwt_without_verification(token: str) -> dict:
+    """Decode JWT token without signature verification (for inspection only).
+
+    Returns:
+        Dict with header and payload
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError(f"Invalid JWT format: expected 3 parts, got {len(parts)}")
+
+    # Decode header
+    header = json.loads(
+        base64.urlsafe_b64decode(parts[0] + "=" * (4 - len(parts[0]) % 4))
+    )
+
+    # Decode payload
+    payload = json.loads(
+        base64.urlsafe_b64decode(parts[1] + "=" * (4 - len(parts[1]) % 4))
+    )
+
+    return {
+        "header": header,
+        "payload": payload,
+    }
+
+
+# ============================================================================
+# Basic OAuth Connectivity Tests
+# ============================================================================
+
+
+async def test_mcp_oauth_server_connection(nc_mcp_oauth_client):
+    """Test connection to OAuth-enabled MCP server."""
+    result = await nc_mcp_oauth_client.list_tools()
+    assert result is not None
+    assert len(result.tools) > 0
+
+    logger.info(f"OAuth MCP server has {len(result.tools)} tools available")
+
+
+async def test_mcp_oauth_tool_execution(nc_mcp_oauth_client):
+    """Test executing a tool on the OAuth-enabled MCP server."""
+    # Example: Execute the 'nc_notes_search_notes' tool
+    result = await nc_mcp_oauth_client.call_tool(
+        "nc_notes_search_notes", arguments={"query": ""}
+    )
+
+    assert result.isError is False, f"Tool execution failed: {result.content}"
+    assert result.content is not None
+    response_data = json.loads(result.content[0].text)
+
+    # The search response should have a 'results' field containing the list
+    assert "results" in response_data
+    assert isinstance(response_data["results"], list)
+
+    logger.info(
+        f"Successfully executed 'nc_notes_search_notes' tool on OAuth MCP server and got {len(response_data['results'])} notes."
+    )
+
+
+async def test_mcp_oauth_client_with_playwright(nc_mcp_oauth_client):
+    """Test that MCP OAuth client via Playwright can execute tools."""
+    # Test: Execute the 'nc_notes_search_notes' tool
+    result = await nc_mcp_oauth_client.call_tool(
+        "nc_notes_search_notes", arguments={"query": ""}
+    )
+
+    assert result.isError is False, f"Tool execution failed: {result.content}"
+    assert result.content is not None
+    response_data = json.loads(result.content[0].text)
+
+    # The search response should have a 'results' field containing the list
+    assert "results" in response_data
+    assert isinstance(response_data["results"], list)
+
+    logger.info(
+        f"Successfully executed 'nc_notes_search_notes' tool on Playwright OAuth MCP server and got {len(response_data['results'])} notes."
+    )
+
+
+# ============================================================================
+# JWT-Specific Tests
+# ============================================================================
+
+
+async def test_jwt_tool_list_operations(nc_mcp_oauth_jwt_client):
+    """Test that list_tools works with JWT authentication and returns expected tools.
+
+    This test verifies that tools are properly filtered based on per-app scopes:
+    - notes:read/write → Notes app tools
+    - calendar:read/write → Calendar app tools
+    - files:read/write → WebDAV/Files app tools
+    - etc.
+    """
+    result = await nc_mcp_oauth_jwt_client.list_tools()
+
+    # Verify we have tools
+    assert len(result.tools) > 0
+
+    # Verify expected tools exist based on configured scopes
+    tool_names = [tool.name for tool in result.tools]
+
+    # Notes tools (require notes:read and notes:write)
+    assert "nc_notes_get_note" in tool_names, "Missing nc_notes_get_note (notes:read)"
+    assert "nc_notes_create_note" in tool_names, (
+        "Missing nc_notes_create_note (notes:write)"
+    )
+
+    # Calendar tools (require calendar:read and calendar:write)
+    assert "nc_calendar_list_calendars" in tool_names, (
+        "Missing nc_calendar_list_calendars (calendar:read)"
+    )
+    assert "nc_calendar_create_event" in tool_names, (
+        "Missing nc_calendar_create_event (calendar:write)"
+    )
+
+    # Verify we have a reasonable number of tools for the configured scopes
+    # With notes + calendar scopes, expect ~20-30 tools
+    assert len(tool_names) >= 20, (
+        f"Expected at least 20 tools with notes+calendar scopes, got {len(tool_names)}"
+    )
+
+    logger.info(
+        f"JWT OAuth server provides {len(result.tools)} tools with configured per-app scopes"
+    )
+
+
+async def test_jwt_multiple_operations(nc_mcp_oauth_jwt_client):
+    """Test multiple operations with same JWT token to verify token persistence.
+
+    JWT tokens should work across multiple tool calls without re-authentication,
+    demonstrating that the token is properly cached and reused.
+    """
+    # First operation: Search notes
+    result1 = await nc_mcp_oauth_jwt_client.call_tool(
+        "nc_notes_search_notes", arguments={"query": ""}
+    )
+    assert result1.isError is False
+
+    # Second operation: List calendars
+    result2 = await nc_mcp_oauth_jwt_client.call_tool(
+        "nc_calendar_list_calendars", arguments={}
+    )
+    assert result2.isError is False
+
+    # Third operation: List directory
+    result3 = await nc_mcp_oauth_jwt_client.call_tool(
+        "nc_webdav_list_directory", arguments={"path": "/"}
+    )
+    assert result3.isError is False
+
+    logger.info(
+        "Successfully executed 3 different operations with same JWT token (token persistence verified)"
+    )
+
+
+async def test_jwt_error_handling(nc_mcp_oauth_jwt_client):
+    """Test error handling with JWT authentication.
+
+    Verifies that invalid operations return proper errors even with valid JWT tokens.
+    """
+    # Try to get a non-existent note
+    result = await nc_mcp_oauth_jwt_client.call_tool(
+        "nc_notes_get_note", arguments={"note_id": 999999}
+    )
+
+    # Should get an error (note doesn't exist)
+    assert result.isError is True
+    logger.info("JWT OAuth server correctly handles errors for invalid operations")
+
+
+# ============================================================================
+# JWT Token Structure Tests
+# ============================================================================
+
+
+async def test_jwt_tokens_embed_scopes_in_payload():
+    """Document that JWT tokens embed scopes in the payload (RFC 9068).
+
+    This test documents expected JWT structure based on manual testing.
+    """
+    expected_structure = {
+        "header": {
+            "typ": "at+JWT",  # RFC 9068 access token type
+            "alg": "RS256",  # Signature algorithm
+        },
+        "payload_claims": {
+            "iss": "issuer URL",
+            "sub": "user ID",
+            "aud": "client ID",
+            "exp": "expiration timestamp",
+            "iat": "issued at timestamp",
+            "scope": "space-separated scope string (e.g., 'notes:read notes:write')",
+            "client_id": "client identifier",
+            "jti": "JWT ID",
+        },
+        "scope_claim": {
+            "format": "space-separated string",
+            "example": "openid profile email notes:read notes:write",
+            "extraction": "payload['scope'].split()",
+        },
+    }
+
+    logger.info("JWT token structure (RFC 9068):")
+    logger.info(json.dumps(expected_structure, indent=2))
+
+    # This test documents expected behavior
+    assert True
+
+
+async def test_opaque_token_vs_jwt_comparison():
+    """Document differences between opaque tokens and JWT tokens.
+
+    This test captures our findings about the two token types.
+    """
+    findings = {
+        "jwt_advantages": [
+            "Scopes embedded in payload - no introspection needed",
+            "Self-contained - can validate with JWKS",
+            "Standard approach (RFC 9068)",
+        ],
+        "jwt_disadvantages": [
+            "10-15x larger than opaque tokens (~800-1200 chars vs 72)",
+            "Cannot be easily revoked (until expiration)",
+        ],
+        "token_sizes": {
+            "opaque": "72 characters",
+            "jwt": "~800-1200 characters",
+        },
+        "recommendation": "Use JWT for MCP server (scopes available without introspection)",
+    }
+
+    logger.info("JWT vs Opaque token comparison:")
+    logger.info(json.dumps(findings, indent=2))
+
+    assert True

tests/server/oauth/test_oauth_deck_permissions.py

@@ -46,7 +46,6 @@ async def delete_board_acl(nc_client, board_id: int, acl_id: int):
     logger.info(f"Deleted ACL {acl_id} from board {board_id}")
 
 
-@pytest.mark.anyio
 async def test_deck_board_view_permissions(
     nc_client, alice_mcp_client, bob_mcp_client, diana_mcp_client
 ):
@@ -119,7 +118,6 @@ async def test_deck_board_view_permissions(
         await nc_client.deck.delete_board(board_id)
 
 
-@pytest.mark.anyio
 async def test_deck_board_edit_permissions(
     nc_client, alice_mcp_client, charlie_mcp_client, bob_mcp_client
 ):
@@ -214,7 +212,6 @@ async def test_deck_board_edit_permissions(
         await nc_client.deck.delete_board(board_id)
 
 
-@pytest.mark.anyio
 async def test_deck_board_manage_permissions(
     nc_client, alice_mcp_client, charlie_mcp_client
 ):
@@ -289,7 +286,6 @@ async def test_deck_board_manage_permissions(
         await nc_client.deck.delete_board(board_id)
 
 
-@pytest.mark.anyio
 async def test_deck_user_isolation(nc_client, alice_mcp_client, bob_mcp_client):
     """
     Test that users can only see their own boards when not shared.

tests/server/oauth/test_oauth_file_permissions.py

@@ -18,7 +18,6 @@ logger = logging.getLogger(__name__)
 pytestmark = [pytest.mark.integration, pytest.mark.oauth]
 
 
-@pytest.mark.anyio
 async def test_file_share_read_permissions(
     alice_mcp_client, bob_mcp_client, diana_mcp_client
 ):
@@ -104,7 +103,6 @@ async def test_file_share_read_permissions(
         )
 
 
-@pytest.mark.anyio
 async def test_file_share_write_permissions(
     alice_mcp_client, charlie_mcp_client, bob_mcp_client
 ):
@@ -210,7 +208,6 @@ async def test_file_share_write_permissions(
         )
 
 
-@pytest.mark.anyio
 async def test_file_list_permissions(alice_mcp_client, bob_mcp_client):
     """
     Test that file listing respects share permissions.
@@ -276,9 +273,9 @@ async def test_file_list_permissions(alice_mcp_client, bob_mcp_client):
 
         if not result.isError:
             response_data = json.loads(result.content[0].text)
-            if not isinstance(response_data, list):
-                response_data = [response_data] if response_data else []
-            file_names = [f["name"] for f in response_data]
+            # Extract files from DirectoryListing response
+            files = response_data.get("files", [])
+            file_names = [f["name"] for f in files]
             logger.info(f"Alice can see files: {file_names}")
 
             # Alice should see her own files
@@ -294,9 +291,9 @@ async def test_file_list_permissions(alice_mcp_client, bob_mcp_client):
 
         if not result.isError:
             response_data = json.loads(result.content[0].text)
-            if not isinstance(response_data, list):
-                response_data = [response_data] if response_data else []
-            file_names = [f["name"] for f in response_data]
+            # Extract files from DirectoryListing response
+            files = response_data.get("files", [])
+            file_names = [f["name"] for f in files]
             logger.info(f"Bob can see files: {file_names}")
 
             # Bob should see his own file, but not Alice's private file
@@ -326,7 +323,6 @@ async def test_file_list_permissions(alice_mcp_client, bob_mcp_client):
         )
 
 
-@pytest.mark.anyio
 async def test_folder_share_permissions(alice_mcp_client, bob_mcp_client):
     """
     Test that folder sharing works correctly.
@@ -383,12 +379,12 @@ async def test_folder_share_permissions(alice_mcp_client, bob_mcp_client):
 
         if not result.isError:
             response_data = json.loads(result.content[0].text)
-            if not isinstance(response_data, list):
-                response_data = [response_data] if response_data else []
-            logger.info(f"Bob can see {len(response_data)} files in shared folder")
+            # Extract files from DirectoryListing response
+            files = response_data.get("files", [])
+            logger.info(f"Bob can see {len(files)} files in shared folder")
 
             # Bob should see the file in the shared folder
-            file_names = [f["name"] for f in response_data]
+            file_names = [f["name"] for f in files]
             assert "document.txt" in file_names, (
                 "Bob should see the file in shared folder"
             )

tests/server/oauth/test_oauth_notes_permissions.py

@@ -15,7 +15,6 @@ logger = logging.getLogger(__name__)
 pytestmark = [pytest.mark.integration, pytest.mark.oauth]
 
 
-@pytest.mark.anyio
 async def test_notes_share_read_permissions(
     nc_client, alice_mcp_client, bob_mcp_client, diana_mcp_client
 ):
@@ -82,7 +81,6 @@ async def test_notes_share_read_permissions(
         await nc_client.notes.delete_note(note_id)
 
 
-@pytest.mark.anyio
 async def test_notes_share_write_permissions(
     nc_client, alice_mcp_client, charlie_mcp_client, bob_mcp_client
 ):
@@ -149,7 +147,6 @@ async def test_notes_share_write_permissions(
         await nc_client.notes.delete_note(note_id)
 
 
-@pytest.mark.anyio
 async def test_user_isolation_notes(nc_client, alice_mcp_client, bob_mcp_client):
     """
     Test that users can only see their own notes when not shared.
@@ -222,7 +219,6 @@ async def test_user_isolation_notes(nc_client, alice_mcp_client, bob_mcp_client)
         await nc_client.notes.delete_note(bob_note_id)
 
 
-@pytest.mark.anyio
 async def test_oauth_mcp_clients_initialized(
     alice_mcp_client, bob_mcp_client, charlie_mcp_client, diana_mcp_client
 ):

tests/server/oauth/test_scope_authorization.py

@@ -1,11 +1,14 @@
 """Integration tests for OAuth scope-based authorization and dynamic tool filtering.
 
 These tests verify:
-1. Dynamic tool filtering based on user's token scopes
+1. Dynamic tool filtering based on user's token scopes (using JWT tokens)
 2. Scope enforcement (403 responses for insufficient scopes)
-3. Protected Resource Metadata (PRM) endpoint
+3. Protected Resource Metadata (PRM) endpoint (RFC 9728)
 4. WWW-Authenticate challenge headers
 5. BasicAuth bypass (all tools visible)
+
+Note: Tests use JWT OAuth tokens because scopes are embedded in the token payload,
+enabling efficient scope-based tool filtering without additional API calls.
 """
 
 import pytest
@@ -16,17 +19,17 @@ async def test_prm_endpoint():
     """Test that the Protected Resource Metadata endpoint returns correct data."""
     import httpx
 
-    # Test the PRM endpoint directly
+    # Test the PRM endpoint directly (RFC 9728 - path includes /mcp resource)
     async with httpx.AsyncClient() as client:
         response = await client.get(
-            "http://localhost:8001/.well-known/oauth-protected-resource"
+            "http://localhost:8001/.well-known/oauth-protected-resource/mcp"
         )
         assert response.status_code == 200
 
         prm_data = response.json()
-        assert prm_data["resource"] == "http://localhost:8001"
-        assert "nc:read" in prm_data["scopes_supported"]
-        assert "nc:write" in prm_data["scopes_supported"]
+        assert prm_data["resource"] == "http://localhost:8001/mcp"
+        assert "notes:read" in prm_data["scopes_supported"]
+        assert "notes:write" in prm_data["scopes_supported"]
         assert "http://localhost:8080" in prm_data["authorization_servers"]
         assert "header" in prm_data["bearer_methods_supported"]
         assert "RS256" in prm_data["resource_signing_alg_values_supported"]
@@ -56,12 +59,12 @@ async def test_basicauth_shows_all_tools(nc_mcp_client):
 
 @pytest.mark.integration
 async def test_read_only_token_filters_write_tools(nc_mcp_oauth_client_read_only):
-    """Test that a token with only nc:read scope filters out write tools."""
+    """Test that a token with only read scopes filters out write tools."""
     import logging
 
     logger = logging.getLogger(__name__)
 
-    # Connect with token that has only "nc:read" scope
+    # Connect with token that has only "notes:read" scope
     result = await nc_mcp_oauth_client_read_only.list_tools()
     assert result is not None
     assert len(result.tools) > 0
@@ -69,29 +72,27 @@ async def test_read_only_token_filters_write_tools(nc_mcp_oauth_client_read_only
     tool_names = [tool.name for tool in result.tools]
     logger.info(f"Read-only token sees {len(tool_names)} tools")
 
-    # Verify read tools are present
+    # Verify read tools are present (only for apps with :read scopes)
+    # Read-only token has: notes:read, calendar:read, contacts:read,
+    # cookbook:read, deck:read, tables:read, files:read, sharing:read
     expected_read_tools = [
-        "nc_notes_get_note",
-        "nc_notes_search_notes",
-        "nc_calendar_list_calendars",
-        "nc_calendar_get_event",
-        "nc_webdav_list_directory",
-        "nc_webdav_read_file",
+        "nc_notes_get_note",  # notes:read
+        "nc_notes_search_notes",  # notes:read
+        "nc_calendar_list_calendars",  # calendar:read
+        "nc_calendar_get_event",  # calendar:read
     ]
 
     for tool in expected_read_tools:
         assert tool in tool_names, f"Expected read tool {tool} not found in tool list"
 
-    # Verify write tools are NOT present
+    # Verify write tools are NOT present (filtered out)
     write_tools_should_be_filtered = [
-        "nc_notes_create_note",
-        "nc_notes_update_note",
-        "nc_notes_delete_note",
-        "nc_calendar_create_event",
-        "nc_calendar_update_event",
-        "nc_calendar_delete_event",
-        "nc_webdav_write_file",
-        "nc_webdav_create_directory",
+        "nc_notes_create_note",  # notes:write
+        "nc_notes_update_note",  # notes:write
+        "nc_notes_delete_note",  # notes:write
+        "nc_calendar_create_event",  # calendar:write
+        "nc_calendar_update_event",  # calendar:write
+        "nc_calendar_delete_event",  # calendar:write
     ]
 
     for tool in write_tools_should_be_filtered:
@@ -107,12 +108,12 @@ async def test_read_only_token_filters_write_tools(nc_mcp_oauth_client_read_only
 
 @pytest.mark.integration
 async def test_write_only_token_filters_read_tools(nc_mcp_oauth_client_write_only):
-    """Test that a token with only nc:write scope filters out read tools."""
+    """Test that a token with only write scopes filters out read tools."""
     import logging
 
     logger = logging.getLogger(__name__)
 
-    # Connect with token that has only "nc:write" scope
+    # Connect with token that has only "notes:write" scope
     result = await nc_mcp_oauth_client_write_only.list_tools()
     assert result is not None
     assert len(result.tools) > 0
@@ -121,28 +122,26 @@ async def test_write_only_token_filters_read_tools(nc_mcp_oauth_client_write_onl
     logger.info(f"Write-only token sees {len(tool_names)} tools")
 
     # Verify write tools are present
+    # Write-only token has: notes:write, calendar:write, contacts:write,
+    # cookbook:write, deck:write, tables:write, files:write, sharing:write
     expected_write_tools = [
-        "nc_notes_create_note",
-        "nc_notes_update_note",
-        "nc_notes_delete_note",
-        "nc_calendar_create_event",
-        "nc_calendar_update_event",
-        "nc_calendar_delete_event",
-        "nc_webdav_write_file",
-        "nc_webdav_create_directory",
+        "nc_notes_create_note",  # notes:write
+        "nc_notes_update_note",  # notes:write
+        "nc_notes_delete_note",  # notes:write
+        "nc_calendar_create_event",  # calendar:write
+        "nc_calendar_update_event",  # calendar:write
+        "nc_calendar_delete_event",  # calendar:write
     ]
 
     for tool in expected_write_tools:
         assert tool in tool_names, f"Expected write tool {tool} not found in tool list"
 
-    # Verify read tools are NOT present (write-only scope)
+    # Verify read-only tools are NOT present (write-only scope)
     read_tools_should_be_filtered = [
-        "nc_notes_get_note",
-        "nc_notes_search_notes",
-        "nc_calendar_list_calendars",
-        "nc_calendar_get_event",
-        "nc_webdav_list_directory",
-        "nc_webdav_read_file",
+        "nc_notes_get_note",  # notes:read
+        "nc_notes_search_notes",  # notes:read
+        "nc_calendar_list_calendars",  # calendar:read
+        "nc_calendar_get_event",  # calendar:read
     ]
 
     for tool in read_tools_should_be_filtered:
@@ -158,31 +157,31 @@ async def test_write_only_token_filters_read_tools(nc_mcp_oauth_client_write_onl
 
 @pytest.mark.integration
 async def test_full_access_token_shows_all_tools(nc_mcp_oauth_client_full_access):
-    """Test that a token with both nc:read and nc:write scopes can see all tools."""
+    """Test that a token with both read and write scopes scopes can see all tools."""
     import logging
 
     logger = logging.getLogger(__name__)
 
-    # Connect with token that has both "nc:read" and "nc:write" scopes
+    # Connect with token that has both "notes:read" and "notes:write" scopes
     result = await nc_mcp_oauth_client_full_access.list_tools()
     assert result is not None
     assert len(result.tools) > 0
 
     tool_names = [tool.name for tool in result.tools]
     logger.info(f"Full access token sees {len(tool_names)} tools")
+    logger.info(f"Tools: {sorted(tool_names)}")
 
     # Verify both read and write tools are present
+    # Full access has all *read and *write scopes
     expected_read_tools = [
-        "nc_notes_get_note",
-        "nc_notes_search_notes",
-        "nc_calendar_list_calendars",
-        "nc_webdav_read_file",
+        "nc_notes_get_note",  # notes:read
+        "nc_notes_search_notes",  # notes:read
+        "nc_calendar_list_calendars",  # calendar:read
     ]
 
     expected_write_tools = [
-        "nc_notes_create_note",
-        "nc_calendar_create_event",
-        "nc_webdav_write_file",
+        "nc_notes_create_note",  # notes:write
+        "nc_calendar_create_event",  # calendar:write
     ]
 
     for tool in expected_read_tools:
@@ -215,17 +214,17 @@ async def test_scope_helper_functions():
         pass
 
     # Add scope metadata
-    mock_read_tool._required_scopes = ["nc:read"]  # type: ignore
-    mock_write_tool._required_scopes = ["nc:write"]  # type: ignore
+    mock_read_tool._required_scopes = ["notes:read"]  # type: ignore
+    mock_write_tool._required_scopes = ["notes:write"]  # type: ignore
 
     # Test get_required_scopes
-    assert get_required_scopes(mock_read_tool) == ["nc:read"]
-    assert get_required_scopes(mock_write_tool) == ["nc:write"]
+    assert get_required_scopes(mock_read_tool) == ["notes:read"]
+    assert get_required_scopes(mock_write_tool) == ["notes:write"]
     assert get_required_scopes(mock_no_scope_tool) == []
 
     # Test has_required_scopes
-    read_only_scopes = {"nc:read"}
-    full_scopes = {"nc:read", "nc:write"}
+    read_only_scopes = {"notes:read"}
+    full_scopes = {"notes:read", "notes:write"}
     no_scopes = set()
 
     # User with only read scope
@@ -249,13 +248,13 @@ async def test_scope_decorator_stores_metadata():
     """Test that @require_scopes decorator properly stores metadata."""
     from nextcloud_mcp_server.auth import require_scopes
 
-    @require_scopes("nc:read", "nc:write")
+    @require_scopes("notes:read", "notes:write")
     async def test_function():
         pass
 
     # Check that metadata was stored
     assert hasattr(test_function, "_required_scopes")
-    assert test_function._required_scopes == ["nc:read", "nc:write"]
+    assert test_function._required_scopes == ["notes:read", "notes:write"]
 
 
 @pytest.mark.integration
@@ -299,36 +298,38 @@ async def test_tools_have_scope_decorators(nc_mcp_client):
         assert tool in tool_names, f"Expected write tool {tool} not found"
 
 
+@pytest.mark.skip(reason="Script no longer exists - decorators are already in place")
 @pytest.mark.integration
 async def test_scope_classification():
     """Test that our scope classification correctly identifies read vs write operations."""
     from scripts.add_scope_decorators_simple import classify_function
 
     # Test read operations
-    assert classify_function("nc_notes_get_note") == "nc:read"
-    assert classify_function("nc_notes_search_notes") == "nc:read"
-    assert classify_function("nc_calendar_list_events") == "nc:read"
-    assert classify_function("nc_webdav_read_file") == "nc:read"
-    assert classify_function("nc_calendar_find_availability") == "nc:read"
-    assert classify_function("nc_calendar_get_upcoming_events") == "nc:read"
+    assert classify_function("nc_notes_get_note") == "notes:read"
+    assert classify_function("nc_notes_search_notes") == "notes:read"
+    assert classify_function("nc_calendar_list_events") == "calendar:read"
+    assert classify_function("nc_webdav_read_file") == "files:read"
+    assert classify_function("nc_calendar_find_availability") == "calendar:read"
+    assert classify_function("nc_calendar_get_upcoming_events") == "notes:read"
 
     # Test write operations
-    assert classify_function("nc_notes_create_note") == "nc:write"
-    assert classify_function("nc_notes_update_note") == "nc:write"
-    assert classify_function("nc_notes_delete_note") == "nc:write"
-    assert classify_function("nc_notes_append_content") == "nc:write"
-    assert classify_function("nc_calendar_create_event") == "nc:write"
-    assert classify_function("nc_calendar_update_event") == "nc:write"
-    assert classify_function("nc_calendar_manage_calendar") == "nc:write"
-    assert classify_function("nc_webdav_write_file") == "nc:write"
-    assert classify_function("nc_webdav_move_resource") == "nc:write"
-    assert classify_function("nc_contacts_create_contact") == "nc:write"
-    assert classify_function("nc_cookbook_import_recipe") == "nc:write"
-    assert classify_function("nc_tables_insert_row") == "nc:write"
-    assert classify_function("deck_archive_card") == "nc:write"
-    assert classify_function("deck_assign_label_to_card") == "nc:write"
+    assert classify_function("nc_notes_create_note") == "notes:write"
+    assert classify_function("nc_notes_update_note") == "notes:write"
+    assert classify_function("nc_notes_delete_note") == "notes:write"
+    assert classify_function("nc_notes_append_content") == "notes:write"
+    assert classify_function("nc_calendar_create_event") == "calendar:write"
+    assert classify_function("nc_calendar_update_event") == "notes:write"
+    assert classify_function("nc_calendar_manage_calendar") == "notes:write"
+    assert classify_function("nc_webdav_write_file") == "files:write"
+    assert classify_function("nc_webdav_move_resource") == "notes:write"
+    assert classify_function("nc_contacts_create_contact") == "notes:write"
+    assert classify_function("nc_cookbook_import_recipe") == "notes:write"
+    assert classify_function("nc_tables_insert_row") == "notes:write"
+    assert classify_function("deck_archive_card") == "notes:write"
+    assert classify_function("deck_assign_label_to_card") == "notes:write"
 
 
+@pytest.mark.skip(reason="Script no longer exists - decorators are already in place")
 @pytest.mark.integration
 async def test_all_tools_classified():
     """Verify that all tools can be properly classified as read or write."""

tests/server/test_cookbook_mcp.py

@@ -1,8 +1,8 @@
-import asyncio
 import json
 import logging
 import uuid
 
+import anyio
 import pytest
 from mcp import ClientSession
 
@@ -136,7 +136,7 @@ async def test_mcp_cookbook_update_recipe(
         )
 
         # 4. Verify update via direct NextcloudClient
-        await asyncio.sleep(1)  # Allow propagation
+        await anyio.sleep(1)  # Allow propagation
         updated_recipe = await nc_client.cookbook.get_recipe(created_recipe_id)
         assert updated_recipe["description"] == "Updated via MCP"
         assert len(updated_recipe["recipeIngredient"]) == 2
@@ -282,7 +282,7 @@ async def test_mcp_cookbook_search_recipes(
         created_recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
 
         # 2. Allow time for indexing
-        await asyncio.sleep(2)
+        await anyio.sleep(2)
 
         # 3. Search for the recipe via MCP
         logger.info(f"Searching for recipes via MCP with keyword: {unique_keyword}")
@@ -358,7 +358,7 @@ async def test_mcp_cookbook_categories_workflow(
         created_recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
 
         # 2. Allow time for indexing
-        await asyncio.sleep(2)
+        await anyio.sleep(2)
 
         # 3. List categories via MCP
         logger.info("Listing categories via MCP")
@@ -433,9 +433,9 @@ async def test_mcp_cookbook_keywords_workflow(
         created_recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
 
         # 2. Allow extra time for indexing and trigger reindex
-        await asyncio.sleep(3)
+        await anyio.sleep(3)
         await nc_client.cookbook.reindex()
-        await asyncio.sleep(2)
+        await anyio.sleep(2)
 
         # 3. List keywords via MCP
         logger.info("Listing keywords via MCP")

tests/server/test_jwt_tokens.py

@@ -1,208 +0,0 @@
-"""
-Test JWT token structure and scope support.
-
-This test obtains a JWT token via OAuth and examines its structure.
-"""
-
-import base64
-import json
-
-import pytest
-
-
-def decode_jwt_without_verification(token: str) -> dict:
-    """
-    Decode JWT token without signature verification (for inspection only).
-
-    Returns:
-        Dict with header and payload
-    """
-    parts = token.split(".")
-    if len(parts) != 3:
-        raise ValueError(f"Invalid JWT format: expected 3 parts, got {len(parts)}")
-
-    # Decode header
-    header = json.loads(
-        base64.urlsafe_b64decode(parts[0] + "=" * (4 - len(parts[0]) % 4))
-    )
-
-    # Decode payload
-    payload = json.loads(
-        base64.urlsafe_b64decode(parts[1] + "=" * (4 - len(parts[1]) % 4))
-    )
-
-    return {
-        "header": header,
-        "payload": payload,
-    }
-
-
-@pytest.mark.integration
-async def test_jwt_token_structure_with_custom_client():
-    """
-    Test that we can create a JWT-enabled OAuth client and examine the token structure.
-
-    This test manually configures a JWT client and obtains a token.
-    """
-    import os
-
-    import httpx
-
-    # This test requires manual setup of a JWT client
-    # Skip if not configured
-    client_id = os.getenv("NEXTCLOUD_JWT_CLIENT_ID")
-    if not client_id:
-        pytest.skip("NEXTCLOUD_JWT_CLIENT_ID not set - skipping JWT token test")
-
-    _client_secret = os.getenv("NEXTCLOUD_JWT_CLIENT_SECRET")
-    nextcloud_host = os.getenv("NEXTCLOUD_HOST", "http://localhost:8080")
-
-    # Fetch discovery
-    async with httpx.AsyncClient() as client:
-        discovery_response = await client.get(
-            f"{nextcloud_host}/.well-known/openid-configuration"
-        )
-        discovery_response.raise_for_status()
-        discovery = discovery_response.json()
-
-    _token_endpoint = discovery["token_endpoint"]
-
-    # For this test, we'll use client credentials grant if supported
-    # Otherwise, skip this test
-    pytest.skip(
-        "JWT token test requires OAuth flow - use manual testing script instead"
-    )
-
-
-@pytest.mark.integration
-async def test_opaque_token_vs_jwt_comparison():
-    """
-    Compare opaque tokens vs JWT tokens to understand the differences.
-
-    This is a documentation test that explains the findings.
-    """
-    # This test documents our findings about JWT vs opaque tokens
-    # Based on manual testing with the test script
-
-    findings = {
-        "oidc_app_capabilities": {
-            "supports_jwt_tokens": True,
-            "supports_opaque_tokens": True,
-            "configuration_method": "per-client via token_type field",
-            "jwt_standard": "RFC 9068 (OAuth 2.0 Access Token JWT Profile)",
-        },
-        "dynamic_registration": {
-            "sets_allowed_scopes": False,
-            "note": "Dynamic registration does NOT populate allowed_scopes from the scope parameter in registration request",
-            "workaround": "Must use occ oidc:create with --allowed_scopes flag or manually update via web UI/API",
-        },
-        "jwt_token_structure": {
-            "header": {
-                "typ": "at+JWT",  # RFC 9068 access token type
-                "alg": "RS256",  # Signature algorithm
-            },
-            "payload_claims": {
-                "iss": "issuer URL",
-                "sub": "user ID",
-                "aud": "client ID",
-                "exp": "expiration timestamp",
-                "iat": "issued at timestamp",
-                "scope": "space-separated scope string (THIS IS THE KEY!)",
-                "client_id": "client identifier",
-                "jti": "JWT ID",
-                # Optional based on scopes:
-                "roles": "if roles scope present",
-                "groups": "if groups scope present",
-                "email": "if email scope present",
-                "name": "if profile scope present",
-            },
-            "scope_claim": {
-                "format": "space-separated string",
-                "example": "openid profile email nc:read nc:write",
-                "extraction": "payload['scope'].split()",
-            },
-        },
-        "scope_validation": {
-            "oidc_app": {
-                "validates": True,
-                "method": "Intersects requested scopes with allowed_scopes per client",
-                "location": "LoginRedirectorController.php:251-267",
-            },
-            "user_oidc_app": {
-                "validates_scopes": False,
-                "validates": ["token expiration", "issuer", "audience (optional)"],
-                "limitation": "Does NOT extract or validate scopes from JWT",
-            },
-        },
-        "token_size": {
-            "opaque": "72 characters",
-            "jwt": "~800-1200 characters (depends on claims)",
-            "overhead": "JWT is 10-15x larger than opaque tokens",
-        },
-        "recommendation": {
-            "for_mcp_server": "Use JWT tokens with self-validation",
-            "reasoning": [
-                "Can extract scopes directly from token payload",
-                "No additional API call needed",
-                "Standard approach (RFC 9068)",
-                "Works with existing oidc app",
-            ],
-            "alternative": "Implement introspection endpoint in oidc app (future work)",
-        },
-    }
-
-    # Print findings for documentation
-    print("\n" + "=" * 80)
-    print("JWT Token vs Opaque Token Findings")
-    print("=" * 80)
-    print(json.dumps(findings, indent=2))
-    print("=" * 80 + "\n")
-
-    # This test always passes - it's for documentation
-    assert True, "Findings documented"
-
-
-@pytest.mark.integration
-async def test_scope_presence_in_jwt():
-    """
-    Verify that custom scopes (nc:read, nc:write) are present in JWT tokens.
-
-    NOTE: This test documents the expected behavior based on manual testing.
-    Actual implementation will be tested in integration tests after JWT validation is implemented.
-    """
-    expected_behavior = {
-        "client_configuration": {
-            "allowed_scopes": "openid profile email nc:read nc:write",
-            "token_type": "jwt",
-        },
-        "authorization_request": {
-            "scope": "openid profile email nc:read nc:write",
-        },
-        "token_response": {
-            "access_token": "JWT with scope claim",
-        },
-        "jwt_payload": {
-            "scope": "openid profile email nc:read nc:write",  # All requested scopes present if in allowed_scopes
-        },
-        "scope_filtering": {
-            "description": "oidc app filters requested scopes against allowed_scopes",
-            "example": {
-                "requested": "openid profile nc:read nc:write nc:admin",
-                "allowed": "openid profile email nc:read nc:write",
-                "granted": "openid profile nc:read nc:write",  # nc:admin filtered out, email not requested
-            },
-        },
-    }
-
-    print("\n" + "=" * 80)
-    print("Expected JWT Scope Behavior")
-    print("=" * 80)
-    print(json.dumps(expected_behavior, indent=2))
-    print("=" * 80 + "\n")
-
-    assert True, "Expected behavior documented"
-
-
-if __name__ == "__main__":
-    # Run with: uv run pytest tests/server/test_jwt_tokens.py -v
-    pytest.main([__file__, "-v", "-s"])

tests/server/test_mcp.py

@@ -470,16 +470,21 @@ async def test_mcp_webdav_workflow(
         logger.info(f"Directory listing response: {listing_text}")
         listing_data = json.loads(listing_text)
 
-        # Ensure listing_data is a list
-        if not isinstance(listing_data, list):
-            logger.warning(
-                f"Expected directory listing to be a list, got: {type(listing_data)}"
-            )
-            listing_data = [listing_data] if listing_data else []
+        # Extract files from DirectoryListing response
+        assert "files" in listing_data, "Expected 'files' field in directory listing"
+        files = listing_data["files"]
+        assert isinstance(files, list), (
+            f"Expected files to be a list, got: {type(files)}"
+        )
+
+        # Verify metadata
+        assert listing_data["path"] == test_dir
+        assert listing_data["total_count"] >= 1
+        assert listing_data["files_count"] >= 1
 
         # Find our file in the listing
         found_file = None
-        for item in listing_data:
+        for item in files:
             if isinstance(item, dict) and item.get("name") == test_file:
                 found_file = item
                 break

tests/server/test_mcp_oauth.py

@@ -1,60 +0,0 @@
-import json
-import logging
-
-import pytest
-
-logger = logging.getLogger(__name__)
-
-pytestmark = [pytest.mark.integration, pytest.mark.oauth]
-
-
-async def test_mcp_oauth_server_connection(nc_mcp_oauth_client):
-    """Test connection to OAuth-enabled MCP server."""
-    result = await nc_mcp_oauth_client.list_tools()
-    assert result is not None
-    assert len(result.tools) > 0
-
-    logger.info(f"OAuth MCP server has {len(result.tools)} tools available")
-
-
-async def test_mcp_oauth_tool_execution(nc_mcp_oauth_client):
-    """Test executing a tool on the OAuth-enabled MCP server."""
-    import json
-
-    # Example: Execute the 'nc_notes_search_notes' tool
-    result = await nc_mcp_oauth_client.call_tool(
-        "nc_notes_search_notes", arguments={"query": ""}
-    )
-
-    assert result.isError is False, f"Tool execution failed: {result.content}"
-    assert result.content is not None
-    response_data = json.loads(result.content[0].text)
-
-    # The search response should have a 'results' field containing the list
-    assert "results" in response_data
-    assert isinstance(response_data["results"], list)
-
-    logger.info(
-        f"Successfully executed 'nc_notes_search_notes' tool on OAuth MCP server and got {len(response_data['results'])} notes."
-    )
-
-
-async def test_mcp_oauth_client_with_playwright(nc_mcp_oauth_client):
-    """Test that MCP OAuth client via Playwright can execute tools."""
-
-    # Test: Execute the 'nc_notes_search_notes' tool
-    result = await nc_mcp_oauth_client.call_tool(
-        "nc_notes_search_notes", arguments={"query": ""}
-    )
-
-    assert result.isError is False, f"Tool execution failed: {result.content}"
-    assert result.content is not None
-    response_data = json.loads(result.content[0].text)
-
-    # The search response should have a 'results' field containing the list
-    assert "results" in response_data
-    assert isinstance(response_data["results"], list)
-
-    logger.info(
-        f"Successfully executed 'nc_notes_search_notes' tool on Playwright OAuth MCP server and got {len(response_data['results'])} notes."
-    )

tests/server/test_mcp_oauth_jwt.py

@@ -1,246 +0,0 @@
-"""Integration tests for JWT OAuth authentication.
-
-These tests verify:
-1. JWT token authentication works correctly
-2. JWT token verification via JWKS
-3. Scope information is properly extracted from JWT claims
-4. Dynamic tool filtering works with JWT tokens
-5. All MCP operations work with JWT authentication
-"""
-
-import json
-import logging
-
-import pytest
-
-logger = logging.getLogger(__name__)
-
-pytestmark = [pytest.mark.integration, pytest.mark.oauth]
-
-
-async def test_jwt_mcp_server_connection(nc_mcp_oauth_jwt_client):
-    """Test connection to JWT OAuth-enabled MCP server."""
-    result = await nc_mcp_oauth_jwt_client.list_tools()
-    assert result is not None
-    assert len(result.tools) > 0
-
-    logger.info(f"JWT OAuth MCP server has {len(result.tools)} tools available")
-
-
-async def test_jwt_token_authentication(nc_mcp_oauth_jwt_client):
-    """Test that JWT token authentication works."""
-    # Execute a simple read operation
-    result = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_search_notes", arguments={"query": ""}
-    )
-
-    assert result.isError is False, f"Tool execution failed: {result.content}"
-    assert result.content is not None
-    response_data = json.loads(result.content[0].text)
-
-    assert "results" in response_data
-    assert isinstance(response_data["results"], list)
-
-    logger.info(
-        f"Successfully authenticated with JWT token and executed tool, got {len(response_data['results'])} notes."
-    )
-
-
-async def test_jwt_tool_list_operations(nc_mcp_oauth_jwt_client):
-    """Test that list_tools works with JWT authentication."""
-    result = await nc_mcp_oauth_jwt_client.list_tools()
-
-    # Verify we have tools
-    assert len(result.tools) > 0
-
-    # Verify some expected tools exist
-    tool_names = [tool.name for tool in result.tools]
-    assert "nc_notes_get_note" in tool_names
-    assert "nc_notes_create_note" in tool_names
-    assert "nc_calendar_list_calendars" in tool_names
-    assert "nc_webdav_list_directory" in tool_names
-
-    logger.info(f"JWT server provides {len(result.tools)} tools")
-
-
-async def test_jwt_read_operation(nc_mcp_oauth_jwt_client):
-    """Test read operation with JWT authentication."""
-    # List calendars (read operation)
-    result = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_calendar_list_calendars", arguments={}
-    )
-
-    assert result.isError is False, f"Tool execution failed: {result.content}"
-    assert result.content is not None
-    response_data = json.loads(result.content[0].text)
-
-    assert "calendars" in response_data
-    assert isinstance(response_data["calendars"], list)
-
-    logger.info(
-        f"Successfully executed read operation with JWT, got {len(response_data['calendars'])} calendars."
-    )
-
-
-async def test_jwt_write_operation(nc_mcp_oauth_jwt_client):
-    """Test write operation with JWT authentication."""
-    import uuid
-
-    # Create a note (write operation)
-    note_title = f"JWT Test Note {uuid.uuid4().hex[:8]}"
-    note_content = "This note was created during JWT authentication testing"
-
-    result = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_create_note",
-        arguments={
-            "title": note_title,
-            "content": note_content,
-            "category": "Testing",
-        },
-    )
-
-    assert result.isError is False, f"Tool execution failed: {result.content}"
-    assert result.content is not None
-    response_data = json.loads(result.content[0].text)
-
-    # Verify note was created
-    assert "id" in response_data
-    assert response_data["title"] == note_title
-
-    note_id = response_data["id"]
-    logger.info(f"Successfully created note {note_id} with JWT authentication")
-
-    # Clean up: Delete the note
-    delete_result = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_delete_note", arguments={"note_id": note_id}
-    )
-
-    assert delete_result.isError is False, f"Cleanup failed: {delete_result.content}"
-    logger.info(f"Cleaned up test note {note_id}")
-
-
-async def test_jwt_multiple_operations(nc_mcp_oauth_jwt_client):
-    """Test multiple operations with same JWT token to verify token persistence."""
-    # First operation: Search notes
-    result1 = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_search_notes", arguments={"query": ""}
-    )
-    assert result1.isError is False
-
-    # Second operation: List calendars
-    result2 = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_calendar_list_calendars", arguments={}
-    )
-    assert result2.isError is False
-
-    # Third operation: List directory
-    result3 = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_webdav_list_directory", arguments={"path": "/"}
-    )
-    assert result3.isError is False
-
-    logger.info("Successfully executed multiple operations with JWT token")
-
-
-async def test_jwt_vs_opaque_token_compatibility(
-    nc_mcp_oauth_client, nc_mcp_oauth_jwt_client
-):
-    """Verify that both opaque and JWT tokens provide same functionality."""
-    # Execute same operation on both servers
-    opaque_result = await nc_mcp_oauth_client.call_tool(
-        "nc_notes_search_notes", arguments={"query": ""}
-    )
-    jwt_result = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_search_notes", arguments={"query": ""}
-    )
-
-    # Both should succeed
-    assert opaque_result.isError is False
-    assert jwt_result.isError is False
-
-    # Both should have results
-    opaque_data = json.loads(opaque_result.content[0].text)
-    jwt_data = json.loads(jwt_result.content[0].text)
-
-    assert "results" in opaque_data
-    assert "results" in jwt_data
-
-    # Results should be the same (same user, same notes)
-    assert len(opaque_data["results"]) == len(jwt_data["results"])
-
-    logger.info(
-        "Verified opaque and JWT tokens provide identical functionality: "
-        f"{len(opaque_data['results'])} notes accessible from both servers"
-    )
-
-
-async def test_jwt_error_handling(nc_mcp_oauth_jwt_client):
-    """Test error handling with JWT authentication."""
-    # Try to get a non-existent note
-    result = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_get_note", arguments={"note_id": 999999}
-    )
-
-    # Should get an error (note doesn't exist)
-    assert result.isError is True
-    logger.info("JWT server correctly handles errors for invalid operations")
-
-
-async def test_jwt_scope_enforcement(nc_mcp_oauth_jwt_client):
-    """Test that JWT server properly enforces scopes."""
-    # This test assumes the JWT token has both nc:read and nc:write scopes
-    # Both read and write operations should succeed
-
-    # Read operation
-    read_result = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_search_notes", arguments={"query": ""}
-    )
-    assert read_result.isError is False
-
-    # Write operation
-    import uuid
-
-    note_title = f"Scope Test {uuid.uuid4().hex[:8]}"
-    write_result = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_create_note",
-        arguments={
-            "title": note_title,
-            "content": "Testing scope enforcement",
-            "category": "Testing",
-        },
-    )
-    assert write_result.isError is False
-
-    # Clean up
-    note_id = json.loads(write_result.content[0].text)["id"]
-    await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_delete_note", arguments={"note_id": note_id}
-    )
-
-    logger.info("JWT server properly allows operations based on token scopes")
-
-
-async def test_jwt_automation_worked(nc_mcp_oauth_jwt_client):
-    """Test that verifies the automated JWT client creation worked correctly.
-
-    This test confirms that:
-    1. JWT client was auto-created during container initialization
-    2. MCP server loaded credentials from auto-generated file
-    3. JWT authentication flow works end-to-end
-    4. Server uses JWT tokens (not opaque tokens)
-    """
-    # If we can connect and execute tools, the automation worked
-    result = await nc_mcp_oauth_jwt_client.list_tools()
-    assert result is not None
-    assert len(result.tools) > 0
-
-    # Execute a tool to verify full OAuth flow
-    tool_result = await nc_mcp_oauth_jwt_client.call_tool(
-        "nc_notes_search_notes", arguments={"query": ""}
-    )
-    assert tool_result.isError is False
-
-    logger.info(
-        "✅ JWT client automation successful! "
-        "Auto-generated credentials working correctly."
-    )

tests/server/test_users_api.py

@@ -2,8 +2,9 @@ import pytest
 
 from nextcloud_mcp_server.client import NextcloudClient
 
+pytestmark = pytest.mark.integration
+
 
-@pytest.mark.anyio
 async def test_create_and_delete_user(nc_client: NextcloudClient, test_user):
     """Test creating a user and verifying deletion (cleanup by fixture)."""
     user_config = test_user
@@ -29,7 +30,6 @@ async def test_create_and_delete_user(nc_client: NextcloudClient, test_user):
     # Note: Fixture cleanup will also try to delete but handle 404 gracefully
 
 
-@pytest.mark.anyio
 async def test_update_user_field(nc_client: NextcloudClient, test_user):
     """Test updating user fields."""
     user_config = test_user
@@ -44,7 +44,6 @@ async def test_update_user_field(nc_client: NextcloudClient, test_user):
     # Fixture will handle cleanup
 
 
-@pytest.mark.anyio
 async def test_user_groups(nc_client: NextcloudClient, test_user_in_group):
     """Test adding and removing users from groups."""
     user_config, groupid = test_user_in_group
@@ -61,7 +60,6 @@ async def test_user_groups(nc_client: NextcloudClient, test_user_in_group):
     # Fixtures will handle cleanup
 
 
-@pytest.mark.anyio
 async def test_user_subadmins(nc_client: NextcloudClient, test_user, test_group):
     """Test promoting and demoting subadmins."""
     user_config = test_user
@@ -82,7 +80,6 @@ async def test_user_subadmins(nc_client: NextcloudClient, test_user, test_group)
     # Fixtures will handle cleanup
 
 
-@pytest.mark.anyio
 async def test_disable_enable_user(nc_client: NextcloudClient, test_user):
     """Test disabling and enabling users."""
     user_config = test_user
@@ -102,7 +99,6 @@ async def test_disable_enable_user(nc_client: NextcloudClient, test_user):
     # Fixture will handle cleanup
 
 
-@pytest.mark.anyio
 async def test_get_editable_user_fields(nc_client: NextcloudClient):
     editable_fields = await nc_client.users.get_editable_user_fields()
     assert "displayname" in editable_fields

tests/smoke/__init__.py

@@ -0,0 +1 @@
+"""Critical path smoke tests for quick validation."""

tests/smoke/test_smoke.py

@@ -0,0 +1,120 @@
+"""Smoke tests - critical path tests for quick validation.
+
+These tests verify the most essential functionality:
+- MCP server connectivity
+- Basic CRUD operations for core apps
+- OAuth authentication
+- Tool schema validation
+
+Run with: uv run pytest -m smoke -v
+Expected runtime: ~30-60 seconds
+"""
+
+import json
+
+import pytest
+
+pytestmark = [pytest.mark.integration, pytest.mark.smoke]
+
+
+async def test_mcp_connectivity_smoke(nc_mcp_client):
+    """Smoke test: Verify MCP server is reachable and lists tools."""
+    tools = await nc_mcp_client.list_tools()
+
+    # Should have a reasonable number of tools
+    assert len(tools.tools) > 30, f"Expected >30 tools, got {len(tools.tools)}"
+
+    # Check for core tool categories
+    tool_names = [tool.name for tool in tools.tools]
+    assert any("notes" in name for name in tool_names), "Missing notes tools"
+    assert any("calendar" in name for name in tool_names), "Missing calendar tools"
+    assert any("webdav" in name for name in tool_names), "Missing webdav tools"
+
+
+async def test_notes_crud_smoke(nc_mcp_client, nc_client):
+    """Smoke test: Verify basic Notes CRUD operations work."""
+    # Create
+    create_result = await nc_mcp_client.call_tool(
+        "nc_notes_create_note",
+        arguments={
+            "title": "Smoke Test Note",
+            "content": "Testing basic CRUD",
+            "category": "test",
+        },
+    )
+    assert create_result.isError is False
+    data = json.loads(create_result.content[0].text)
+    note_id = data["id"]
+
+    try:
+        # Read
+        get_result = await nc_mcp_client.call_tool(
+            "nc_notes_get_note",
+            arguments={"note_id": note_id},
+        )
+        assert get_result.isError is False
+
+        # Update
+        update_result = await nc_mcp_client.call_tool(
+            "nc_notes_update_note",
+            arguments={
+                "note_id": note_id,
+                "title": "Updated Smoke Test",
+                "content": "Updated content",
+                "category": "test",
+                "etag": data["etag"],
+            },
+        )
+        assert update_result.isError is False
+
+    finally:
+        # Delete
+        delete_result = await nc_mcp_client.call_tool(
+            "nc_notes_delete_note",
+            arguments={"note_id": note_id},
+        )
+        assert delete_result.isError is False
+
+
+async def test_calendar_basic_smoke(nc_mcp_client):
+    """Smoke test: Verify calendar operations work."""
+    # List calendars
+    result = await nc_mcp_client.call_tool(
+        "nc_calendar_list_calendars",
+        arguments={},
+    )
+    assert result.isError is False
+
+    data = json.loads(result.content[0].text)
+    assert "calendars" in data
+    assert len(data["calendars"]) > 0
+
+
+async def test_webdav_basic_smoke(nc_mcp_client):
+    """Smoke test: Verify WebDAV file operations work."""
+    # List root directory
+    result = await nc_mcp_client.call_tool(
+        "nc_webdav_list_directory",
+        arguments={"path": "/"},
+    )
+    assert result.isError is False
+
+    data = json.loads(result.content[0].text)
+    assert "files" in data
+    assert isinstance(data["files"], list)
+
+
+@pytest.mark.oauth
+async def test_oauth_connectivity_smoke(nc_mcp_oauth_client):
+    """Smoke test: Verify OAuth authentication works."""
+    # List tools with OAuth
+    result = await nc_mcp_oauth_client.list_tools()
+    assert result is not None
+    assert len(result.tools) > 0
+
+    # Execute a simple tool
+    search_result = await nc_mcp_oauth_client.call_tool(
+        "nc_notes_search_notes",
+        arguments={"query": ""},
+    )
+    assert search_result.isError is False

tests/test_cli.py

@@ -253,8 +253,17 @@ def test_default_values(runner, clean_env, monkeypatch):
     _ = runner.invoke(run, [])
 
     # Verify default values
-    assert (
-        captured_env["NEXTCLOUD_OIDC_SCOPES"] == "openid profile email nc:read nc:write"
+    assert captured_env["NEXTCLOUD_OIDC_SCOPES"] == (
+        "openid profile email "
+        "notes:read notes:write "
+        "calendar:read calendar:write "
+        "todo:read todo:write "
+        "contacts:read contacts:write "
+        "cookbook:read cookbook:write "
+        "deck:read deck:write "
+        "tables:read tables:write "
+        "files:read files:write "
+        "sharing:read sharing:write"
     )
     assert captured_env["NEXTCLOUD_OIDC_TOKEN_TYPE"] == "bearer"
     assert captured_env["NEXTCLOUD_MCP_SERVER_URL"] == "http://localhost:8000"

tests/unit/__init__.py

@@ -0,0 +1 @@
+"""Unit tests with mocked dependencies for fast feedback."""

tests/unit/test_document_processor_config.py

@@ -0,0 +1,136 @@
+"""Unit tests for document processor configuration."""
+
+import os
+
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+class TestDocumentProcessorConfig:
+    """Test document processor configuration system."""
+
+    def test_config_disabled_by_default(self):
+        """Test that document processing is disabled by default."""
+        from nextcloud_mcp_server.config import get_document_processor_config
+
+        os.environ.pop("ENABLE_DOCUMENT_PROCESSING", None)
+        config = get_document_processor_config()
+        assert config["enabled"] is False
+
+    def test_config_enabled(self):
+        """Test enabling document processing."""
+        from nextcloud_mcp_server.config import get_document_processor_config
+
+        os.environ["ENABLE_DOCUMENT_PROCESSING"] = "true"
+        try:
+            config = get_document_processor_config()
+            assert config["enabled"] is True
+        finally:
+            os.environ.pop("ENABLE_DOCUMENT_PROCESSING", None)
+
+    def test_unstructured_processor_config(self):
+        """Test Unstructured processor configuration."""
+        from nextcloud_mcp_server.config import get_document_processor_config
+
+        os.environ["ENABLE_UNSTRUCTURED"] = "true"
+        os.environ["UNSTRUCTURED_API_URL"] = "http://test:8000"
+        os.environ["UNSTRUCTURED_STRATEGY"] = "hi_res"
+        os.environ["UNSTRUCTURED_LANGUAGES"] = "eng,fra"
+        os.environ["UNSTRUCTURED_TIMEOUT"] = "60"
+
+        try:
+            config = get_document_processor_config()
+            assert "unstructured" in config["processors"]
+            unst_config = config["processors"]["unstructured"]
+            assert unst_config["api_url"] == "http://test:8000"
+            assert unst_config["strategy"] == "hi_res"
+            assert unst_config["languages"] == ["eng", "fra"]
+            assert unst_config["timeout"] == 60
+        finally:
+            os.environ.pop("ENABLE_UNSTRUCTURED", None)
+            os.environ.pop("UNSTRUCTURED_API_URL", None)
+            os.environ.pop("UNSTRUCTURED_STRATEGY", None)
+            os.environ.pop("UNSTRUCTURED_LANGUAGES", None)
+            os.environ.pop("UNSTRUCTURED_TIMEOUT", None)
+
+    def test_tesseract_processor_config(self):
+        """Test Tesseract processor configuration."""
+        from nextcloud_mcp_server.config import get_document_processor_config
+
+        os.environ["ENABLE_TESSERACT"] = "true"
+        os.environ["TESSERACT_LANG"] = "eng+deu"
+        os.environ["TESSERACT_CMD"] = "/usr/local/bin/tesseract"
+
+        try:
+            config = get_document_processor_config()
+            assert "tesseract" in config["processors"]
+            tess_config = config["processors"]["tesseract"]
+            assert tess_config["lang"] == "eng+deu"
+            assert tess_config["tesseract_cmd"] == "/usr/local/bin/tesseract"
+        finally:
+            os.environ.pop("ENABLE_TESSERACT", None)
+            os.environ.pop("TESSERACT_LANG", None)
+            os.environ.pop("TESSERACT_CMD", None)
+
+    def test_custom_processor_config(self):
+        """Test custom processor configuration."""
+        from nextcloud_mcp_server.config import get_document_processor_config
+
+        os.environ["ENABLE_CUSTOM_PROCESSOR"] = "true"
+        os.environ["CUSTOM_PROCESSOR_NAME"] = "my_ocr"
+        os.environ["CUSTOM_PROCESSOR_URL"] = "http://localhost:9000/process"
+        os.environ["CUSTOM_PROCESSOR_API_KEY"] = "secret"
+        os.environ["CUSTOM_PROCESSOR_TIMEOUT"] = "30"
+        os.environ["CUSTOM_PROCESSOR_TYPES"] = "application/pdf,image/jpeg"
+
+        try:
+            config = get_document_processor_config()
+            assert "custom" in config["processors"]
+            custom_config = config["processors"]["custom"]
+            assert custom_config["name"] == "my_ocr"
+            assert custom_config["api_url"] == "http://localhost:9000/process"
+            assert custom_config["api_key"] == "secret"
+            assert custom_config["timeout"] == 30
+            assert "application/pdf" in custom_config["supported_types"]
+            assert "image/jpeg" in custom_config["supported_types"]
+        finally:
+            os.environ.pop("ENABLE_CUSTOM_PROCESSOR", None)
+            os.environ.pop("CUSTOM_PROCESSOR_NAME", None)
+            os.environ.pop("CUSTOM_PROCESSOR_URL", None)
+            os.environ.pop("CUSTOM_PROCESSOR_API_KEY", None)
+            os.environ.pop("CUSTOM_PROCESSOR_TIMEOUT", None)
+            os.environ.pop("CUSTOM_PROCESSOR_TYPES", None)
+
+    def test_multiple_processors(self):
+        """Test configuration with multiple processors enabled."""
+        from nextcloud_mcp_server.config import get_document_processor_config
+
+        os.environ["ENABLE_DOCUMENT_PROCESSING"] = "true"
+        os.environ["ENABLE_UNSTRUCTURED"] = "true"
+        os.environ["ENABLE_TESSERACT"] = "true"
+
+        try:
+            config = get_document_processor_config()
+            assert config["enabled"] is True
+            assert "unstructured" in config["processors"]
+            assert "tesseract" in config["processors"]
+        finally:
+            os.environ.pop("ENABLE_DOCUMENT_PROCESSING", None)
+            os.environ.pop("ENABLE_UNSTRUCTURED", None)
+            os.environ.pop("ENABLE_TESSERACT", None)
+
+    def test_default_processor_selection(self):
+        """Test default processor configuration."""
+        from nextcloud_mcp_server.config import get_document_processor_config
+
+        os.environ.pop("DOCUMENT_PROCESSOR", None)
+        config = get_document_processor_config()
+        assert config["default_processor"] == "unstructured"
+
+        os.environ["DOCUMENT_PROCESSOR"] = "tesseract"
+        try:
+            config = get_document_processor_config()
+            assert config["default_processor"] == "tesseract"
+        finally:
+            os.environ.pop("DOCUMENT_PROCESSOR", None)

tests/unit/test_progress_notification.py

@@ -0,0 +1,164 @@
+"""Unit tests for progress notification system."""
+
+import time
+from unittest.mock import AsyncMock
+
+import anyio
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+class TestProgressNotification:
+    """Test progress notification in document processors."""
+
+    async def test_progress_callback_called_during_processing(self):
+        """Test that progress callback is called at intervals during processing."""
+        from nextcloud_mcp_server.document_processors.unstructured import (
+            UnstructuredProcessor,
+        )
+
+        # Mock progress callback to track calls
+        progress_callback = AsyncMock()
+
+        # Create processor with 1-second interval for faster testing
+        processor = UnstructuredProcessor(
+            api_url="http://test:8000",
+            timeout=10,
+            progress_interval=1,
+        )
+
+        # Create a mock event and start time
+        stop_event = anyio.Event()
+        start_time = time.time()
+
+        # Run the poller for 3 seconds, then stop it
+        async def stop_after_delay():
+            await anyio.sleep(3.5)
+            stop_event.set()
+
+        # Run poller and stopper concurrently
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(
+                processor._run_progress_poller,
+                stop_event,
+                progress_callback,
+                start_time,
+            )
+            tg.start_soon(stop_after_delay)
+
+        # Verify progress callback was called at least 3 times (1s, 2s, 3s)
+        assert progress_callback.call_count >= 3
+
+        # Verify each call had correct structure
+        for call in progress_callback.call_args_list:
+            # Calls are made with keyword arguments
+            assert "progress" in call.kwargs
+            assert "total" in call.kwargs
+            assert "message" in call.kwargs
+
+            progress = call.kwargs["progress"]
+            total = call.kwargs["total"]
+            message = call.kwargs["message"]
+
+            assert isinstance(progress, float)
+            assert total is None  # Unknown total for unstructured
+            assert "Processing document with unstructured" in message
+            assert "elapsed" in message
+
+    async def test_progress_poller_stops_when_event_set(self):
+        """Test that progress poller stops immediately when event is set."""
+        from nextcloud_mcp_server.document_processors.unstructured import (
+            UnstructuredProcessor,
+        )
+
+        progress_callback = AsyncMock()
+        processor = UnstructuredProcessor(
+            api_url="http://test:8000",
+            timeout=10,
+            progress_interval=10,  # Long interval
+        )
+
+        stop_event = anyio.Event()
+        start_time = time.time()
+
+        # Set event immediately
+        stop_event.set()
+
+        # Run poller
+        await processor._run_progress_poller(stop_event, progress_callback, start_time)
+
+        # Should not call progress callback since event was already set
+        assert progress_callback.call_count == 0
+
+    async def test_progress_callback_exception_handled(self):
+        """Test that exceptions in progress callback don't crash the poller."""
+        from nextcloud_mcp_server.document_processors.unstructured import (
+            UnstructuredProcessor,
+        )
+
+        # Mock callback that raises exception
+        progress_callback = AsyncMock(side_effect=Exception("Callback error"))
+
+        processor = UnstructuredProcessor(
+            api_url="http://test:8000",
+            timeout=10,
+            progress_interval=1,
+        )
+
+        stop_event = anyio.Event()
+        start_time = time.time()
+
+        # Run poller for 2 seconds
+        async def stop_after_delay():
+            await anyio.sleep(2.5)
+            stop_event.set()
+
+        # Should not raise exception even though callback fails
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(
+                processor._run_progress_poller,
+                stop_event,
+                progress_callback,
+                start_time,
+            )
+            tg.start_soon(stop_after_delay)
+
+        # Callback should have been called (and failed) at least twice
+        assert progress_callback.call_count >= 2
+
+    async def test_process_without_progress_callback(self):
+        """Test that processing works without progress callback (backward compatibility)."""
+        from nextcloud_mcp_server.document_processors.unstructured import (
+            UnstructuredProcessor,
+        )
+
+        processor = UnstructuredProcessor(
+            api_url="http://test:8000",
+            timeout=10,
+            progress_interval=1,
+        )
+
+        # Mock the _make_api_request method to avoid actual HTTP call
+        from unittest.mock import patch
+
+        from nextcloud_mcp_server.document_processors.base import ProcessingResult
+
+        mock_result = ProcessingResult(
+            text="Test content",
+            metadata={"test": "data"},
+            processor="unstructured",
+            success=True,
+        )
+
+        with patch.object(
+            processor, "_make_api_request", return_value=mock_result
+        ) as mock_request:
+            # Call process without progress_callback
+            result = await processor.process(
+                content=b"test", content_type="application/pdf", progress_callback=None
+            )
+
+            # Should call _make_api_request directly
+            assert result == mock_result
+            mock_request.assert_called_once()

tests/unit/test_response_models.py

@@ -0,0 +1,123 @@
+"""Unit tests for Pydantic response models."""
+
+import pytest
+
+from nextcloud_mcp_server.models.notes import (
+    CreateNoteResponse,
+    Note,
+    NoteSearchResult,
+    SearchNotesResponse,
+)
+
+
+@pytest.mark.unit
+def test_note_model_creation():
+    """Test creating a Note model with required fields."""
+    note = Note(
+        id=123,
+        title="Test Note",
+        content="# Test Content",
+        modified=1700000000,
+        etag="abc123",
+    )
+
+    assert note.id == 123
+    assert note.title == "Test Note"
+    assert note.content == "# Test Content"
+    assert note.category == ""  # default value
+    assert note.favorite is False  # default value
+    assert note.etag == "abc123"
+
+
+@pytest.mark.unit
+def test_note_modified_datetime_property():
+    """Test that Note.modified_datetime converts Unix timestamp correctly."""
+    note = Note(
+        id=1,
+        title="Test",
+        content="Content",
+        modified=1700000000,
+        etag="etag",
+    )
+
+    dt = note.modified_datetime
+    assert dt.year == 2023  # Nov 14, 2023
+    assert dt.month == 11
+
+
+@pytest.mark.unit
+def test_create_note_response_serialization():
+    """Test CreateNoteResponse can serialize to JSON."""
+    response = CreateNoteResponse(
+        id=42,
+        title="New Note",
+        category="Work",
+        etag="xyz789",
+    )
+
+    # Test serialization
+    data = response.model_dump()
+    assert data["id"] == 42
+    assert data["title"] == "New Note"
+    assert data["category"] == "Work"
+    assert data["etag"] == "xyz789"
+
+
+@pytest.mark.unit
+def test_search_notes_response_wraps_results():
+    """Test SearchNotesResponse wraps list of results correctly.
+
+    This is critical - FastMCP mangles raw List[Dict] responses,
+    so we must wrap them in a response model.
+    """
+    results = [
+        NoteSearchResult(id=1, title="First Note", category="Work"),
+        NoteSearchResult(id=2, title="Second Note", category="Personal"),
+    ]
+
+    response = SearchNotesResponse(
+        results=results,
+        query="test query",
+        total_found=2,
+    )
+
+    # Verify the response structure
+    assert len(response.results) == 2
+    assert response.results[0].id == 1
+    assert response.results[1].title == "Second Note"
+    assert response.query == "test query"
+    assert response.total_found == 2
+
+    # Verify it serializes correctly
+    data = response.model_dump()
+    assert "results" in data
+    assert isinstance(data["results"], list)
+    assert len(data["results"]) == 2
+    assert data["results"][0]["id"] == 1
+
+
+@pytest.mark.unit
+def test_note_search_result_with_score():
+    """Test NoteSearchResult with optional score field."""
+    result = NoteSearchResult(
+        id=99,
+        title="Relevant Note",
+        category="Archive",
+        score=0.95,
+    )
+
+    assert result.id == 99
+    assert result.score == 0.95
+
+
+@pytest.mark.unit
+def test_note_search_result_without_score():
+    """Test NoteSearchResult without optional score field."""
+    result = NoteSearchResult(
+        id=99,
+        title="Relevant Note",
+        category="Archive",
+    )
+
+    assert result.id == 99
+    assert result.score is None

tests/unit/test_scope_decorator.py

@@ -0,0 +1,65 @@
+"""Unit tests for scope decorator metadata and classification logic."""
+
+import pytest
+
+from nextcloud_mcp_server.auth.scope_authorization import (
+    InsufficientScopeError,
+    require_scopes,
+)
+
+
+@pytest.mark.unit
+def test_scope_decorator_stores_metadata():
+    """Test that @require_scopes decorator stores scope requirements as function metadata."""
+
+    @require_scopes("notes:read", "notes:write")
+    async def example_function():
+        pass
+
+    # Verify metadata is stored
+    assert hasattr(example_function, "_required_scopes")
+    assert example_function._required_scopes == ["notes:read", "notes:write"]
+
+
+@pytest.mark.unit
+def test_scope_decorator_with_single_scope():
+    """Test decorator with a single scope requirement."""
+
+    @require_scopes("calendar:read")
+    async def example_function():
+        pass
+
+    assert example_function._required_scopes == ["calendar:read"]
+
+
+@pytest.mark.unit
+def test_scope_decorator_with_no_scopes():
+    """Test decorator with no scope requirements."""
+
+    @require_scopes()
+    async def example_function():
+        pass
+
+    assert example_function._required_scopes == []
+
+
+@pytest.mark.unit
+def test_insufficient_scope_error():
+    """Test InsufficientScopeError exception structure."""
+    missing = ["notes:write", "calendar:write"]
+    error = InsufficientScopeError(missing)
+
+    assert error.missing_scopes == missing
+    assert "notes:write" in str(error)
+    assert "calendar:write" in str(error)
+
+
+@pytest.mark.unit
+def test_insufficient_scope_error_with_custom_message():
+    """Test InsufficientScopeError with custom message."""
+    missing = ["files:write"]
+    custom_msg = "You need more permissions"
+    error = InsufficientScopeError(missing, custom_msg)
+
+    assert error.missing_scopes == missing
+    assert str(error) == custom_msg