Update index.yaml

Signed-off-by: cbcoutinho <cbcoutinho@users.noreply.github.com>

.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

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    # Environment and permissions trusted publishing.
+    environment:
+      # Create this environment in the GitHub repository under Settings -> Environments
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
+      - name: Install Python 3.11
+        run: uv python install 3.11
+      - name: Build
+        run: uv build
+      - name: Smoke test (wheel)
+        run: uv run --isolated --no-project --with dist/*.whl nextcloud-mcp-server --help
+      - name: Smoke test (source distribution)
+        run: uv run --isolated --no-project --with dist/*.tar.gz nextcloud-mcp-server --help
+      - name: Publish
+        run: uv publish

.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@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7.1.0
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
       - name: Check format
         run: |
           uv run --frozen ruff format --diff
@@ -25,6 +25,25 @@ jobs:
 
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          submodules: 'true'
+
+
+      ###### Required to build OIDC App ######
+
+      - name: Set up php 8.4
+        uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # v2
+        with:
+          php-version: 8.4
+          coverage: none
+
+      - name: Install OIDC app composer dependencies
+        run: |
+          cd third_party/oidc
+          composer install --no-dev
+
+      ###### Required to build OIDC App ######
+
 
       - name: Run docker compose
         uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
@@ -33,11 +52,11 @@ jobs:
           up-flags: "--build"
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7.1.0
+        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
 
       - name: Install Playwright dependencies
         run: |
-          uv run playwright install firefox --with-deps
+          uv run playwright install chromium --with-deps
 
       - name: Wait for service to be ready
         run: |
@@ -62,4 +81,4 @@ jobs:
           NEXTCLOUD_USERNAME: "admin"
           NEXTCLOUD_PASSWORD: "admin"
         run: |
-          uv run pytest -v --browser firefox
+          uv run pytest -v --log-cli-level=INFO

.gitignore

@@ -6,4 +6,4 @@ __pycache__/
 .env.*.local
 
 # Generated by pytest used to login users
-.nextcloud_oauth_shared_test_client.json
+.nextcloud_oauth_*.json

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "oidc"]
+	path = third_party/oidc
+	url = https://github.com/cbcoutinho/oidc
+[submodule "third_party/oidc"]
+	path = third_party/oidc
+	url = https://github.com/cbcoutinho/oidc

CHANGELOG.md

@@ -1,3 +1,95 @@
+## 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
+
+- **caldav**: Fix caldav search() due to missing todos
+
+## v0.17.0 (2025-10-19)
+
+### Feat
+
+- **caldav**: Add support for tasks
+
+### Fix
+
+- **caldav**: Check that calendar exists after creation to avoid race condition
+- **caldav**: Properly parse datetimes as vDDDTypes
+
+### Refactor
+
+- Migrate from internal CalendarClient to caldav library
+
+## v0.16.0 (2025-10-19)
+
+### Feat
+
+- **webdav**: Add search and list favorite response tools
+
+### Perf
+
+- **notes**: Improve notes search performance using async iterators
+
 ## v0.15.2 (2025-10-17)
 
 ### Refactor

CLAUDE.md

@@ -5,20 +5,88 @@ 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)
+uv run python -m tests.load.benchmark
+
+# Quick test with custom concurrency and duration
+uv run python -m tests.load.benchmark --concurrency 20 --duration 60
+
+# Extended load test (50 workers for 5 minutes)
+uv run python -m tests.load.benchmark -c 50 -d 300
+
+# Export results to JSON for analysis
+uv run python -m tests.load.benchmark -c 20 -d 60 --output results.json
+
+# Test OAuth server on port 8001
+uv run python -m tests.load.benchmark --url http://127.0.0.1:8001/mcp
+
+# Verbose mode with detailed logging
+uv run python -m tests.load.benchmark -c 10 -d 30 --verbose
+```
+
+**Load Testing Features:**
+- **Mixed workload** simulating realistic MCP usage (40% reads, 20% writes, 15% search, 25% other operations)
+- **Real-time progress** bar with live RPS and error counts
+- **Detailed metrics**:
+  - Throughput (requests/second)
+  - Latency percentiles (p50, p90, p95, p99)
+  - Per-operation breakdown
+  - Error rates and types
+- **Automatic cleanup** of test data
+- **JSON export** for CI/CD integration
+- **Server health checks** before starting
+
+**Understanding Results:**
+- **Requests/Second (RPS)**: Higher is better. Expected baseline: 50-200 RPS for mixed workload
+- **Latency**:
+  - p50 (median): Should be <100ms for most operations
+  - p95: Should be <500ms
+  - p99: Should be <1000ms
+- **Error Rate**: Should be <1% under normal load
+
+**Common Bottlenecks:**
+1. Nextcloud backend API response times (most common)
+2. Database connection limits
+3. HTTP client connection pooling
+4. Network I/O between containers
+
 ### Code Quality
 ```bash
 # Format and lint code
@@ -42,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
@@ -62,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:
@@ -89,7 +189,17 @@ Each Nextcloud app has a corresponding server module that:
 ### Supported Nextcloud Apps
 
 - **Notes** - Full CRUD operations and search
-- **Calendar** - CalDAV integration with events, recurring events, attendees
+- **Calendar** - CalDAV integration with events, recurring events, attendees, and **tasks (VTODO)**
+  - **Calendar Operations**: List, create, delete calendars
+  - **Event Operations**: Full CRUD, recurring events, attendees, reminders, bulk operations
+  - **Task Operations (VTODO)**: Full CRUD for CalDAV tasks with:
+    - Status tracking (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
+    - Priority levels (0-9, 1=highest, 9=lowest)
+    - Due dates, start dates, completion tracking
+    - Percent complete (0-100%)
+    - Categories and filtering
+    - Search across all calendars
+  - **Note**: Calendar implementation uses caldav library's AsyncDavClient
 - **Contacts** - CardDAV integration with address book operations
 - **Tables** - Row-level operations on Nextcloud Tables
 - **WebDAV** - Complete file system access
@@ -102,11 +212,57 @@ Each Nextcloud app has a corresponding server module that:
 4. **Context injection** - MCP context provides access to the authenticated client instance
 5. **Modular design** - Each Nextcloud app is isolated in its own client/server pair
 
+### MCP Response Patterns
+
+**CRITICAL: Never return raw `List[Dict]` from MCP tools - always wrap in Pydantic response models**
+
+FastMCP serialization issue: raw lists get mangled into dicts with numeric string keys.
+
+**Pattern:**
+1. Client methods return `List[Dict]` (raw data)
+2. MCP tools convert to Pydantic models and wrap in response object
+3. Response models inherit from `BaseResponse`, include `results` field + metadata
+
+**Reference implementations:**
+- `SearchNotesResponse` in `nextcloud_mcp_server/models/notes.py:80`
+- `SearchFilesResponse` in `nextcloud_mcp_server/models/webdav.py:113`
+- Tool examples: `nextcloud_mcp_server/server/{notes,webdav}.py`
+
+**Testing:** Extract `data["results"]` from MCP responses, not `data` directly.
+
 ### Testing Structure
 
-- **Integration tests** in `tests/integration/` and `tests/client/`, `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`
@@ -126,21 +282,89 @@ Each Nextcloud app has a corresponding server module that:
   - `temporary_addressbook` - Creates and cleans up test address books
   - `temporary_contact` - Creates and cleans up test contacts
 - **Test specific functionality** after changes:
-  - For Notes changes: `uv run pytest tests/integration/test_mcp.py -k "notes" -v`
-  - For specific API changes: `uv run pytest tests/integration/test_notes_api.py -v`
+  - For Notes changes: `uv run pytest tests/server/test_mcp.py -k "notes" -v`
+  - For specific API changes: `uv run pytest tests/client/notes/test_notes_api.py -v`
   - 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
@@ -151,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:**
@@ -166,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
@@ -177,3 +400,15 @@ uv run pytest tests/server/test_oauth*.py -v
 - **`pyproject.toml`** - Python project configuration using uv for dependency management
 - **`.env`** (from `env.sample`) - Environment variables for Nextcloud connection
 - **`docker-compose.yml`** - Complete development environment with Nextcloud + database
+
+## Integration testing with docker
+
+### Nextcloud
+
+- The `app` container is running nextcloud.
+- Use `docker compose exec app php occ ...` to get a list of available commands
+
+### Mariadb
+
+- The `db` container is running mariadb
+- Use `docker compose exec db mariadb -u [user] -p [password] [database]` to execute queries. Check the docker-compose file for credentials

Dockerfile

@@ -1,4 +1,7 @@
-FROM ghcr.io/astral-sh/uv:0.9.3-python3.11-alpine@sha256:c5c8e9241027c384aa5e0d0368a6fd013945a23b7a5f25c754ed55ea7ef64f92
+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
 
 WORKDIR /app
 

README.md

@@ -1,270 +1,742 @@
-# Nextcloud MCP Server
+# Nextcloud MCP Server Helm Chart
 
-[![Docker Image](https://img.shields.io/badge/docker-ghcr.io/cbcoutinho/nextcloud--mcp--server-blue)](https://github.com/cbcoutinho/nextcloud-mcp-server/pkgs/container/nextcloud-mcp-server)
+This Helm chart deploys the Nextcloud MCP (Model Context Protocol) Server on a Kubernetes cluster, enabling AI assistants to interact with your Nextcloud instance.
 
-**Enable AI assistants to interact with your Nextcloud instance.**
+## Prerequisites
 
-The Nextcloud MCP (Model Context Protocol) server allows Large Language Models like Claude, GPT, and Gemini to interact with your Nextcloud data through a secure API. Create notes, manage calendars, organize contacts, work with files, and more - all through natural language.
+- 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)
 
-> [!NOTE]
-> **Nextcloud has two ways to enable AI access:** Nextcloud provides [Context Agent](https://github.com/nextcloud/context_agent), an AI agent backend that powers the [Assistant](https://github.com/nextcloud/assistant) app and allows AI to interact with Nextcloud apps like Calendar, Talk, and Contacts. Context Agent runs as an ExApp inside Nextcloud and also exposes an MCP server endpoint for external LLMs. This project (Nextcloud MCP Server) is a **dedicated standalone MCP server** designed specifically for external MCP clients like Claude Code and IDEs, with deep CRUD operations and OAuth support. See our [detailed comparison](docs/comparison-context-agent.md) to understand which approach fits your use case.
+## Installation
 
-## Features
-
-### Supported Nextcloud Apps
-
-| App | Support | Features |
-|-----|---------|----------|
-| **Notes** | ✅ Full | Create, read, update, delete, search notes. Handle attachments. |
-| **Calendar** | ✅ Full | Manage events, recurring events, reminders, attendees via CalDAV. |
-| **Contacts** | ✅ Full | CRUD operations for contacts and address books via CardDAV. |
-| **Cookbook** | ✅ Full | Manage recipes with schema.org metadata. Import from URLs, search, categorize. |
-| **Files (WebDAV)** | ✅ Full | Complete file system access - browse, read, write, organize files. |
-| **Deck** | ✅ Full | Project management - boards, stacks, cards, labels, assignments. |
-| **Tables** | ⚠️ Partial | Row-level operations. Table management not yet supported. |
-| **Tasks** | ❌ Planned | [Issue #73](https://github.com/cbcoutinho/nextcloud-mcp-server/issues/73) |
-
-Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request!
-
-### Authentication
-
-| Mode | Security | Best For |
-|------|----------|----------|
-| **OAuth2/OIDC** ⚠️ **Experimental** | 🔒 High | Testing, evaluation (requires patches) |
-| **Basic Auth** ✅ | Lower | Development, testing, production |
-
-> [!IMPORTANT]
-> **OAuth is experimental** and requires manual patches to upstream Nextcloud apps. Specifically:
-> - **Required patch**: `user_oidc` app needs modifications for Bearer token support ([issue #1221](https://github.com/nextcloud/user_oidc/issues/1221))
-> - **Impact**: Without the patch, most app-specific APIs (Notes, Calendar, Contacts, Deck, etc.) will fail with 401 errors
-> - **Production use**: Wait for upstream patches to be merged into official releases
->
-> See [OAuth Upstream Status](docs/oauth-upstream-status.md) for detailed information on required patches and workarounds.
-
-OAuth2/OIDC provides secure, per-user authentication with access tokens. See [Authentication Guide](docs/authentication.md) for details.
-
-## Quick Start
-
-### 1. Install
+### Quick Start with Basic Authentication
 
 ```bash
-# Clone the repository
-git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
-cd nextcloud-mcp-server
+# Add the Helm repository
+helm repo add nextcloud-mcp https://cbcoutinho.github.io/nextcloud-mcp-server
+helm repo update
 
-# Install with uv (recommended)
-uv sync
-
-# Or using Docker
-docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+# Install with basic auth (recommended for most users)
+helm install nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server \
+  --set nextcloud.host=https://cloud.example.com \
+  --set auth.basic.username=myuser \
+  --set auth.basic.password=mypassword
 ```
 
-See [Installation Guide](docs/installation.md) for detailed instructions.
+### Using a values file
 
-### 2. Configure
+Create a `custom-values.yaml` file:
 
-Create a `.env` 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
-# Copy the sample
-cp env.sample .env
+helm install nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server -f custom-values.yaml
 ```
 
-**For Basic Auth (recommended for most users):**
-```dotenv
-NEXTCLOUD_HOST=https://your.nextcloud.instance.com
-NEXTCLOUD_USERNAME=your_username
-NEXTCLOUD_PASSWORD=your_app_password
+### 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
 ```
 
-**For OAuth (experimental - requires patches):**
-```dotenv
-NEXTCLOUD_HOST=https://your.nextcloud.instance.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 URL for browser-accessible OAuth authorization endpoint (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, defaults to `nextcloud.host`. **Only used for authorization endpoints** that browsers must access. All server-to-server endpoints (token, JWKS, introspection, userinfo) use URLs from OIDC discovery without rewriting
+
+#### 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` |
+
+#### Data Storage
+
+The `/app/data` directory is used for application data (token databases, Qdrant persistent storage, etc.). It is always mounted as writable to support the read-only root filesystem security context.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `dataStorage.enabled` | Enable persistent storage for `/app/data` | `false` |
+| `dataStorage.size` | Size of data storage PVC | `1Gi` |
+| `dataStorage.storageClass` | Storage class (leave empty for default) | `""` |
+| `dataStorage.accessMode` | Access mode | `ReadWriteOnce` |
+| `dataStorage.existingClaim` | Use existing PVC | `""` |
+
+**When to enable persistence:**
+- Multi-user basic auth with offline access (stores `tokens.db`)
+- Qdrant persistent mode (stores vector database)
+- Any feature requiring persistent app data
+
+**When persistence is disabled:** Uses `emptyDir` (non-persistent, data lost on pod restart, but directory remains writable).
+
+#### MCP Server Configuration
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `mcp.transport` | Transport mode | `streamable-http` |
+| `mcp.port` | Server port (used by both auth modes) | `8000` |
+| `mcp.extraArgs` | Additional command-line arguments | `[]` |
+
+The `extraArgs` parameter allows you to pass additional command-line arguments to the MCP server. This is useful for enabling debug logging, enabling specific apps, or other runtime configuration.
+
+**Example:**
+```yaml
+mcp:
+  extraArgs:
+    - "--log-level"
+    - "debug"
+    - "--enable-app"
+    - "notes"
 ```
 
-See [Configuration Guide](docs/configuration.md) for all options.
+#### Image Configuration
 
-### 3. Set Up Authentication
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `image.repository` | Container image repository | `ghcr.io/cbcoutinho/nextcloud-mcp-server` |
+| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
 
-**Basic Auth Setup (recommended):**
-1. Create an app password in Nextcloud (Settings → Security → Devices & sessions)
-2. Add credentials to `.env` file
-3. Start the server
+**Note:** Image tag is automatically set to the chart's `appVersion` and cannot be overridden.
 
-**OAuth Setup (experimental):**
-1. Install Nextcloud OIDC apps (`oidc` + `user_oidc`)
-2. **Apply required patches** to `user_oidc` app (see [OAuth Upstream Status](docs/oauth-upstream-status.md))
-3. Enable dynamic client registration
-4. Configure Bearer token validation
-5. Start the server
+#### Resources
 
-See [OAuth Quick Start](docs/quickstart-oauth.md) for 5-minute setup or [OAuth Setup Guide](docs/oauth-setup.md) for detailed instructions.
+| 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` |
 
-### 4. Run the Server
+#### Service
 
-```bash
-# Load environment variables
-export $(grep -v '^#' .env | xargs)
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `service.type` | Service type | `ClusterIP` |
+| `service.port` | Service port | `8000` |
 
-# Start with Basic Auth (default)
-uv run nextcloud-mcp-server
+#### Ingress
 
-# Or start with OAuth (experimental - requires patches)
-uv run nextcloud-mcp-server --oauth
+| 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 | `[]` |
 
-# Or with Docker
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
-```
+#### Autoscaling
 
-The server starts on `http://127.0.0.1:8000` by default.
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `autoscaling.enabled` | Enable HPA | `false` |
+| `autoscaling.minReplicas` | Minimum replicas | `1` |
+| `autoscaling.maxReplicas` | Maximum replicas | `10` |
+| `autoscaling.targetCPUUtilizationPercentage` | Target CPU % | `80` |
 
-See [Running the Server](docs/running.md) for more options.
+#### Health Probes
 
-### 5. Connect an MCP Client
+| 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` |
 
-Test with MCP Inspector:
+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)
 
-```bash
-uv run mcp dev
-```
+#### Document Processing (Optional)
 
-Or connect from:
-- Claude Desktop
-- Any MCP-compatible client
+| 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` |
 
-## Documentation
+#### Vector Search & Semantic Capabilities (Optional)
 
-### Getting Started
-- **[Installation](docs/installation.md)** - Install the server
-- **[Configuration](docs/configuration.md)** - Environment variables and settings
-- **[Authentication](docs/authentication.md)** - OAuth vs BasicAuth
-- **[Running the Server](docs/running.md)** - Start and manage the server
+Enable semantic search capabilities with BM25 hybrid search by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
 
-### Architecture
-- **[Comparison with Context Agent](docs/comparison-context-agent.md)** - How this MCP server differs from Nextcloud's Context Agent
+**Semantic Search Configuration:**
 
-### OAuth Documentation (Experimental)
-- **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute setup guide
-- **[OAuth Setup Guide](docs/oauth-setup.md)** - Detailed setup instructions
-- **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works
-- **[OAuth Troubleshooting](docs/oauth-troubleshooting.md)** - OAuth-specific issues
-- **[Upstream Status](docs/oauth-upstream-status.md)** - **Required patches and PRs** ⚠️
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `semanticSearch.enabled` | Enable semantic search and background vector synchronization | `false` |
+| `semanticSearch.scanInterval` | Scan interval in seconds | `3600` |
+| `semanticSearch.processorWorkers` | Number of concurrent processor workers | `3` |
+| `semanticSearch.queueMaxSize` | Maximum queue size for pending documents | `10000` |
 
-### Reference
-- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
+**Document Chunking Configuration:**
 
-### App-Specific Documentation
-- [Notes API](docs/notes.md)
-- [Calendar (CalDAV)](docs/calendar.md)
-- [Contacts (CardDAV)](docs/contacts.md)
-- [Cookbook](docs/cookbook.md)
-- [Deck](docs/deck.md)
-- [Tables](docs/table.md)
-- [WebDAV](docs/webdav.md)
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `documentChunking.chunkSize` | Number of words per chunk for embedding | `512` |
+| `documentChunking.chunkOverlap` | Number of overlapping words between chunks | `50` |
 
-## MCP Tools & Resources
+**Chunking Strategy:**
+- **Small chunks (256-384)**: Better precision for searches, more storage overhead
+- **Medium chunks (512-768)**: Balanced approach (recommended for most use cases)
+- **Large chunks (1024+)**: Better context preservation, less precise matching
+- **Overlap**: Should be 10-20% of chunk size to preserve context across boundaries
 
-The server exposes Nextcloud functionality through MCP tools (for actions) and resources (for data browsing).
+**Qdrant Vector Database:**
 
-### Tools
-Tools enable AI assistants to perform actions:
-- `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_contacts_create_contact` - Create a contact
-- And many more...
+Qdrant is deployed as a subchart when `qdrant.enabled` is `true`. All configuration values are passed through to the [qdrant/qdrant](https://github.com/qdrant/qdrant-helm) chart.
 
-### Resources
-Resources provide read-only access to Nextcloud data:
-- `nc://capabilities` - Server capabilities
-- `cookbook://version` - Cookbook app version info
-- `nc://Deck/boards/{board_id}` - Deck board data
-- `notes://settings` - Notes app settings
-- And more...
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `qdrant.enabled` | Deploy Qdrant as a subchart | `false` |
+| `qdrant.replicaCount` | Number of Qdrant replicas | `1` |
+| `qdrant.image.tag` | Qdrant version | `v1.12.5` |
+| `qdrant.apiKey` | Optional API key for authentication | `""` |
+| `qdrant.persistence.size` | Storage size for vector data | `10Gi` |
+| `qdrant.persistence.storageClass` | Storage class | `""` |
+| `qdrant.resources.requests.cpu` | CPU request | `200m` |
+| `qdrant.resources.requests.memory` | Memory request | `512Mi` |
+| `qdrant.resources.limits.cpu` | CPU limit | `1000m` |
+| `qdrant.resources.limits.memory` | Memory limit | `2Gi` |
 
-Run `uv run nextcloud-mcp-server --help` to see all available options.
+**Ollama Embedding Service:**
+
+Ollama is deployed as a subchart when `ollama.enabled` is `true`. All configuration values are passed through to the [ollama/ollama](https://github.com/otwld/ollama-helm) chart. Alternatively, set `ollama.url` to use an external Ollama instance.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `ollama.enabled` | Deploy Ollama as a subchart | `false` |
+| `ollama.url` | External Ollama URL (use with `enabled: false`) | `""` |
+| `ollama.embeddingModel` | Embedding model to use | `nomic-embed-text` |
+| `ollama.verifySsl` | Verify SSL certificates | `true` |
+| `ollama.replicaCount` | Number of Ollama replicas | `1` |
+| `ollama.ollama.models.pull` | Models to pull on startup | `["nomic-embed-text"]` |
+| `ollama.persistentVolume.enabled` | Enable persistent storage | `true` |
+| `ollama.persistentVolume.size` | Storage size for models | `20Gi` |
+| `ollama.resources.requests.cpu` | CPU request | `500m` |
+| `ollama.resources.requests.memory` | Memory request | `1Gi` |
+| `ollama.resources.limits.cpu` | CPU limit | `2000m` |
+| `ollama.resources.limits.memory` | Memory limit | `4Gi` |
+
+**OpenAI Embedding Provider (Alternative):**
+
+Use OpenAI or any OpenAI-compatible API instead of Ollama.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `openai.enabled` | Enable OpenAI embedding provider | `false` |
+| `openai.apiKey` | OpenAI API key | `""` |
+| `openai.existingSecret` | Use existing secret for API key | `""` |
+| `openai.secretKey` | Key in secret containing API key | `api-key` |
+| `openai.baseUrl` | Custom API endpoint (optional) | `""` |
+
+#### Observability & Monitoring
+
+The chart includes comprehensive observability features including Prometheus metrics, OpenTelemetry tracing, and Grafana dashboards.
+
+**Metrics Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.metrics.enabled` | Enable Prometheus metrics | `true` |
+| `observability.metrics.port` | Metrics port | `9090` |
+| `observability.metrics.path` | Metrics endpoint path | `/metrics` |
+
+**Tracing Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.tracing.enabled` | Enable OpenTelemetry tracing | `false` |
+| `observability.tracing.endpoint` | OTLP collector endpoint | `""` |
+| `observability.tracing.serviceName` | Service name in traces | `nextcloud-mcp-server` |
+| `observability.tracing.samplingRate` | Trace sampling rate (0.0-1.0) | `1.0` |
+
+**Logging Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.logging.format` | Log format (json or text) | `json` |
+| `observability.logging.level` | Log level | `INFO` |
+| `observability.logging.includeTraceContext` | Include trace IDs in logs | `true` |
+
+**ServiceMonitor (Prometheus Operator):**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `serviceMonitor.enabled` | Create ServiceMonitor resource | `false` |
+| `serviceMonitor.interval` | Scrape interval | `30s` |
+| `serviceMonitor.scrapeTimeout` | Scrape timeout | `10s` |
+| `serviceMonitor.labels` | Additional labels for ServiceMonitor | `{}` |
+
+**PrometheusRule (Prometheus Operator):**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `prometheusRule.enabled` | Create PrometheusRule with alert rules | `false` |
+| `prometheusRule.labels` | Additional labels for PrometheusRule | `{}` |
+
+**Grafana Dashboards:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `dashboards.enabled` | Enable automatic dashboard provisioning | `false` |
+| `dashboards.grafanaFolder` | Grafana folder name for dashboards | `Nextcloud MCP` |
+| `dashboards.labels` | Additional labels for dashboard ConfigMap | `{}` |
+| `dashboards.annotations` | Additional annotations for dashboard ConfigMap | `{}` |
+
+When `dashboards.enabled` is `true`, a ConfigMap with the Grafana dashboard is created with the `grafana_dashboard: "1"` label. This enables automatic discovery by Grafana sidecar containers (commonly used with kube-prometheus-stack).
+
+The dashboard provides comprehensive monitoring including:
+- HTTP request metrics (RED pattern: Rate, Errors, Duration)
+- MCP tool performance and errors
+- Nextcloud API performance by app (notes, calendar, contacts, etc.)
+- OAuth token operations and cache hit rates
+- External dependency health (Nextcloud, Qdrant, Keycloak, Unstructured API)
+- Vector sync processing pipeline (when enabled)
+
+For manual import or more details, see `charts/nextcloud-mcp-server/dashboards/README.md`.
 
 ## Examples
 
-### Create a Note
-```
-AI: "Create a note called 'Meeting Notes' with today's agenda"
-→ Uses nc_notes_create_note tool
+### 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
 ```
 
-### Manage Recipes
-```
-AI: "Import the recipe from this URL: https://www.example.com/recipe/chocolate-cake"
-→ Uses nc_cookbook_import_recipe tool to extract schema.org metadata
-```
+### Example 2: Using Existing Secrets
 
-### Manage Calendar
-```
-AI: "Schedule a team meeting for next Tuesday at 2pm"
-→ Uses nc_calendar_create_event tool
-```
+#### Basic Auth with Existing Secret
 
-### Organize Files
-```
-AI: "Create a folder called 'Project X' and move all PDFs there"
-→ Uses WebDAV tools (nc_webdav_create_directory, nc_webdav_move)
-```
-
-### Project Management
-```
-AI: "Create a new Deck board for Q1 planning with Todo, In Progress, and Done stacks"
-→ Uses deck_create_board and deck_create_stack tools
-```
-
-## Transport Protocols
-
-The server supports multiple MCP transport protocols:
-
-- **streamable-http** (recommended) - Modern streaming protocol
-- **sse** (default, deprecated) - Server-Sent Events for backward compatibility
-- **http** - Standard HTTP protocol
+Create a secret manually:
 
 ```bash
-# Use streamable-http (recommended)
-uv run nextcloud-mcp-server --transport streamable-http
+kubectl create secret generic nextcloud-credentials \
+  --from-literal=username=myuser \
+  --from-literal=password=mypassword
 ```
 
-> [!WARNING]
-> SSE transport is deprecated and will be removed in a future MCP specification version. Please migrate to `streamable-http`.
+Then reference it in your values:
 
-## Contributing
+```yaml
+nextcloud:
+  host: https://cloud.example.com
 
-Contributions are welcome!
+auth:
+  mode: basic
+  basic:
+    existingSecret: nextcloud-credentials
+    usernameKey: username
+    passwordKey: password
+```
 
-- Report bugs or request features: [GitHub Issues](https://github.com/cbcoutinho/nextcloud-mcp-server/issues)
-- Submit improvements: [Pull Requests](https://github.com/cbcoutinho/nextcloud-mcp-server/pulls)
-- Read [CLAUDE.md](CLAUDE.md) for development guidelines
+#### OAuth with Existing Secret (Pre-registered Client)
 
-## Security
+If you have a pre-registered OAuth client:
 
-[![MseeP.ai Security Assessment](https://mseep.net/pr/cbcoutinho-nextcloud-mcp-server-badge.png)](https://mseep.ai/app/cbcoutinho-nextcloud-mcp-server)
+```bash
+kubectl create secret generic nextcloud-oauth-creds \
+  --from-literal=clientId=my-oauth-client-id \
+  --from-literal=clientSecret=my-oauth-client-secret
+```
 
-This project takes security seriously:
-- OAuth2/OIDC support (experimental - requires upstream patches)
-- Basic Auth with app-specific passwords (recommended)
-- No credential storage with OAuth mode
-- Per-user access tokens
-- Regular security assessments
+Then reference it in your values:
 
-Found a security issue? Please report it privately to the maintainers.
+```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 (only used for browser-accessible auth endpoint)
+
+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 (only used for browser-accessible auth endpoint)
+
+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
+```
+
+### Example 5: Semantic Search with Qdrant and Ollama
+
+Deploy with vector search capabilities using embedded Qdrant and Ollama:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    username: admin
+    password: secure-password
+
+# Enable semantic search
+semanticSearch:
+  enabled: true
+  scanInterval: 1800  # Scan every 30 minutes
+  processorWorkers: 5
+
+# Deploy Qdrant as a subchart
+qdrant:
+  enabled: true
+  persistence:
+    size: 20Gi
+    storageClass: fast-ssd
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+    limits:
+      cpu: 2000m
+      memory: 4Gi
+
+# Deploy Ollama as a subchart
+ollama:
+  enabled: true
+  embeddingModel: nomic-embed-text
+  persistentVolume:
+    size: 30Gi
+    storageClass: standard
+  resources:
+    requests:
+      cpu: 1000m
+      memory: 2Gi
+    limits:
+      cpu: 4000m
+      memory: 8Gi
+```
+
+Or use an external Ollama instance:
+
+```yaml
+semanticSearch:
+  enabled: true
+
+qdrant:
+  enabled: true
+
+# Use external Ollama instead of deploying subchart
+ollama:
+  enabled: false
+  url: "http://ollama.ai-services.svc.cluster.local:11434"
+  embeddingModel: nomic-embed-text
+```
+
+Or use OpenAI for embeddings:
+
+```yaml
+semanticSearch:
+  enabled: true
+
+qdrant:
+  enabled: true
+
+# Use OpenAI instead of Ollama
+openai:
+  enabled: true
+  apiKey: "sk-..."
+  # Or use existing secret:
+  # existingSecret: openai-api-key
+  # secretKey: api-key
+```
+
+## Upgrading
+
+### To upgrade an existing deployment:
+
+```bash
+# Update the repository
+helm repo update
+
+# Upgrade with your custom values
+helm upgrade nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server -f custom-values.yaml
+```
+
+### To upgrade with new values:
+
+```bash
+helm upgrade nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server \
+  --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
+   - For OAuth mode: Ensure MCP server can reach OIDC discovery endpoints (token, JWKS, introspection, userinfo URLs)
+   - Check network policies and firewall rules
+   - Note: Do not use internal Docker hostnames (like `http://app:80`) for `nextcloud.host` - use externally resolvable URLs
+
+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 project is licensed under the AGPL-3.0 License. See [LICENSE](./LICENSE) for details.
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=cbcoutinho/nextcloud-mcp-server&type=Date)](https://www.star-history.com/#cbcoutinho/nextcloud-mcp-server&Date)
-
-## References
-
-- [Model Context Protocol](https://github.com/modelcontextprotocol)
-- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
-- [Nextcloud](https://nextcloud.com/)
+This chart is licensed under AGPL-3.0, consistent with the Nextcloud MCP Server project.

app-hooks/post-installation/00-setup-trusted-domains.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+set -euox pipefail
+
+php /var/www/html/occ config:system:set trusted_domains 2 --value=host.docker.internal

app-hooks/post-installation/0002-Add-PKCE-code-challenge-methods-to-discovery-documen.patch

@@ -1,16 +0,0 @@
-diff --git a/lib/Util/DiscoveryGenerator.php b/lib/Util/DiscoveryGenerator.php
-index ee3cd57..6429f94 100644
---- a/lib/Util/DiscoveryGenerator.php
-+++ b/lib/Util/DiscoveryGenerator.php
-@@ -171,6 +171,11 @@ class DiscoveryGenerator
-             $discoveryPayload['registration_endpoint'] = $host . $this->urlGenerator->linkToRoute('oidc.DynamicRegistration.registerClient', []);
-         }
- 
-+        // Add PKCE support if enabled
-+        if ($this->appConfig->getAppValueBool('proof_key_for_code_exchange', false)) {
-+            $discoveryPayload['code_challenge_methods_supported'] = ['S256'];
-+        }
-+
-         $this->logger->info('Request to Discovery Endpoint.');
- 
-         $response = new JSONResponse($discoveryPayload);

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

@@ -6,14 +6,18 @@ echo "Installing and configuring Calendar app..."
 
 # Enable calendar app
 php /var/www/html/occ app:enable calendar
+php /var/www/html/occ app:enable tasks
 
 # Wait for calendar app to be fully initialized
 echo "Waiting for calendar app to initialize..."
 sleep 5
 
-# Increase limits on calendar creation for integration tests (100 in 60s)
+# Disable rate limits on calendar creation for integration tests
+# Set to -1 to completely disable rate limiting
+# Reference: https://docs.nextcloud.com/server/stable/admin_manual/groupware/calendar.html#rate-limits
 php occ config:app:set dav rateLimitCalendarCreation --type=integer --value=100
 php occ config:app:set dav rateLimitPeriodCalendarCreation --type=integer --value=60
+php occ config:app:set dav maximumCalendarsSubscriptions --type=integer --value=-1
 
 # Ensure maintenance mode is off before calendar operations
 php /var/www/html/occ maintenance:mode --off

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

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+set -euox pipefail
+
+echo "Installing and configuring OIDC app for testing..."
+
+# Check if development OIDC app is mounted at /opt/apps/oidc
+if [ -d /opt/apps/oidc ]; then
+    echo "Development OIDC app found at /opt/apps/oidc"
+
+    # Remove any existing OIDC app in custom_apps (from app store or old symlink)
+    if [ -e /var/www/html/custom_apps/oidc ]; then
+        echo "Removing existing OIDC in custom_apps..."
+        rm -rf /var/www/html/custom_apps/oidc
+    fi
+
+    # Create symlink from custom_apps to the mounted development version
+    # Per Nextcloud docs: apps outside server root need symlinks in server root
+    echo "Creating symlink: custom_apps/oidc -> /opt/apps/oidc"
+    ln -sf /opt/apps/oidc /var/www/html/custom_apps/oidc
+
+    echo "Enabling OIDC app from /opt/apps (development mode via symlink)"
+    php /var/www/html/occ app:enable oidc
+elif [ -d /var/www/html/custom_apps/oidc ]; then
+    echo "OIDC app directory found in custom_apps (already installed)"
+    php /var/www/html/occ app:enable oidc
+else
+    echo "OIDC app not found, installing from app store..."
+    php /var/www/html/occ app:install oidc
+    php /var/www/html/occ app:enable oidc
+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"

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

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+set -euox pipefail
+
+echo "Installing and configuring user_oidc app for testing..."
+
+# Enable the user_oidc app (OIDC client for bearer token validation)
+php /var/www/html/occ app:enable user_oidc
+
+# Configure user_oidc to validate bearer tokens from the OIDC Identity Provider
+php /var/www/html/occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
+
+patch -u /var/www/html/custom_apps/user_oidc/lib/User/Backend.php -i /docker-entrypoint-hooks.d/post-installation/0001-Fix-Bearer-token-authentication-causing-session-logo.patch

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

@@ -1,23 +0,0 @@
-#!/bin/bash
-
-set -euox pipefail
-
-echo "Installing and configuring OIDC apps for testing..."
-
-# Enable the OIDC Identity Provider app
-php /var/www/html/occ app:enable oidc
-
-# Enable the user_oidc app (OIDC client for bearer token validation)
-php /var/www/html/occ app:enable user_oidc
-
-patch -u /var/www/html/custom_apps/user_oidc/lib/User/Backend.php -i /docker-entrypoint-hooks.d/post-installation/0001-Fix-Bearer-token-authentication-causing-session-logo.patch
-patch -u /var/www/html/custom_apps/oidc/lib/Util/DiscoveryGenerator.php -i /docker-entrypoint-hooks.d/post-installation/0002-Add-PKCE-code-challenge-methods-to-discovery-documen.patch
-
-# 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
-
-# Configure user_oidc to validate bearer tokens from the OIDC Identity Provider
-php /var/www/html/occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
-
-echo "OIDC apps 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,742 @@
+# 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
+# Add the Helm repository
+helm repo add nextcloud-mcp https://cbcoutinho.github.io/nextcloud-mcp-server
+helm repo update
+
+# Install with basic auth (recommended for most users)
+helm install nextcloud-mcp nextcloud-mcp/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 nextcloud-mcp/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 URL for browser-accessible OAuth authorization endpoint (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, defaults to `nextcloud.host`. **Only used for authorization endpoints** that browsers must access. All server-to-server endpoints (token, JWKS, introspection, userinfo) use URLs from OIDC discovery without rewriting
+
+#### 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` |
+
+#### Data Storage
+
+The `/app/data` directory is used for application data (token databases, Qdrant persistent storage, etc.). It is always mounted as writable to support the read-only root filesystem security context.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `dataStorage.enabled` | Enable persistent storage for `/app/data` | `false` |
+| `dataStorage.size` | Size of data storage PVC | `1Gi` |
+| `dataStorage.storageClass` | Storage class (leave empty for default) | `""` |
+| `dataStorage.accessMode` | Access mode | `ReadWriteOnce` |
+| `dataStorage.existingClaim` | Use existing PVC | `""` |
+
+**When to enable persistence:**
+- Multi-user basic auth with offline access (stores `tokens.db`)
+- Qdrant persistent mode (stores vector database)
+- Any feature requiring persistent app data
+
+**When persistence is disabled:** Uses `emptyDir` (non-persistent, data lost on pod restart, but directory remains writable).
+
+#### MCP Server Configuration
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `mcp.transport` | Transport mode | `streamable-http` |
+| `mcp.port` | Server port (used by both auth modes) | `8000` |
+| `mcp.extraArgs` | Additional command-line arguments | `[]` |
+
+The `extraArgs` parameter allows you to pass additional command-line arguments to the MCP server. This is useful for enabling debug logging, enabling specific apps, or other runtime configuration.
+
+**Example:**
+```yaml
+mcp:
+  extraArgs:
+    - "--log-level"
+    - "debug"
+    - "--enable-app"
+    - "notes"
+```
+
+#### Image Configuration
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `image.repository` | Container image repository | `ghcr.io/cbcoutinho/nextcloud-mcp-server` |
+| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
+
+**Note:** Image tag is automatically set to the chart's `appVersion` and cannot be overridden.
+
+#### 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` |
+
+#### 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` |
+
+#### Vector Search & Semantic Capabilities (Optional)
+
+Enable semantic search capabilities with BM25 hybrid search by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
+
+**Semantic Search Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `semanticSearch.enabled` | Enable semantic search and background vector synchronization | `false` |
+| `semanticSearch.scanInterval` | Scan interval in seconds | `3600` |
+| `semanticSearch.processorWorkers` | Number of concurrent processor workers | `3` |
+| `semanticSearch.queueMaxSize` | Maximum queue size for pending documents | `10000` |
+
+**Document Chunking Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `documentChunking.chunkSize` | Number of words per chunk for embedding | `512` |
+| `documentChunking.chunkOverlap` | Number of overlapping words between chunks | `50` |
+
+**Chunking Strategy:**
+- **Small chunks (256-384)**: Better precision for searches, more storage overhead
+- **Medium chunks (512-768)**: Balanced approach (recommended for most use cases)
+- **Large chunks (1024+)**: Better context preservation, less precise matching
+- **Overlap**: Should be 10-20% of chunk size to preserve context across boundaries
+
+**Qdrant Vector Database:**
+
+Qdrant is deployed as a subchart when `qdrant.enabled` is `true`. All configuration values are passed through to the [qdrant/qdrant](https://github.com/qdrant/qdrant-helm) chart.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `qdrant.enabled` | Deploy Qdrant as a subchart | `false` |
+| `qdrant.replicaCount` | Number of Qdrant replicas | `1` |
+| `qdrant.image.tag` | Qdrant version | `v1.12.5` |
+| `qdrant.apiKey` | Optional API key for authentication | `""` |
+| `qdrant.persistence.size` | Storage size for vector data | `10Gi` |
+| `qdrant.persistence.storageClass` | Storage class | `""` |
+| `qdrant.resources.requests.cpu` | CPU request | `200m` |
+| `qdrant.resources.requests.memory` | Memory request | `512Mi` |
+| `qdrant.resources.limits.cpu` | CPU limit | `1000m` |
+| `qdrant.resources.limits.memory` | Memory limit | `2Gi` |
+
+**Ollama Embedding Service:**
+
+Ollama is deployed as a subchart when `ollama.enabled` is `true`. All configuration values are passed through to the [ollama/ollama](https://github.com/otwld/ollama-helm) chart. Alternatively, set `ollama.url` to use an external Ollama instance.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `ollama.enabled` | Deploy Ollama as a subchart | `false` |
+| `ollama.url` | External Ollama URL (use with `enabled: false`) | `""` |
+| `ollama.embeddingModel` | Embedding model to use | `nomic-embed-text` |
+| `ollama.verifySsl` | Verify SSL certificates | `true` |
+| `ollama.replicaCount` | Number of Ollama replicas | `1` |
+| `ollama.ollama.models.pull` | Models to pull on startup | `["nomic-embed-text"]` |
+| `ollama.persistentVolume.enabled` | Enable persistent storage | `true` |
+| `ollama.persistentVolume.size` | Storage size for models | `20Gi` |
+| `ollama.resources.requests.cpu` | CPU request | `500m` |
+| `ollama.resources.requests.memory` | Memory request | `1Gi` |
+| `ollama.resources.limits.cpu` | CPU limit | `2000m` |
+| `ollama.resources.limits.memory` | Memory limit | `4Gi` |
+
+**OpenAI Embedding Provider (Alternative):**
+
+Use OpenAI or any OpenAI-compatible API instead of Ollama.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `openai.enabled` | Enable OpenAI embedding provider | `false` |
+| `openai.apiKey` | OpenAI API key | `""` |
+| `openai.existingSecret` | Use existing secret for API key | `""` |
+| `openai.secretKey` | Key in secret containing API key | `api-key` |
+| `openai.baseUrl` | Custom API endpoint (optional) | `""` |
+
+#### Observability & Monitoring
+
+The chart includes comprehensive observability features including Prometheus metrics, OpenTelemetry tracing, and Grafana dashboards.
+
+**Metrics Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.metrics.enabled` | Enable Prometheus metrics | `true` |
+| `observability.metrics.port` | Metrics port | `9090` |
+| `observability.metrics.path` | Metrics endpoint path | `/metrics` |
+
+**Tracing Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.tracing.enabled` | Enable OpenTelemetry tracing | `false` |
+| `observability.tracing.endpoint` | OTLP collector endpoint | `""` |
+| `observability.tracing.serviceName` | Service name in traces | `nextcloud-mcp-server` |
+| `observability.tracing.samplingRate` | Trace sampling rate (0.0-1.0) | `1.0` |
+
+**Logging Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.logging.format` | Log format (json or text) | `json` |
+| `observability.logging.level` | Log level | `INFO` |
+| `observability.logging.includeTraceContext` | Include trace IDs in logs | `true` |
+
+**ServiceMonitor (Prometheus Operator):**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `serviceMonitor.enabled` | Create ServiceMonitor resource | `false` |
+| `serviceMonitor.interval` | Scrape interval | `30s` |
+| `serviceMonitor.scrapeTimeout` | Scrape timeout | `10s` |
+| `serviceMonitor.labels` | Additional labels for ServiceMonitor | `{}` |
+
+**PrometheusRule (Prometheus Operator):**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `prometheusRule.enabled` | Create PrometheusRule with alert rules | `false` |
+| `prometheusRule.labels` | Additional labels for PrometheusRule | `{}` |
+
+**Grafana Dashboards:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `dashboards.enabled` | Enable automatic dashboard provisioning | `false` |
+| `dashboards.grafanaFolder` | Grafana folder name for dashboards | `Nextcloud MCP` |
+| `dashboards.labels` | Additional labels for dashboard ConfigMap | `{}` |
+| `dashboards.annotations` | Additional annotations for dashboard ConfigMap | `{}` |
+
+When `dashboards.enabled` is `true`, a ConfigMap with the Grafana dashboard is created with the `grafana_dashboard: "1"` label. This enables automatic discovery by Grafana sidecar containers (commonly used with kube-prometheus-stack).
+
+The dashboard provides comprehensive monitoring including:
+- HTTP request metrics (RED pattern: Rate, Errors, Duration)
+- MCP tool performance and errors
+- Nextcloud API performance by app (notes, calendar, contacts, etc.)
+- OAuth token operations and cache hit rates
+- External dependency health (Nextcloud, Qdrant, Keycloak, Unstructured API)
+- Vector sync processing pipeline (when enabled)
+
+For manual import or more details, see `charts/nextcloud-mcp-server/dashboards/README.md`.
+
+## 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 (only used for browser-accessible auth endpoint)
+
+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 (only used for browser-accessible auth endpoint)
+
+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
+```
+
+### Example 5: Semantic Search with Qdrant and Ollama
+
+Deploy with vector search capabilities using embedded Qdrant and Ollama:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    username: admin
+    password: secure-password
+
+# Enable semantic search
+semanticSearch:
+  enabled: true
+  scanInterval: 1800  # Scan every 30 minutes
+  processorWorkers: 5
+
+# Deploy Qdrant as a subchart
+qdrant:
+  enabled: true
+  persistence:
+    size: 20Gi
+    storageClass: fast-ssd
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+    limits:
+      cpu: 2000m
+      memory: 4Gi
+
+# Deploy Ollama as a subchart
+ollama:
+  enabled: true
+  embeddingModel: nomic-embed-text
+  persistentVolume:
+    size: 30Gi
+    storageClass: standard
+  resources:
+    requests:
+      cpu: 1000m
+      memory: 2Gi
+    limits:
+      cpu: 4000m
+      memory: 8Gi
+```
+
+Or use an external Ollama instance:
+
+```yaml
+semanticSearch:
+  enabled: true
+
+qdrant:
+  enabled: true
+
+# Use external Ollama instead of deploying subchart
+ollama:
+  enabled: false
+  url: "http://ollama.ai-services.svc.cluster.local:11434"
+  embeddingModel: nomic-embed-text
+```
+
+Or use OpenAI for embeddings:
+
+```yaml
+semanticSearch:
+  enabled: true
+
+qdrant:
+  enabled: true
+
+# Use OpenAI instead of Ollama
+openai:
+  enabled: true
+  apiKey: "sk-..."
+  # Or use existing secret:
+  # existingSecret: openai-api-key
+  # secretKey: api-key
+```
+
+## Upgrading
+
+### To upgrade an existing deployment:
+
+```bash
+# Update the repository
+helm repo update
+
+# Upgrade with your custom values
+helm upgrade nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server -f custom-values.yaml
+```
+
+### To upgrade with new values:
+
+```bash
+helm upgrade nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server \
+  --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
+   - For OAuth mode: Ensure MCP server can reach OIDC discovery endpoints (token, JWKS, introspection, userinfo URLs)
+   - Check network policies and firewall rules
+   - Note: Do not use internal Docker hostnames (like `http://app:80`) for `nextcloud.host` - use externally resolvable URLs
+
+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:3e70e4dfe882ef44738fdc30d9896fb07c12febb27c4a1177e3d63dc0004a0b4
+    image: docker.io/library/nextcloud:32.0.1@sha256:1e4eae55eebe094cae6f9e7b6e0b4bccf4a4fe7b7e6f6f8f57010994b3b2ee42
     restart: always
     ports:
       - 0.0.0.0:8080:80
@@ -31,6 +31,9 @@ services:
     volumes:
       - nextcloud:/var/www/html
       - ./app-hooks/post-installation:/docker-entrypoint-hooks.d/post-installation:ro
+      # Mount OIDC development directory outside /var/www/html to avoid rsync conflicts
+      # The post-installation hook will register /opt/apps as an additional app directory
+      - ./third_party/oidc:/opt/apps/oidc:ro
     environment:
       - NEXTCLOUD_TRUSTED_DOMAINS=app
       - NEXTCLOUD_ADMIN_USER=admin
@@ -39,14 +42,25 @@ services:
       - MYSQL_DATABASE=nextcloud
       - MYSQL_USER=nextcloud
       - MYSQL_HOST=db
+      - 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"]
@@ -62,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
@@ -70,9 +84,13 @@ services:
       - 127.0.0.1:8001:8001
     environment:
       - NEXTCLOUD_HOST=http://app:80
-      - NEXTCLOUD_MCP_SERVER_URL=http://127.0.0.1:8001
-      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://127.0.0.1:8080
-      # No USERNAME/PASSWORD - will use OAuth
+      - 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 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
 

docs/jwt-oauth-reference.md

@@ -0,0 +1,899 @@
+# JWT OAuth Reference - Nextcloud MCP Server
+
+**Last Updated:** 2025-10-23
+**Status:** Production Ready
+
+## Table of Contents
+
+- [Overview](#overview)
+- [JWT vs Opaque Tokens](#jwt-vs-opaque-tokens)
+- [Scope-Based Authorization](#scope-based-authorization)
+- [Configuration](#configuration)
+- [Architecture](#architecture)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+- [Production Deployment](#production-deployment)
+
+---
+
+## Overview
+
+The Nextcloud MCP Server supports OAuth authentication with both **JWT** (RFC 9068) and **opaque** tokens. JWT tokens are recommended for production use as they enable:
+
+- **Faster validation** - No HTTP call needed for token verification
+- **Direct scope extraction** - Scopes embedded in token claims
+- **Dynamic tool filtering** - Users only see tools they have permission to use
+- **Signature verification** - Cryptographic validation using JWKS
+
+### Key Features
+
+- ✅ **JWT Token Support** - RFC 9068 compliant access tokens with RS256 signatures
+- ✅ **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 9728 endpoint for scope discovery
+- ✅ **Backward Compatible** - BasicAuth mode bypasses all scope checks
+
+### Supported Scopes
+
+| Scope | Description | Tool Count |
+|-------|-------------|------------|
+| `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.
+
+---
+
+## JWT vs Opaque Tokens
+
+The Nextcloud OIDC app supports two token formats, configured per-client:
+
+### JWT Tokens (Recommended)
+
+**Advantages:**
+- ✅ Fast validation - JWT signature verified locally using JWKS
+- ✅ Direct scope extraction from `scope` claim in payload
+- ✅ Standard approach (RFC 9068)
+- ✅ No additional HTTP calls for validation
+
+**Disadvantages:**
+- ⚠️ Larger size (~800-1200 chars vs 72 chars for opaque)
+- ⚠️ Token payload visible to client (not an issue for access tokens)
+
+**Token Structure:**
+```json
+{
+  "header": {
+    "typ": "at+JWT",
+    "alg": "RS256",
+    "kid": "..."
+  },
+  "payload": {
+    "iss": "http://localhost:8080",
+    "sub": "admin",
+    "aud": "client_id",
+    "exp": 1234567890,
+    "iat": 1234567890,
+    "scope": "openid profile email mcp:notes:read mcp:notes:write",
+    "client_id": "...",
+    "jti": "..."
+  }
+}
+```
+
+### Opaque Tokens
+
+**Advantages:**
+- ✅ Smaller size (72 characters)
+- ✅ No payload visible to client
+- ✅ Direct scope access via introspection endpoint (RFC 7662)
+
+**Disadvantages:**
+- ❌ Higher latency - Requires HTTP call to introspection endpoint
+- ❌ Slower than JWT signature verification (network roundtrip)
+
+**Validation Method:**
+Opaque tokens are validated using the **introspection endpoint** (`/apps/oidc/introspect`), which returns:
+- Token active status
+- Scope claim (direct access, no inference needed)
+- User information (`sub`, `username`)
+- Token metadata (`exp`, `iat`, `client_id`)
+
+Falls back to userinfo endpoint only if introspection is unavailable.
+
+**When to Use:**
+- Use **JWT tokens** for production (better performance, no HTTP call)
+- Use **opaque tokens** for compatibility with clients that don't support JWT
+
+---
+
+## Scope-Based Authorization
+
+### Scope Definitions
+
+The MCP server uses **coarse-grained scopes** for simplicity:
+
+| Scope | Operations | Examples |
+|-------|------------|----------|
+| `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
+
+| Scope | Description | Required |
+|-------|-------------|----------|
+| `openid` | OIDC authentication | Yes |
+| `profile` | User profile information | Recommended |
+| `email` | Email address | Recommended |
+
+### Recommended Configurations
+
+**Full Access:**
+```
+openid profile email mcp:notes:read mcp:notes:write
+```
+
+**Read-Only:**
+```
+openid profile email mcp:notes:read
+```
+
+**No Custom Scopes (OIDC only):**
+```
+openid profile email
+```
+
+### Implementation
+
+All 90 MCP tools are decorated with scope requirements:
+
+```python
+@mcp.tool()
+@require_scopes("mcp:notes:read")
+async def nc_notes_get_note(note_id: int, ctx: Context):
+    """Get a note by ID (requires mcp:notes:read scope)"""
+    ...
+
+@mcp.tool()
+@require_scopes("mcp:notes:write")
+async def nc_notes_create_note(title: str, content: str, ctx: Context):
+    """Create a note (requires mcp:notes:write scope)"""
+    ...
+```
+
+**Coverage:**
+- ✅ 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. This applies to **both JWT and Bearer (opaque) tokens** in OAuth mode:
+
+**Token with `mcp:notes:read` only:**
+- `list_tools()` returns 36 read-only tools
+- Write tools are hidden from the tool list
+
+**Token with `mcp:notes:write` only:**
+- `list_tools()` returns 54 write-only tools
+- Read tools are hidden from the tool list
+
+**Token with both scopes:**
+- `list_tools()` returns all 90 tools
+
+**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:
+
+```http
+HTTP/1.1 403 Forbidden
+WWW-Authenticate: Bearer error="insufficient_scope",
+                  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 9728's Protected Resource Metadata endpoint:
+
+**Endpoint:** `GET /.well-known/oauth-protected-resource/mcp`
+
+**Response:**
+```json
+{
+  "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"]
+}
+```
+
+This allows OAuth clients to discover supported scopes before requesting authorization.
+
+---
+
+## Configuration
+
+### Docker Services
+
+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 | JWT (configurable) | OAuth testing with JWT tokens |
+
+### OAuth Service Configuration
+
+The `mcp-oauth` service uses **Dynamic Client Registration (DCR)** by default and is configured to request JWT tokens:
+
+**Default Configuration (DCR with JWT tokens):**
+```yaml
+mcp-oauth:
+  build: .
+  command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
+  ports:
+    - 127.0.0.1:8001:8001
+  environment:
+    - NEXTCLOUD_HOST=http://app:80
+    - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8001
+    - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+    - NEXTCLOUD_OIDC_SCOPES=openid profile email mcp:notes:read mcp:notes:write
+  volumes:
+    - oauth-client-storage:/app/.oauth  # Persist DCR credentials
+```
+
+**With Pre-Configured Credentials:**
+```yaml
+mcp-oauth:
+  build: .
+  command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
+  ports:
+    - 127.0.0.1:8001:8001
+  environment:
+    - NEXTCLOUD_HOST=http://app:80
+    - 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
+```
+
+**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** - 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
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NEXTCLOUD_HOST` | Nextcloud base URL | `http://localhost:8080` |
+| `NEXTCLOUD_MCP_SERVER_URL` | MCP server external URL for OAuth callbacks | (required in OAuth mode) |
+| `NEXTCLOUD_PUBLIC_ISSUER_URL` | Public issuer URL for JWT validation | (uses `NEXTCLOUD_HOST`) |
+| `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 mcp:notes:read mcp:notes:write"` |
+| `NEXTCLOUD_OIDC_TOKEN_TYPE` | Token format: `"jwt"` or `"Bearer"` | `"Bearer"` |
+
+### Dynamic Client Registration (DCR)
+
+The MCP server supports **automatic OAuth client registration** using the OIDC Discovery registration endpoint. This eliminates the need for manual client creation in most cases.
+
+**How It Works:**
+
+When the MCP server starts in OAuth mode, it follows this **three-tier credential loading strategy**:
+
+```
+1. Environment Variables (Highest Priority)
+   ├─ NEXTCLOUD_OIDC_CLIENT_ID
+   └─ NEXTCLOUD_OIDC_CLIENT_SECRET
+
+2. Storage File (Second Priority)
+   └─ NEXTCLOUD_OIDC_CLIENT_STORAGE (.nextcloud_oauth_client.json)
+
+3. Dynamic Client Registration (Automatic Fallback)
+   ├─ Discovers registration endpoint from /.well-known/openid-configuration
+   ├─ Registers new client with requested scopes and token type
+   ├─ Saves credentials to storage file for future use
+   └─ Client credentials persist across restarts
+```
+
+**Configuration:**
+
+DCR automatically configures the client based on environment variables:
+
+```bash
+# 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 mcp:notes:read mcp:notes:write"
+export NEXTCLOUD_OIDC_TOKEN_TYPE=jwt  # or "Bearer" for opaque tokens
+```
+
+**Credential Storage:**
+
+- Registered credentials are saved to `NEXTCLOUD_OIDC_CLIENT_STORAGE` (default: `.nextcloud_oauth_client.json`)
+- File has restrictive permissions (0600 - owner read/write only)
+- Credentials are reused on subsequent starts (no re-registration needed)
+- Storage file is checked for expiration (auto-regenerates if expired)
+
+**Format:**
+```json
+{
+  "client_id": "XBd2xqIisu3Kswg39Ub4BUhC36PEYjwwivx3G5nZdDgigvwKXrTHozs7m9DeoLSY",
+  "client_secret": "xNKcy0qpUSau36T60pGGdb03pMEVLXtqykxjK8YkDpoNxNcZ4ClyAT3IAEse2AKT",
+  "client_id_issued_at": 1761097039,
+  "client_secret_expires_at": 2076457039,
+  "redirect_uris": ["http://localhost:8000/oauth/callback"]
+}
+```
+
+**Benefits:**
+- ✅ Zero-configuration OAuth setup
+- ✅ Automatic credential management
+- ✅ Supports both JWT and opaque tokens
+- ✅ Credentials persist across container restarts
+- ✅ Automatic re-registration if credentials expire
+- ✅ Properly sets `allowed_scopes` for JWT token validation
+
+### Manual Client Creation
+
+Manual client creation is **optional** but may be preferred when:
+- You want explicit control over client configuration
+- You're deploying to production environments with strict security policies
+- You need to pre-provision OAuth clients before deployment
+
+**Create Client via OCC Command:**
+
+```bash
+docker compose exec app php occ oidc:create \
+  --token_type=jwt \
+  --allowed_scopes="openid profile email mcp:notes:read mcp:notes:write" \
+  "Nextcloud MCP Server" \
+  "http://localhost:8000/oauth/callback"
+```
+
+**Output:**
+```json
+{
+  "client_id": "XBd2xqIisu3Kswg39Ub4BUhC36PEYjwwivx3G5nZdDgigvwKXrTHozs7m9DeoLSY",
+  "client_secret": "xNKcy0qpUSau36T60pGGdb03pMEVLXtqykxjK8YkDpoNxNcZ4ClyAT3IAEse2AKT",
+  "token_type": "jwt",
+  "allowed_scopes": "openid profile email mcp:notes:read mcp:notes:write"
+}
+```
+
+**Configure MCP Server with Pre-Configured Credentials:**
+
+```bash
+# Option 1: Environment variables (highest priority)
+export NEXTCLOUD_OIDC_CLIENT_ID="<client_id>"
+export NEXTCLOUD_OIDC_CLIENT_SECRET="<client_secret>"
+export NEXTCLOUD_OIDC_TOKEN_TYPE="jwt"
+
+# Option 2: Storage file (second priority)
+# Save the JSON response to .nextcloud_oauth_client.json
+# Server will automatically load it on startup
+```
+
+When credentials are provided via environment variables or storage file, **DCR is skipped**.
+
+---
+
+## Architecture
+
+### Component Overview
+
+```
+┌──────────────────┐     OAuth Flow      ┌──────────────────┐
+│  OAuth Client    │<─────────────────────>│ Nextcloud OIDC  │
+│  (Claude, etc)   │                       │ Server           │
+└────────┬─────────┘                       └────────┬─────────┘
+         │                                          │
+         │ JWT Access Token                         │
+         │ {                                        │
+         │   "scope": "openid mcp:notes:read mcp:notes:write"    │
+         │   ...                                    │
+         │ }                                        │
+         │                                          │
+         v                                          │
+┌────────────────────────────────────────────────────────────┐
+│         Nextcloud MCP Server                               │
+│  ┌───────────────────────────────────────────────────┐    │
+│  │  NextcloudTokenVerifier                            │    │
+│  │  - JWT signature verification (JWKS)               │    │
+│  │  - Introspection endpoint (opaque tokens)          │    │
+│  │  - Userinfo fallback (last resort)                 │    │
+│  └───────────────────┬───────────────────────────────┘    │
+│                      │                                     │
+│                      v                                     │
+│  ┌───────────────────────────────────────────────────┐    │
+│  │  Dynamic Tool Filtering (list_tools)               │    │
+│  │  - Get user scopes from verified token             │    │
+│  │  - Filter tools based on @require_scopes metadata  │    │
+│  │  - Return only accessible tools                     │    │
+│  └───────────────────┬───────────────────────────────┘    │
+│                      │                                     │
+│                      v                                     │
+│  ┌───────────────────────────────────────────────────┐    │
+│  │  Tool Execution (@require_scopes decorator)        │    │
+│  │  - Check token scopes before execution             │    │
+│  │  - Raise InsufficientScopeError if missing         │    │
+│  │  - Return 403 with WWW-Authenticate header         │    │
+│  └───────────────────────────────────────────────────┘    │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+**1. Token Verification** (`nextcloud_mcp_server/auth/token_verifier.py`)
+- **Three-tier validation strategy:**
+  1. **JWT verification** (lines 116-124): JWKS signature validation for JWT tokens
+  2. **Introspection** (lines 126-134): RFC 7662 endpoint for opaque tokens
+  3. **Userinfo fallback** (lines 137-142): Last resort if introspection unavailable
+- Scope extraction from token payload (JWT) or introspection response (opaque)
+- Token caching with TTL to reduce repeated validations
+- Supports both access token formats transparently
+
+**2. Scope Authorization** (`nextcloud_mcp_server/auth/scope_authorization.py`)
+- `@require_scopes()` decorator for tools
+- `get_required_scopes()` - Extract scope requirements from functions
+- `has_required_scopes()` - Check if user has necessary scopes
+- `InsufficientScopeError` exception for WWW-Authenticate challenges
+
+**3. Dynamic Filtering** (`nextcloud_mcp_server/app.py:473-516`)
+- Overrides FastMCP's `list_tools()` method
+- 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/mcp`
+- Advertises `["mcp:notes:read", "mcp:notes:write"]`
+- RFC 9728 compliant
+
+**5. Exception Handler** (`nextcloud_mcp_server/app.py:540-563`)
+- Catches `InsufficientScopeError`
+- Returns 403 with `WWW-Authenticate` header
+- Includes missing scopes and PRM endpoint URL
+
+### Token Validation Flow
+
+The `NextcloudTokenVerifier` implements a **cascading validation strategy** that handles both JWT and opaque tokens efficiently:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  verify_token(token)                                    │
+│  (nextcloud_mcp_server/auth/token_verifier.py:88-142)  │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ├──> 1. Check cache (lines 106-109)
+                         │    ├─ Hit: Return cached AccessToken
+                         │    └─ Miss: Continue to validation
+                         │
+                         ├──> 2. JWT Format Check (lines 112-124)
+                         │    ├─ Token has 3 parts (header.payload.signature)?
+                         │    │   └─ Yes: Attempt JWT verification
+                         │    │       ├─ Verify signature with JWKS (RS256)
+                         │    │       ├─ Validate issuer, expiration
+                         │    │       ├─ Extract scopes from payload
+                         │    │       └─ Success: Return AccessToken
+                         │    └─ Fail/Not JWT: Continue to introspection
+                         │
+                         ├──> 3. Introspection (lines 126-134)
+                         │    ├─ POST to /apps/oidc/introspect
+                         │    ├─ Authenticate with client credentials
+                         │    ├─ Response contains:
+                         │    │   • active: true/false
+                         │    │   • scope: "openid mcp:notes:read mcp:notes:write"
+                         │    │   • sub, exp, iat, client_id
+                         │    ├─ Extract scopes from response
+                         │    └─ Success: Return AccessToken
+                         │
+                         └──> 4. Userinfo Fallback (lines 137-142)
+                              ├─ GET /apps/oidc/userinfo
+                              ├─ Bearer token in Authorization header
+                              ├─ Infer scopes from response claims
+                              └─ Return AccessToken or None
+```
+
+**Validation Priorities:**
+
+| Token Type | Method | Performance | Scope Access | Code Reference |
+|------------|--------|-------------|--------------|----------------|
+| JWT | JWKS Signature | ⚡ Fastest (local) | Direct (`scope` claim) | `token_verifier.py:156-234` |
+| Opaque | Introspection | 🔄 Medium (HTTP) | Direct (`scope` field) | `token_verifier.py:236-328` |
+| Any | Userinfo | 🐌 Slowest (HTTP + inference) | Inferred (from claims) | `token_verifier.py:330-386` |
+
+**Configuration** (`nextcloud_mcp_server/app.py:391-399`):
+```python
+token_verifier = NextcloudTokenVerifier(
+    nextcloud_host=nextcloud_host,
+    userinfo_uri=userinfo_uri,
+    jwks_uri=jwks_uri,                    # Enables JWT verification
+    issuer=jwt_validation_issuer,         # For JWT issuer validation
+    introspection_uri=introspection_uri,  # Enables introspection for opaque tokens
+    client_id=client_id,                  # Required for introspection auth
+    client_secret=client_secret,          # Required for introspection auth
+)
+```
+
+## Testing
+
+### Test Infrastructure
+
+The test suite includes comprehensive coverage for JWT OAuth and scope authorization:
+
+**Test Files:**
+- `tests/server/test_scope_authorization.py` - Scope-based authorization tests (4 tests)
+- `tests/server/test_mcp_oauth_jwt.py` - JWT OAuth integration tests
+- `tests/conftest.py` - Shared fixtures for JWT testing
+
+### Consent Scenario Tests
+
+Four test scenarios verify scope-based tool filtering with different consent levels:
+
+#### 1. No Custom Scopes (0 tools)
+```bash
+uv run pytest tests/server/test_scope_authorization.py::test_jwt_with_no_custom_scopes_returns_zero_tools -v
+```
+
+**Scenario:** JWT token with only OIDC defaults (`openid profile email`)
+**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)
+```bash
+uv run pytest tests/server/test_scope_authorization.py::test_jwt_consent_scenarios_read_only -v
+```
+
+**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
+
+#### 3. Write-Only Access (54 tools)
+```bash
+uv run pytest tests/server/test_scope_authorization.py::test_jwt_consent_scenarios_write_only -v
+```
+
+**Scenario:** JWT token with `mcp:notes:write` only
+**Expected:** 54 write tools visible, read tools hidden
+**Verifies:** Write tools accessible, read tools filtered out
+
+#### 4. Full Access (90 tools)
+```bash
+uv run pytest tests/server/test_scope_authorization.py::test_jwt_consent_scenarios_full_access -v
+```
+
+**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 `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 `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
+
+**MCP Client Fixtures:**
+- `nc_mcp_oauth_client_read_only` - MCP session with read-only token
+- `nc_mcp_oauth_client_write_only` - MCP session with write-only token
+- `nc_mcp_oauth_client_full_access` - MCP session with full access token
+- `nc_mcp_oauth_client_no_custom_scopes` - MCP session with no custom scopes
+
+### Running Tests
+
+**All consent scenario tests:**
+```bash
+uv run pytest tests/server/test_scope_authorization.py -v
+```
+
+**JWT OAuth integration tests:**
+```bash
+uv run pytest tests/server/test_mcp_oauth_jwt.py -v --browser firefox
+```
+
+**With visible browser (debugging):**
+```bash
+uv run pytest tests/server/test_mcp_oauth_jwt.py -v --browser firefox --headed
+```
+
+### Test Configuration
+
+**Playwright Browser:**
+- Default: Chromium
+- Recommended for CI: Firefox (`--browser firefox`)
+- Debugging: Add `--headed` flag
+
+**OAuth Flow:**
+- Uses automated Playwright browser automation
+- Completes OAuth consent flow programmatically
+- Creates separate OAuth client for each scenario
+- Each user gets unique access token
+
+---
+
+## Troubleshooting
+
+### Issue: JWT Issuer Validation Failed
+
+**Symptom:**
+```
+WARNING JWT issuer validation failed: Invalid issuer
+WARNING JWT verification failed, will try other methods
+✅ Extracted scopes from access token: {'openid', 'profile'}
+```
+
+**Cause:** Token's `iss` claim doesn't match expected issuer URL. This often happens when:
+- Using `localhost` vs `127.0.0.1` inconsistently
+- MCP server uses internal URL but clients use public URL
+
+**Solution:**
+```bash
+# Option 1: Use consistent URLs
+export NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+# Ensure all test fixtures also use localhost:8080
+
+# Option 2: Check discovery document
+curl http://localhost:8080/.well-known/openid-configuration | jq .issuer
+# Use this exact issuer in NEXTCLOUD_PUBLIC_ISSUER_URL
+```
+
+**Impact if not fixed:**
+- JWT validation falls back to userinfo endpoint
+- Scopes inferred from userinfo (only standard OIDC scopes, no custom scopes)
+- Result: 0 tools visible or incorrect tool filtering
+
+### Issue: Scopes Not Present in JWT
+
+**Symptom:** JWT token doesn't contain `scope` claim or contains empty string
+
+**Cause:** Client's `allowed_scopes` is empty or not configured
+
+**Solution:**
+```bash
+# Check client configuration
+docker compose exec app php occ oidc:list
+
+# Look for allowed_scopes in output
+# If empty, recreate client with --allowed_scopes
+docker compose exec app php occ oidc:create \
+  --token_type=jwt \
+  --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 `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 | grep "OAuth mode"
+
+# Should see: "Running in OAuth mode"
+
+# If not, check environment variables:
+docker compose exec mcp-oauth env | grep NEXTCLOUD_OIDC
+
+# Ensure no NEXTCLOUD_USERNAME or NEXTCLOUD_PASSWORD set
+```
+
+### Verifying DCR Scope Configuration
+
+DCR **now properly sets `allowed_scopes`** when the `scope` parameter is provided during registration.
+
+**To verify DCR scopes are working:**
+
+```bash
+# Check the registered client's allowed_scopes via database
+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 mcp:notes:read mcp:notes:write")
+```
+
+**If scopes are missing:**
+1. Ensure `NEXTCLOUD_OIDC_SCOPES` environment variable is set correctly
+2. Check MCP server startup logs for the scopes being requested
+3. Verify DCR is enabled in Nextcloud OIDC app settings
+4. Delete `.nextcloud_oauth_client.json` and restart to force re-registration
+
+### Issue: Token Type Case Sensitivity
+
+**Symptom:** JWT tokens not generated even though `token_type=JWT` set
+
+**Cause:** OIDC app checks `token_type === 'jwt'` (lowercase)
+
+**Solution:** Always use lowercase:
+```bash
+# Correct
+export NEXTCLOUD_OIDC_TOKEN_TYPE=jwt
+
+# Incorrect (will generate opaque tokens)
+export NEXTCLOUD_OIDC_TOKEN_TYPE=JWT
+```
+
+### Issue: Missing WWW-Authenticate Header
+
+**Symptom:** 403 error doesn't include `WWW-Authenticate` header
+
+**Cause:** Server not in OAuth mode, or exception not being caught
+
+**Solution:**
+```bash
+# Check server logs for OAuth mode
+docker compose logs mcp-oauth | grep "WWW-Authenticate scope challenges enabled"
+
+# Should see this during startup
+
+# Check exception handling
+docker compose logs mcp-oauth | grep "InsufficientScopeError"
+```
+
+### Debugging Tools
+
+**Check JWT contents:**
+```bash
+# Decode JWT (base64 decode the payload)
+echo "JWT_PAYLOAD_PART" | base64 -d | jq .
+```
+
+**Check database scopes:**
+```bash
+# View access tokens with scopes
+docker compose exec db mariadb -u nextcloud -ppassword nextcloud \
+  -e "SELECT id, client_id, user_id, scope FROM oc_oidc_access_tokens ORDER BY id DESC LIMIT 5;"
+
+# View user consents
+docker compose exec db mariadb -u nextcloud -ppassword nextcloud \
+  -e "SELECT user_id, client_id, scopes_granted FROM oc_oidc_user_consents;"
+```
+
+**Check server logs:**
+```bash
+# Follow JWT verification logs
+docker compose logs -f mcp-oauth | grep -E "JWT|scope|tool"
+
+# Check for issuer mismatches
+docker compose logs mcp-oauth | grep -i issuer
+```
+
+---
+
+## Production Deployment
+
+### Deployment Checklist
+
+✅ **Use JWT Tokens** - Enable `token_type=jwt` for better performance
+✅ **Configure Allowed Scopes** - Always set `allowed_scopes` on OAuth clients
+✅ **Use Pre-Configured Clients** - Avoid DCR limitation with manual client creation
+✅ **Consistent URLs** - Use same URL for `NEXTCLOUD_HOST` and `PUBLIC_ISSUER_URL`
+✅ **Secure Credentials** - Store client credentials securely (environment variables or secrets management)
+✅ **Monitor Token Size** - JWT tokens are 10-15x larger than opaque (not usually an issue)
+✅ **Enable Logging** - Configure appropriate log levels for JWT verification
+
+### Production Configuration Example
+
+```yaml
+# docker-compose.yml (production)
+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 mcp:notes:read mcp:notes:write
+  ports:
+    - "8001:8001"
+```
+
+### Security Considerations
+
+**Token Storage:**
+- Never commit credentials to version control
+- Use environment variables or secrets management
+- Rotate client secrets periodically
+
+**Scope Configuration:**
+- Grant minimum necessary scopes to clients
+- Use read-only tokens for AI assistants that don't need write access
+- Review OAuth client list regularly
+
+**Network Security:**
+- Use HTTPS in production
+- Ensure issuer URL matches public URL
+- Configure proper CORS headers
+
+### Monitoring
+
+**Key Metrics:**
+- JWT verification success/failure rate
+- Scope challenge frequency (indicates clients with insufficient scopes)
+- Token validation latency
+- Tool execution by scope (identify unused scopes)
+
+**Log Patterns:**
+```bash
+# Success
+INFO JWT verified successfully for user: admin
+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: mcp:notes:write
+```
+
+### Known Limitations
+
+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
+
+**Potential Improvements:**
+- Per-app scopes (`nc:notes:read`, `nc:calendar:write`)
+- Resource-level filtering (apply to MCP resources, not just tools)
+- Automatic scope discovery from decorated tools
+- Admin UI for scope management
+
+---
+
+## References
+
+### Standards
+
+- [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 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
+
+- [OAuth Setup Guide](oauth-setup.md) - Complete OAuth configuration guide
+- [OAuth Architecture](oauth-architecture.md) - Detailed architecture documentation
+- [OAuth Troubleshooting](oauth-troubleshooting.md) - Common OAuth issues and solutions
+- [Authentication Guide](authentication.md) - BasicAuth vs OAuth comparison
+
+### External Resources
+
+- [Nextcloud OIDC App](https://github.com/H2CK/oidc) - OIDC identity provider for Nextcloud
+- [PyJWT Documentation](https://pyjwt.readthedocs.io/) - JWT library used for verification
+- [FastMCP Documentation](https://github.com/jlowin/fastmcp) - MCP server framework
+
+---
+
+**Implementation Date:** 2025-10-21 to 2025-10-23
+**Version:** 1.0.0
+**Status:** ✅ Production Ready

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:
@@ -296,8 +724,7 @@ See [Configuration Guide](configuration.md) for all OAuth environment variables:
 
 The integration test suite includes comprehensive OAuth testing:
 
-- **Automated tests** (Playwright): [`tests/integration/test_oauth_playwright.py`](../tests/integration/test_oauth_playwright.py)
-- **Interactive tests**: [`tests/integration/test_oauth_interactive.py`](../tests/integration/test_oauth_interactive.py)
+- **Automated tests** (Playwright): [`tests/client/test_oauth_playwright.py`](../tests/client/test_oauth_playwright.py)
 - **Fixtures**: [`tests/conftest.py`](../tests/conftest.py)
 
 Run OAuth tests:
@@ -306,10 +733,7 @@ Run OAuth tests:
 docker-compose up --build -d mcp-oauth
 
 # Run automated tests
-uv run pytest tests/integration/test_oauth_playwright.py --browser firefox -v
-
-# Run interactive tests (manual login)
-uv run pytest tests/integration/test_oauth_interactive.py -v
+uv run pytest tests/client/test_oauth_playwright.py --browser firefox -v
 ```
 
 ## See Also

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/oauth-upstream-status.md

@@ -44,36 +44,52 @@ This is added at lines ~243, ~310, ~315, and ~337 in `Backend.php`.
 
 ---
 
-### 2. PKCE Support Advertisement in Discovery
+### 2. PKCE Support (RFC 7636)
 
-**Status**: 🟢 **PR Submitted** (Pending Review)
+**Status**: ✅ **Complete** (Merged Upstream)
 
 **Affected Component**: `oidc` app
 
-**Issue**: The OIDC discovery endpoint (`/.well-known/openid-configuration`) does not advertise PKCE support in the `code_challenge_methods_supported` field.
+**Issue**: The OIDC app lacked PKCE (Proof Key for Code Exchange) implementation per RFC 7636.
 
-**Why It Matters**:
-- MCP specification requires PKCE with S256 code challenge method
-- RFC 8414 states that absence of `code_challenge_methods_supported` means PKCE is **not supported**
-- Some MCP clients may reject providers without proper PKCE advertisement
+**Resolution**: Full PKCE support has been implemented and merged upstream into the `oidc` app:
 
-**Current Behavior**:
-- PKCE **functionally works** (the OIDC app accepts and validates PKCE)
-- PKCE just isn't **advertised** in discovery metadata
+**Authorization Endpoint** (`/authorize`):
+- Accepts `code_challenge` and `code_challenge_method` parameters
+- Validates code_challenge format (43-128 characters, unreserved chars only)
+- Supports both `S256` (SHA-256) and `plain` challenge methods
+- Stores challenge and method in database for later verification
 
-**Recommended Fix**: Update `oidc` app to include:
+**Token Endpoint** (`/token`):
+- Accepts `code_verifier` parameter
+- Verifies code_verifier against stored code_challenge using proper algorithm
+- Uses constant-time comparison to prevent timing attacks
+- Enforces code_verifier requirement when PKCE was used in authorization
+
+**Discovery Document**:
 ```json
 {
-  "code_challenge_methods_supported": ["S256"]
+  "code_challenge_methods_supported": ["S256", "plain"]
 }
 ```
 
-**Workaround**: The MCP server implements PKCE validation and logs a warning if not advertised. Functionality still works.
+**Database**:
+- New columns: `code_challenge` and `code_challenge_method` in `oc_oauth2_access_tokens`
+- Migration included for existing installations
 
-**Upstream PR**: [H2CK/oidc#584](https://github.com/H2CK/oidc/pull/584) - Submitted 2025-10-13
-- **Changes**: Adds `code_challenge_methods_supported: ["S256"]` to discovery document when PKCE is enabled
-- **Size**: +5 lines added, 0 deleted
-- **Status**: Open, awaiting review
+**Why It Mattered**:
+- MCP specification requires PKCE with S256 code challenge method
+- RFC 7636 PKCE provides security for public clients (no client secret)
+- RFC 8414 states that absence of `code_challenge_methods_supported` means PKCE is **not supported**
+- Prevents authorization code interception attacks
+
+**Upstream PR**: [H2CK/oidc#584](https://github.com/H2CK/oidc/pull/584) - ✅ **Merged 2025-10-20**
+- **Changes**: Complete PKCE implementation (+194 lines)
+  - Authorization flow with code_challenge validation
+  - Token exchange with code_verifier verification
+  - Database schema updates
+  - Discovery document updates
+- **Status**: Merged and available in v1.10.0+ of the `oidc` app
 
 ---
 
@@ -82,17 +98,17 @@ This is added at lines ~243, ~310, ~315, and ~337 in `Backend.php`.
 | PR/Issue | Component | Status | Priority | Notes |
 |----------|-----------|--------|----------|-------|
 | [user_oidc#1221](https://github.com/nextcloud/user_oidc/issues/1221) | `user_oidc` | 🟡 Open | High | Required for app-specific APIs |
-| [H2CK/oidc#584](https://github.com/H2CK/oidc/pull/584) | `oidc` | 🟢 PR Open | Medium | PKCE advertisement for standards compliance |
+| [H2CK/oidc#584](https://github.com/H2CK/oidc/pull/584) | `oidc` | ✅ Merged | ~~Medium~~ | ✅ PKCE advertisement complete (v1.10.0+) |
 
 ## What Works Without Patches
 
 The following functionality works **out of the box** without any patches:
 
 ✅ **OAuth Flow**:
-- OIDC discovery
+- OIDC discovery with full PKCE support (requires `oidc` app v1.10.0+)
 - Dynamic client registration
-- Authorization code flow with PKCE
-- Token exchange
+- Authorization code flow with PKCE (S256 and plain methods)
+- Token exchange with code_verifier verification
 - Userinfo endpoint
 
 ✅ **MCP Server as Resource Server**:
@@ -116,9 +132,9 @@ The following functionality requires upstream patches:
 - Tables API
 - Custom app APIs
 
-🟡 **Standards Compliance** (PKCE advertisement):
-- Full RFC 8414 compliance
-- MCP client compatibility guarantee
+✅ **Standards Compliance**: Now complete with `oidc` app v1.10.0+
+- ✅ Full RFC 8414 compliance (PKCE advertisement)
+- ✅ MCP client compatibility guarantee
 
 ## Installation Instructions
 
@@ -171,7 +187,7 @@ The integration test suite validates OAuth functionality:
 docker-compose up --build -d mcp-oauth
 
 # Run comprehensive OAuth tests
-uv run pytest tests/integration/test_oauth_playwright.py --browser firefox -v
+uv run pytest tests/client/test_oauth_playwright.py --browser firefox -v
 
 # Tests verify:
 # - OAuth flow completion
@@ -221,6 +237,6 @@ Want to help get these patches merged?
 
 ---
 
-**Last Updated**: 2025-10-14
+**Last Updated**: 2025-10-20
 
-**Next Review**: When PR #584 or issue #1221 has activity
+**Next Review**: When issue #1221 (Bearer token support) has activity

docs/testing-client-sessions-architecture.md

@@ -0,0 +1,317 @@
+# Testing Client Sessions Architecture
+
+## Overview
+
+This document compares different approaches to managing MCP client sessions in integration tests, addressing the fundamental incompatibility between pytest-asyncio's fixture management and anyio's structured concurrency requirements.
+
+## The Problem
+
+When using pytest-asyncio with anyio-based libraries (like the MCP Python SDK), session-scoped async generator fixtures encounter a fundamental issue:
+
+1. **pytest-asyncio** runs fixture teardown in a **new asyncio task** using `runner.run()`
+2. **anyio** requires that cancel scopes be entered and exited in the **same task**
+3. This causes `RuntimeError: Attempted to exit cancel scope in a different task than it was entered in`
+
+This is a **known limitation** documented in the anyio project and is not a bug in either pytest-asyncio or anyio, but rather an inherent incompatibility between their design philosophies.
+
+## Solution Comparison
+
+### Solution 1: Native Async Context Managers with Surgical Exception Handling ✅ **IMPLEMENTED**
+
+**Approach**: Use native `async with` statements for clean code structure, but add targeted exception handling at the pytest fixture level to handle the expected teardown errors.
+
+**Implementation**:
+
+```python
+async def create_mcp_client_session(
+    url: str,
+    token: str | None = None,
+    client_name: str = "MCP",
+) -> AsyncGenerator[ClientSession, Any]:
+    """Uses native async context managers for clean LIFO cleanup."""
+    headers = {"Authorization": f"Bearer {token}"} if token else None
+
+    async with streamablehttp_client(url, headers=headers) as (read_stream, write_stream, _):
+        async with ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+            yield session
+
+@pytest.fixture(scope="session")
+async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
+    """Fixture with surgical exception handling for pytest-asyncio incompatibility."""
+    try:
+        async for session in create_mcp_client_session(
+            url="http://localhost:8000/mcp", client_name="Basic MCP"
+        ):
+            yield session
+    except RuntimeError as e:
+        # Only catch the specific expected error during pytest teardown
+        if "cancel scope" in str(e) and "different task" in str(e):
+            logger.debug(f"Ignoring expected pytest-asyncio teardown issue: {e}")
+        else:
+            # Unexpected RuntimeError - re-raise to fail the test
+            raise
+```
+
+**Pros**:
+- ✅ Clean, idiomatic code using native Python context managers
+- ✅ Exception handling is surgical - only catches the specific expected error
+- ✅ Unexpected errors still propagate and fail tests
+- ✅ Can use session-scoped fixtures for performance
+- ✅ Easy to understand and maintain
+- ✅ Minimal code changes from original implementation
+- ✅ No external dependencies required
+
+**Cons**:
+- ⚠️ Still requires exception suppression (though targeted)
+- ⚠️ String-based exception matching is somewhat fragile
+- ⚠️ Must apply the pattern to each session-scoped fixture
+- ⚠️ Doesn't solve the root cause
+
+**Verdict**: **Recommended** - Best balance of code clarity, maintainability, and pragmatism.
+
+---
+
+### Solution 2: Task-Isolated Fixtures
+
+**Approach**: Run each fixture's client session in an isolated anyio task group, allowing independent cleanup without cross-fixture interference.
+
+**Implementation**:
+
+```python
+@pytest.fixture(scope="session")
+async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
+    """Fixture with task isolation for clean teardown."""
+    import anyio
+
+    session_holder = {"session": None}
+
+    async def create_and_hold_session():
+        """Runs in isolated task - creates session and keeps it alive."""
+        async with streamablehttp_client("http://localhost:8000/mcp") as (read_stream, write_stream, _):
+            async with ClientSession(read_stream, write_stream) as session:
+                await session.initialize()
+                session_holder["session"] = session
+
+                # Keep session alive until cancelled
+                try:
+                    await anyio.sleep_forever()
+                except anyio.get_cancelled_exc_class():
+                    pass  # Expected cancellation
+
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(create_and_hold_session)
+
+        # Wait for session to be ready
+        while session_holder["session"] is None:
+            await anyio.sleep(0.1)
+
+        yield session_holder["session"]
+
+        # Task group cancellation ensures clean LIFO cleanup
+        tg.cancel_scope.cancel()
+```
+
+**Pros**:
+- ✅ No exception suppression needed
+- ✅ Each fixture has its own isolated task scope
+- ✅ More theoretically correct approach
+- ✅ Can use session-scoped fixtures
+
+**Cons**:
+- ❌ Significantly more complex code
+- ❌ Harder to understand for developers unfamiliar with anyio
+- ❌ Requires understanding of task groups and cancel scopes
+- ❌ More boilerplate per fixture
+- ❌ Still doesn't solve the fundamental pytest-asyncio incompatibility
+- ❌ Polling for session readiness is inelegant
+- ❌ Higher cognitive overhead for maintenance
+
+**Verdict**: **Not Recommended** - Complexity outweighs benefits. Consider only if exception handling is completely unacceptable.
+
+---
+
+### Solution 3: Function-Scoped Fixtures with Nested Context Managers
+
+**Approach**: Change fixtures to function scope and rely on Python's context manager nesting for guaranteed LIFO cleanup.
+
+**Implementation**:
+
+```python
+@pytest.fixture(scope="function")  # Changed from session
+async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
+    """Function-scoped fixture with natural LIFO cleanup."""
+    async with streamablehttp_client("http://localhost:8000/mcp") as (read_stream, write_stream, _):
+        async with ClientSession(read_stream, write_stream) as session:
+            await session.initialize()
+            yield session
+
+# For tests needing multiple clients:
+@pytest.fixture(scope="function")
+async def multi_mcp_clients() -> AsyncGenerator[tuple[ClientSession, ClientSession], Any]:
+    """Multiple clients with guaranteed LIFO cleanup through nesting."""
+    async with streamablehttp_client("http://localhost:8000/mcp") as (read1, write1, _):
+        async with ClientSession(read1, write1) as session1:
+            await session1.initialize()
+
+            async with streamablehttp_client("http://localhost:8001/mcp") as (read2, write2, _):
+                async with ClientSession(read2, write2) as session2:
+                    await session2.initialize()
+                    yield session1, session2
+    # Cleanup: session2 -> stream2 -> session1 -> stream1 (LIFO guaranteed)
+```
+
+**Pros**:
+- ✅ No exception handling needed
+- ✅ Simplest to understand
+- ✅ Natural LIFO cleanup through Python's context managers
+- ✅ Each test gets fresh clients (better isolation)
+- ✅ No workarounds or hacks required
+
+**Cons**:
+- ❌ Significantly slower tests (new clients per test)
+- ❌ Cannot share client state across tests
+- ❌ More resource intensive
+- ❌ Higher overhead for test suite execution
+- ❌ May not be practical for expensive fixtures (e.g., OAuth tokens)
+- ❌ Nested context managers become unwieldy with many clients
+
+**Verdict**: **Good Alternative** - Consider for specific fixtures where session scope isn't critical, or for new test files where performance isn't a concern.
+
+---
+
+### Solution 4: Use pytest-trio Instead of pytest-asyncio (Future)
+
+**Approach**: Replace pytest-asyncio with pytest-trio, which was designed with structured concurrency in mind.
+
+**Implementation**:
+
+```python
+# pyproject.toml
+[tool.pytest.ini_options]
+# Remove: asyncio_mode = "auto"
+# Add: trio_mode = "auto"
+
+# Fixtures work naturally with trio
+@pytest.fixture(scope="session")
+async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
+    async with streamablehttp_client("http://localhost:8000/mcp") as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            yield session
+```
+
+**Pros**:
+- ✅ No workarounds needed
+- ✅ Designed for structured concurrency
+- ✅ Theoretically cleanest solution
+- ✅ Can use session-scoped fixtures naturally
+
+**Cons**:
+- ❌ Requires switching from asyncio to trio backend
+- ❌ Major refactoring required
+- ❌ May break existing code that assumes asyncio
+- ❌ Dependency changes throughout project
+- ❌ Team needs to learn trio ecosystem
+- ❌ Less ecosystem support than asyncio
+
+**Verdict**: **Not Practical** - Too disruptive for existing projects. Consider only for greenfield projects or major rewrites.
+
+---
+
+## Decision Matrix
+
+| Solution | Code Clarity | Maintenance | Performance | Safety | Effort |
+|----------|--------------|-------------|-------------|--------|--------|
+| **Solution 1** (Implemented) | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| Solution 2 (Task-Isolated) | ⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ |
+| Solution 3 (Function-Scoped) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| Solution 4 (pytest-trio) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐ |
+
+## Implementation Details
+
+### What Changed in Solution 1
+
+1. **`create_mcp_client_session` function** (conftest.py:61-110):
+   - Replaced manual `__aenter__`/`__aexit__` calls with native `async with` statements
+   - Removed blanket exception suppression from cleanup logic
+   - Added clear documentation about LIFO cleanup order
+   - Simplified from ~60 lines to ~40 lines
+
+2. **Session-scoped MCP client fixtures** (conftest.py:148-1269):
+   - Added targeted exception handling wrapper
+   - Only catches specific "cancel scope" + "different task" RuntimeError
+   - All other exceptions propagate normally
+   - Applied to: `nc_mcp_client`, `nc_mcp_oauth_client`, `alice_mcp_client`, `bob_mcp_client`, `charlie_mcp_client`, `diana_mcp_client`
+
+3. **Documentation**:
+   - Added comprehensive docstrings explaining the workaround
+   - Referenced MCP SDK issue #577 for context
+   - Documented why this is necessary and not a bug
+
+### Benefits of This Implementation
+
+1. **Clean Core Logic**: The `create_mcp_client_session` function is now clean, idiomatic Python with no workarounds
+2. **Isolated Workaround**: Exception handling is confined to pytest fixture level where the issue actually occurs
+3. **Surgical Exception Handling**: Only catches the specific expected error, not all RuntimeErrors
+4. **Performance**: Maintains session-scoped fixtures for fast test execution
+5. **Maintainability**: Easy to understand and modify
+6. **Safety**: Real errors still cause test failures
+
+## Testing Results
+
+All tests pass cleanly with the implementation:
+
+```bash
+$ uv run pytest tests/server/test_mcp.py -v
+============================================= test session starts ==============================================
+tests/server/test_mcp.py::test_mcp_connectivity PASSED                                            [ 16%]
+tests/server/test_mcp.py::test_mcp_notes_crud_workflow PASSED                                     [ 33%]
+tests/server/test_mcp.py::test_mcp_notes_etag_conflict PASSED                                     [ 50%]
+tests/server/test_mcp.py::test_mcp_webdav_workflow PASSED                                         [ 66%]
+tests/server/test_mcp.py::test_mcp_resources_access PASSED                                        [ 83%]
+tests/server/test_mcp.py::test_mcp_calendar_workflow PASSED                                       [100%]
+============================================== 6 passed in 39.52s ==============================================
+```
+
+## Recommendations
+
+### For This Project: Solution 1 ✅
+
+The implemented solution (Solution 1) is the best fit because:
+- Minimal disruption to existing tests
+- Clean, maintainable code
+- Good performance with session-scoped fixtures
+- Targeted exception handling that doesn't hide real errors
+
+### For New Test Files: Consider Solution 3
+
+For new test files where performance isn't critical, consider using function-scoped fixtures (Solution 3):
+- No workarounds needed
+- Perfect code clarity
+- Better test isolation
+
+### For Greenfield Projects: Consider Solution 4
+
+For new projects starting from scratch, consider pytest-trio instead of pytest-asyncio:
+- Native structured concurrency support
+- No workarounds needed
+- Better alignment with modern async Python patterns
+
+## Related Resources
+
+- [MCP Python SDK Issue #577](https://github.com/modelcontextprotocol/python-sdk/issues/577) - Original issue report
+- [Anyio Issue #345](https://github.com/agronholm/anyio/issues/345) - Discussion of fixture limitations
+- [Nextcloud MCP Note 378555](nextcloud://notes/378555) - Detailed investigation notes
+- pytest-asyncio documentation: https://pytest-asyncio.readthedocs.io/
+- anyio structured concurrency guide: https://anyio.readthedocs.io/en/stable/basics.html
+
+## Appendix: Why Can't This Be Fixed Upstream?
+
+The incompatibility cannot be "fixed" in either pytest-asyncio or anyio without breaking their core design:
+
+1. **pytest-asyncio** needs to manage fixture lifecycle across different scopes, requiring separate task creation for cleanup
+2. **anyio** enforces structured concurrency guarantees by requiring same-task cancel scope entry/exit
+3. These requirements are fundamentally incompatible
+
+The maintainers of both projects are aware of this issue, and it's considered an acceptable trade-off given their respective design goals. The recommended approach is to handle it at the application level, as we've done here.

docs/testing-oidc-consent.md

@@ -0,0 +1,412 @@
+# Testing OIDC Consent Feature
+
+This guide explains how to test the OIDC consent feature using the development version of the OIDC app mounted into the Docker environment.
+
+## Setup
+
+### Volume Mount Configuration
+
+The development OIDC app is mounted from `~/Software/oidc` into the container at `/opt/apps/oidc`:
+
+```yaml
+# docker-compose.yml
+volumes:
+  - ../Software/oidc:/opt/apps/oidc:ro
+```
+
+**Why mount outside `/var/www/html/`?**
+- The Nextcloud container uses `rsync` to initialize `/var/www/html/` from the image
+- Mounting inside that path causes conflicts (rsync tries to delete mounted directories)
+- Mounting to `/opt/apps/oidc` avoids rsync entirely
+- Nextcloud supports multiple app directories via the `apps_paths` configuration
+
+**How multiple app paths work:**
+- Nextcloud can load apps from multiple directories
+- The post-installation hook registers `/opt/apps` as an additional app directory (index 2)
+- Apps in default paths (index 0 and 1) are still available
+- All directories are scanned for apps, but `/opt/apps` is read-only
+
+This setup allows you to:
+- Test changes without rebuilding containers
+- Avoid needing npm/node in the container (JS already built on host)
+- Iterate quickly on development
+- Install other Nextcloud apps normally (custom_apps remains writable)
+
+### How It Works
+
+1. **Mount Development App**: Docker mounts `~/Software/oidc` to `/opt/apps/oidc` (outside Nextcloud's path)
+2. **Register App Path**: The `10-install-oidc-app.sh` hook configures `/opt/apps` as an additional app directory
+3. **Enable App**: The hook enables the OIDC app from `/opt/apps/oidc`
+4. **Run Migrations**: Nextcloud detects pending migrations and runs them automatically
+5. **Configure OIDC**: Dynamic client registration and PKCE are enabled
+
+## Starting the Stack
+
+```bash
+cd ~/Projects/nextcloud-mcp-server
+
+# Start fresh (recommended for first test)
+docker compose down -v
+docker compose up -d
+
+# Wait for initialization (check logs)
+docker compose logs -f app
+```
+
+The post-installation hooks will:
+1. Configure custom_apps path (already done)
+2. Enable OIDC app from mounted directory
+3. Run database migrations (including consent table creation)
+4. Configure OIDC settings
+
+## Verifying Installation
+
+### Before Container Restart
+
+Before running `docker compose up -d`, the consent feature will NOT be active:
+- ❌ No `oc_oidc_user_consents` table in database
+- ❌ Migration 0015 not applied yet
+- ❌ ConsentController class not loaded
+- ❌ Consent routes not registered
+
+You can verify this with:
+```bash
+# Check migrations applied (should stop at 0014)
+docker compose exec -T db mariadb -u nextcloud -ppassword nextcloud -e "SELECT version FROM oc_migrations WHERE app = 'oidc' ORDER BY version DESC LIMIT 3;" nextcloud
+
+# Check for consent table (should return empty)
+docker compose exec -T db mariadb -u nextcloud -ppassword nextcloud -e "SHOW TABLES LIKE 'oc_oidc_user_consents';" nextcloud
+```
+
+### After Container Restart
+
+After `docker compose up -d` with the mounted OIDC directory, the consent feature should be active:
+- ✅ `oc_oidc_user_consents` table exists
+- ✅ Migration 0015 (Version0015Date20251123100100) applied
+- ✅ ConsentController routes registered
+- ✅ Consent screen appears during OAuth flows
+
+### Check App Status
+
+```bash
+docker compose exec app php occ app:list | grep -A 2 oidc
+```
+
+Expected output:
+```
+  - oidc: 1.10.0 (enabled)
+```
+
+### Verify App Paths Configuration
+
+Verify that `/opt/apps` is registered as an additional app directory:
+
+```bash
+# Check configured app paths
+docker compose exec app php occ config:system:get apps_paths
+
+# Verify the mount is accessible
+docker compose exec app ls -la /opt/apps/oidc/
+
+# Verify custom_apps is writable (for normal app installation)
+docker compose exec -u www-data app touch /var/www/html/custom_apps/.test && echo "✅ custom_apps is writable" || echo "❌ custom_apps NOT writable"
+docker compose exec app rm -f /var/www/html/custom_apps/.test
+```
+
+Expected: Output should show multiple app paths including index 2 (/opt/apps).
+
+### Verify Consent Files
+
+```bash
+# Check controller exists in mounted location
+docker compose exec app ls -la /opt/apps/oidc/lib/Controller/ConsentController.php
+
+# Check Vue component exists
+docker compose exec app ls -la /opt/apps/oidc/src/Consent.vue
+
+# Check built JS exists
+docker compose exec app ls -lh /opt/apps/oidc/js/oidc-consent.js
+```
+
+### Verify Database Migration
+
+**Note**: These checks will only pass after restarting containers with the mounted OIDC app.
+
+```bash
+# Check if consent table exists
+docker compose exec -T db mariadb -u nextcloud -ppassword nextcloud -e "SHOW TABLES LIKE 'oc_oidc_user_consents';"
+
+# Check table structure
+docker compose exec -T db mariadb -u nextcloud -ppassword nextcloud -e "DESCRIBE oc_oidc_user_consents;"
+
+# Verify migration 0015 was applied
+docker compose exec -T db mariadb -u nextcloud -ppassword nextcloud -e "SELECT app, version FROM oc_migrations WHERE app = 'oidc' AND version LIKE '%0015%';"
+```
+
+Expected table structure:
+- id: int(10) unsigned, auto_increment, primary key
+- user_id: varchar(256), not null
+- client_id: int(10) unsigned, not null
+- scopes_granted: varchar(512), not null
+- created_at: int(10) unsigned, not null
+- updated_at: int(10) unsigned, not null
+- expires_at: int(10) unsigned, nullable
+
+### Verify Routes
+
+```bash
+docker compose exec app php occ router:list | grep consent
+```
+
+Expected output:
+```
+oidc.Consent.show        GET    apps/oidc/consent
+oidc.Consent.grant       POST   apps/oidc/consent/grant
+oidc.Consent.deny        POST   apps/oidc/consent/deny
+```
+
+## Testing the Consent Flow
+
+### 1. Create an OAuth Client
+
+The JWT client is automatically created by the post-installation hooks:
+
+```bash
+# Check if JWT client exists
+docker compose exec app cat /var/www/html/.oauth-jwt/nextcloud_oauth_client.json
+```
+
+### 2. Initiate Authorization Flow
+
+You can test using the MCP OAuth container or manually:
+
+**Option A: Using MCP OAuth container**
+```bash
+# 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:8001/oauth/callback&scope=openid+profile+email+mcp:notes:read+mcp:notes:write&state=test123
+```
+
+### 3. Expected Behavior
+
+**First Authorization:**
+1. User logs in (if not already authenticated)
+2. **Consent screen appears** with:
+   - Application name: "Nextcloud MCP Server JWT"
+   - List of requested scopes with descriptions:
+     - ✓ Basic authentication (openid) - required, cannot deselect
+     - ✓ Profile information (profile)
+     - ✓ Email address (email)
+     - ✓ 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
+5. Consent is stored in database
+
+**Subsequent Authorizations:**
+- Same scopes → No consent screen (uses stored consent)
+- Different scopes → Consent screen appears again
+- If user clicks "Deny" → Returns `error=access_denied` to client
+
+### 4. Verify Consent Stored
+
+After granting consent:
+
+```bash
+# View all stored consents with formatted timestamps
+docker compose exec -T db mariadb -u nextcloud -ppassword nextcloud -e "
+SELECT
+    user_id,
+    client_id,
+    scopes_granted,
+    FROM_UNIXTIME(created_at) as created,
+    FROM_UNIXTIME(updated_at) as updated,
+    FROM_UNIXTIME(expires_at) as expires
+FROM oc_oidc_user_consents;
+" nextcloud
+
+# Or for a compact view:
+docker compose exec -T db mariadb -u nextcloud -ppassword nextcloud -e "SELECT * FROM oc_oidc_user_consents;" nextcloud
+```
+
+## Troubleshooting
+
+### Consent Screen Not Appearing
+
+**Check browser console** (F12 → Console tab):
+```
+# Look for JS errors like:
+Failed to load resource: js/oidc-consent.js
+```
+
+**Check Nextcloud logs:**
+```bash
+docker compose exec app tail -f /var/www/html/data/nextcloud.log | grep -i consent
+```
+
+**Verify JS file loaded:**
+```bash
+# Check file exists and has correct size (~73KB)
+docker compose exec app ls -lh /opt/apps/oidc/js/oidc-consent.js
+```
+
+**Clear Nextcloud caches:**
+```bash
+docker compose exec app php occ maintenance:repair
+docker compose restart app
+```
+
+### Migration Didn't Run
+
+**Check which migrations have been applied:**
+```bash
+docker compose exec -T db mariadb -u nextcloud -ppassword nextcloud -e "SELECT app, version FROM oc_migrations WHERE app = 'oidc' ORDER BY version;" nextcloud
+```
+
+Expected to see `Version0015Date20251123100100` in the list.
+
+**Manually trigger migrations:**
+```bash
+# Disable and re-enable app (triggers all pending migrations)
+docker compose exec app php occ app:disable oidc
+docker compose exec app php occ app:enable oidc
+
+# Verify migration 0015 was applied
+docker compose exec -T db mariadb -u nextcloud -ppassword nextcloud -e "SELECT version FROM oc_migrations WHERE app = 'oidc' AND version LIKE '%0015%';" nextcloud
+```
+
+### Routes Not Registered
+
+If `router:list` doesn't show consent routes:
+
+```bash
+# The autoloader might not have picked up new classes
+# Restart the container
+docker compose restart app
+
+# Wait for it to be ready
+sleep 10
+
+# Try again
+docker compose exec app php occ router:list | grep consent
+```
+
+If still not working, check if ConsentController is accessible:
+```bash
+docker compose exec app php -r "
+require_once '/var/www/html/lib/base.php';
+\$class = 'OCA\\OIDCIdentityProvider\\Controller\\ConsentController';
+if (class_exists(\$class)) {
+    echo \"Class exists\n\";
+} else {
+    echo \"Class not found\n\";
+}
+"
+```
+
+## Making Changes
+
+### Frontend Changes (Vue.js)
+
+1. Edit source file on host:
+```bash
+cd ~/Software/oidc
+# Edit src/Consent.vue
+```
+
+2. Rebuild JS:
+```bash
+npm run build
+```
+
+3. Refresh browser (container sees changes immediately via volume mount at /opt/apps/oidc)
+
+### Backend Changes (PHP)
+
+1. Edit files on host:
+```bash
+cd ~/Software/oidc
+# Edit lib/Controller/ConsentController.php or other PHP files
+```
+
+2. Changes are immediately visible (PHP is interpreted, no build step)
+
+3. For new classes or major changes, restart container:
+```bash
+docker compose restart app
+```
+
+### Database Schema Changes
+
+If you modify the migration:
+
+```bash
+# Changes won't be picked up if migration already ran
+# Need to recreate the database:
+docker compose down -v  # Removes volumes
+docker compose up -d    # Fresh start with clean DB
+```
+
+## Cleanup
+
+### Reset Everything
+
+```bash
+cd ~/Projects/nextcloud-mcp-server
+docker compose down -v
+```
+
+This removes:
+- All containers
+- Database volume (all data)
+- OAuth client credentials
+
+### Keep Data, Restart App
+
+```bash
+docker compose restart app
+```
+
+This preserves:
+- Database (consents, clients, users)
+- OAuth client credentials
+
+## Development Workflow Summary
+
+1. **Make changes** in `~/Software/oidc`
+2. **Build JS** if you changed Vue files: `npm run build`
+3. **Test immediately** - refresh browser or restart container
+4. **No need** to rebuild Docker images or reinstall app
+5. **Iterate quickly** with instant feedback
+
+## Production Deployment
+
+When ready to deploy:
+
+1. **Create patch file** (already done):
+   ```bash
+   cd ~/Software/oidc
+   git format-patch master --stdout > user-consent-feature.patch
+   ```
+
+2. **Test patch** in clean environment:
+   ```bash
+   # In a production-like environment
+   cd /path/to/production/oidc
+   git apply user-consent-feature.patch
+   npm install
+   npm run build
+   php occ app:disable oidc
+   php occ app:enable oidc
+   ```
+
+3. **Verify migration** runs automatically on app enable
+
+4. **Submit pull request** to upstream repository

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

index.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Nextcloud MCP Server Helm Chart</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+            max-width: 800px;
+            margin: 50px auto;
+            padding: 20px;
+            line-height: 1.6;
+        }
+        code {
+            background: #f4f4f4;
+            padding: 2px 6px;
+            border-radius: 3px;
+            font-family: "Monaco", "Courier New", monospace;
+        }
+        pre {
+            background: #f4f4f4;
+            padding: 15px;
+            border-radius: 5px;
+            overflow-x: auto;
+        }
+        h1, h2 { color: #0082c9; }
+        a { color: #0082c9; text-decoration: none; }
+        a:hover { text-decoration: underline; }
+    </style>
+</head>
+<body>
+    <h1>Nextcloud MCP Server Helm Chart</h1>
+
+    <p>A Helm chart for deploying the Nextcloud MCP (Model Context Protocol) Server on Kubernetes, enabling AI assistants to interact with your Nextcloud instance.</p>
+
+    <h2>Installation</h2>
+
+    <p>Add the Helm repository:</p>
+    <pre><code>helm repo add nextcloud-mcp https://cbcoutinho.github.io/nextcloud-mcp-server/
+helm repo update</code></pre>
+
+    <p>Install the chart:</p>
+    <pre><code>helm install nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server \
+  --set nextcloud.host=https://cloud.example.com \
+  --set auth.basic.username=myuser \
+  --set auth.basic.password=mypassword</code></pre>
+
+    <h2>Documentation</h2>
+
+    <ul>
+        <li><a href="README.md">Chart README</a> - Full documentation for the Helm chart</li>
+        <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server">GitHub Repository</a> - Source code and issues</li>
+        <li><a href="index.yaml">Helm Repository Index</a> - Chart metadata</li>
+    </ul>
+
+    <h2>Quick Start</h2>
+
+    <p>See the <a href="README.md">full documentation</a> for detailed configuration options, examples, and troubleshooting guides.</p>
+
+    <hr>
+    <p><small>Generated by <a href="https://github.com/helm/chart-releaser">chart-releaser</a></small></p>
+</body>
+</html>

nextcloud_mcp_server/app.py

@@ -5,17 +5,32 @@ from contextlib import AsyncExitStack, asynccontextmanager
 from dataclasses import dataclass
 
 import click
+import httpx
 import uvicorn
 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.routing import Mount
+from starlette.middleware.cors import CORSMiddleware
+from starlette.responses import JSONResponse
+from starlette.routing import Mount, Route
 
-from nextcloud_mcp_server.auth import NextcloudTokenVerifier, load_or_register_client
+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 setup_logging, LOGGING_CONFIG
+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,
@@ -30,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.
@@ -134,6 +235,114 @@ def is_oauth_mode() -> bool:
     return True
 
 
+async def load_oauth_client_credentials(
+    nextcloud_host: str, registration_endpoint: str | None
+) -> tuple[str, str]:
+    """
+    Load OAuth client credentials from environment, storage file, or dynamic registration.
+
+    This consolidates the client loading logic that was duplicated across multiple functions.
+
+    Args:
+        nextcloud_host: Nextcloud instance URL
+        registration_endpoint: Dynamic registration endpoint URL (or None if not available)
+
+    Returns:
+        Tuple of (client_id, client_secret)
+
+    Raises:
+        ValueError: If credentials cannot be obtained
+    """
+    # Try environment variables first
+    client_id = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID")
+    client_secret = os.getenv("NEXTCLOUD_OIDC_CLIENT_SECRET")
+
+    if client_id and client_secret:
+        logger.info("Using pre-configured OAuth client credentials from environment")
+        return (client_id, client_secret)
+
+    # Try loading from storage file
+    storage_path = os.getenv(
+        "NEXTCLOUD_OIDC_CLIENT_STORAGE", ".nextcloud_oauth_client.json"
+    )
+    from pathlib import Path
+
+    from nextcloud_mcp_server.auth.client_registration import load_client_from_file
+
+    client_info = load_client_from_file(Path(storage_path))
+
+    if client_info:
+        logger.info(
+            f"Loaded OAuth client from storage: {client_info.client_id[:16]}..."
+        )
+        return (client_info.client_id, client_info.client_secret)
+
+    # Try dynamic registration if available
+    if registration_endpoint:
+        logger.info("Dynamic client registration available")
+        mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
+        redirect_uris = [f"{mcp_server_url}/oauth/callback"]
+
+        # Get scopes from environment or use defaults
+        # 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)
+        # Note: Must be lowercase "jwt" to match OIDC app's check
+        token_type = os.getenv("NEXTCLOUD_OIDC_TOKEN_TYPE", "Bearer").lower()
+        # Special case: "bearer" should remain capitalized for compatibility
+        if token_type != "jwt":
+            token_type = "Bearer"
+        logger.info(f"Requesting token type: {token_type}")
+
+        # Load or register client
+        from nextcloud_mcp_server.auth.client_registration import (
+            load_or_register_client,
+        )
+
+        client_info = await load_or_register_client(
+            nextcloud_url=nextcloud_host,
+            registration_endpoint=registration_endpoint,
+            storage_path=storage_path,
+            client_name=f"Nextcloud MCP Server ({token_type})",
+            redirect_uris=redirect_uris,
+            scopes=scopes,
+            token_type=token_type,
+        )
+
+        logger.info(f"OAuth client ready: {client_info.client_id[:16]}...")
+        return (client_info.client_id, client_info.client_secret)
+
+    # No credentials available
+    raise ValueError(
+        "OAuth mode requires either:\n"
+        "1. NEXTCLOUD_OIDC_CLIENT_ID and NEXTCLOUD_OIDC_CLIENT_SECRET environment variables, OR\n"
+        "2. Pre-existing client credentials file at NEXTCLOUD_OIDC_CLIENT_STORAGE, OR\n"
+        "3. Dynamic client registration enabled on Nextcloud OIDC app"
+    )
+
+
 @asynccontextmanager
 async def app_lifespan_basic(server: FastMCP) -> AsyncIterator[AppContext]:
     """
@@ -148,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:
@@ -176,8 +388,6 @@ async def app_lifespan_oauth(server: FastMCP) -> AsyncIterator[OAuthAppContext]:
 
     try:
         # Fetch OIDC discovery
-        import httpx
-
         async with httpx.AsyncClient() as client:
             response = await client.get(discovery_url)
             response.raise_for_status()
@@ -188,49 +398,31 @@ async def app_lifespan_oauth(server: FastMCP) -> AsyncIterator[OAuthAppContext]:
         # Extract endpoints
         userinfo_uri = discovery["userinfo_endpoint"]
         registration_endpoint = discovery.get("registration_endpoint")
+        introspection_uri = discovery.get("introspection_endpoint")
 
         logger.info(f"Userinfo endpoint: {userinfo_uri}")
+        if introspection_uri:
+            logger.info(f"Introspection endpoint: {introspection_uri}")
 
-        # Handle client registration
-        client_id = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID")
-        client_secret = os.getenv("NEXTCLOUD_OIDC_CLIENT_SECRET")
-        storage_path = os.getenv(
-            "NEXTCLOUD_OIDC_CLIENT_STORAGE", ".nextcloud_oauth_client.json"
+        # Load OAuth client credentials
+        client_id, client_secret = await load_oauth_client_credentials(
+            nextcloud_host=nextcloud_host, registration_endpoint=registration_endpoint
         )
 
-        if client_id and client_secret:
-            logger.info("Using pre-configured OAuth client credentials")
-        elif registration_endpoint:
-            logger.info("Dynamic client registration available")
-            mcp_server_url = os.getenv(
-                "NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000"
-            )
-            redirect_uris = [f"{mcp_server_url}/oauth/callback"]
-
-            # Load or register client
-            client_info = await load_or_register_client(
-                nextcloud_url=nextcloud_host,
-                registration_endpoint=registration_endpoint,
-                storage_path=storage_path,
-                client_name="Nextcloud MCP Server",
-                redirect_uris=redirect_uris,
-            )
-
-            logger.info(f"OAuth client ready: {client_info.client_id[:16]}...")
-        else:
-            raise ValueError(
-                "OAuth mode requires either:\n"
-                "1. NEXTCLOUD_OIDC_CLIENT_ID and NEXTCLOUD_OIDC_CLIENT_SECRET, OR\n"
-                "2. Dynamic client registration enabled on Nextcloud OIDC app"
-            )
-
-        # Create token verifier
+        # Create token verifier with introspection support
         token_verifier = NextcloudTokenVerifier(
-            nextcloud_host=nextcloud_host, userinfo_uri=userinfo_uri
+            nextcloud_host=nextcloud_host,
+            userinfo_uri=userinfo_uri,
+            introspection_uri=introspection_uri,
+            client_id=client_id,
+            client_secret=client_secret,
         )
 
         logger.info("OAuth initialization complete")
 
+        # Initialize document processors
+        initialize_document_processors()
+
         try:
             yield OAuthAppContext(
                 nextcloud_host=nextcloud_host, token_verifier=token_verifier
@@ -266,8 +458,6 @@ async def setup_oauth_config():
     logger.info(f"Performing OIDC discovery: {discovery_url}")
 
     # Fetch OIDC discovery
-    import httpx
-
     async with httpx.AsyncClient() as client:
         response = await client.get(discovery_url)
         response.raise_for_status()
@@ -281,59 +471,60 @@ async def setup_oauth_config():
     # Extract endpoints
     issuer = discovery["issuer"]
     userinfo_uri = discovery["userinfo_endpoint"]
+    jwks_uri = discovery.get("jwks_uri")
+    introspection_uri = discovery.get("introspection_endpoint")
     registration_endpoint = discovery.get("registration_endpoint")
 
-    # Allow override of public issuer URL for clients
-    # (useful when MCP server accesses Nextcloud via internal URL
-    # but needs to advertise a different URL to clients)
+    logger.info("OIDC endpoints discovered:")
+    logger.info(f"  Issuer: {issuer}")
+    logger.info(f"  Userinfo: {userinfo_uri}")
+    logger.info(f"  JWKS: {jwks_uri}")
+    if introspection_uri:
+        logger.info(f"  Introspection: {introspection_uri}")
+
+    # Allow override of public issuer URL for both client configuration and JWT validation
+    # When clients access Nextcloud via a public URL (e.g., http://127.0.0.1:8080),
+    # the OIDC app issues JWT tokens with that public URL in the 'iss' claim,
+    # even though the MCP server accesses Nextcloud via an internal URL (e.g., http://app).
+    # Therefore, we must validate JWT tokens against the public issuer, not the internal one.
     public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
     if public_issuer:
         public_issuer = public_issuer.rstrip("/")
-        logger.info(f"Using public issuer URL for clients: {public_issuer}")
+        logger.info(
+            f"Using public issuer URL for clients and JWT validation: {public_issuer}"
+        )
+        # Use public issuer for both client configuration AND JWT validation
         issuer = public_issuer
-
-    # Handle client registration
-    client_id = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID")
-    client_secret = os.getenv("NEXTCLOUD_OIDC_CLIENT_SECRET")
-
-    if client_id and client_secret:
-        logger.info("Using pre-configured OAuth client credentials")
-    elif registration_endpoint:
-        logger.info("Dynamic client registration available")
-        storage_path = os.getenv(
-            "NEXTCLOUD_OIDC_CLIENT_STORAGE", ".nextcloud_oauth_client.json"
-        )
-        mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
-        redirect_uris = [f"{mcp_server_url}/oauth/callback"]
-
-        # Load or register client
-        client_info = await load_or_register_client(
-            nextcloud_url=nextcloud_host,
-            registration_endpoint=registration_endpoint,
-            storage_path=storage_path,
-            client_name="Nextcloud MCP Server",
-            redirect_uris=redirect_uris,
-        )
-
-        logger.info(f"OAuth client ready: {client_info.client_id[:16]}...")
+        jwt_validation_issuer = public_issuer
     else:
-        raise ValueError(
-            "OAuth mode requires either:\n"
-            "1. NEXTCLOUD_OIDC_CLIENT_ID and NEXTCLOUD_OIDC_CLIENT_SECRET, OR\n"
-            "2. Dynamic client registration enabled on Nextcloud OIDC app"
-        )
+        # Use discovered issuer for both
+        jwt_validation_issuer = issuer
 
-    # Create token verifier
+    # Load OAuth client credentials
+    client_id, client_secret = await load_oauth_client_credentials(
+        nextcloud_host=nextcloud_host, registration_endpoint=registration_endpoint
+    )
+
+    # Create token verifier with JWT support and introspection
     token_verifier = NextcloudTokenVerifier(
-        nextcloud_host=nextcloud_host, userinfo_uri=userinfo_uri
+        nextcloud_host=nextcloud_host,
+        userinfo_uri=userinfo_uri,
+        jwks_uri=jwks_uri,  # Enable JWT verification if available
+        issuer=jwt_validation_issuer,  # Use original issuer for JWT validation
+        introspection_uri=introspection_uri,  # Enable introspection for opaque tokens
+        client_id=client_id,
+        client_secret=client_secret,
     )
 
     # Create auth settings
     mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
+
+    # Note: We don't set required_scopes here anymore.
+    # Scopes are now advertised via PRM endpoint and enforced per-tool.
+    # This allows dynamic tool filtering based on user's actual token scopes.
     auth_settings = AuthSettings(
         issuer_url=AnyHttpUrl(issuer),
         resource_server_url=AnyHttpUrl(mcp_server_url),
-        required_scopes=["openid", "profile"],
     )
 
     logger.info("OAuth configuration complete")
@@ -350,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,
@@ -396,6 +587,55 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 f"Unknown app: {app_name}. Available apps: {list(available_apps.keys())}"
             )
 
+    # Override list_tools to filter based on user's token scopes (OAuth mode only)
+    if oauth_enabled:
+        original_list_tools = mcp._tool_manager.list_tools
+
+        def list_tools_filtered():
+            """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()
+            is_jwt = is_jwt_token()
+            logger.info(
+                f"🔍 list_tools called - Token type: {'JWT' if is_jwt else 'opaque/none'}, "
+                f"User scopes: {user_scopes}"
+            )
+
+            # Get all tools
+            all_tools = original_list_tools()
+
+            # 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"✂️ {token_type} scope filtering: {len(allowed_tools)}/{len(all_tools)} tools "
+                    f"available for scopes: {user_scopes}"
+                )
+            else:
+                # BasicAuth mode or no token - show all tools
+                allowed_tools = all_tools
+                logger.info(
+                    f"📋 Showing all {len(all_tools)} tools (no token/BasicAuth)"
+                )
+
+            # 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 and Bearer tokens)"
+        )
+
     if transport == "sse":
         mcp_app = mcp.sse_app()
         lifespan = None
@@ -408,7 +648,167 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 await stack.enter_async_context(mcp.session_manager.run())
                 yield
 
-    app = Starlette(routes=[Mount("/", app=mcp_app)], lifespan=lifespan)
+    # 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 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")
+            if not public_issuer_url:
+                # 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": 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",
+                oauth_protected_resource_metadata,
+                methods=["GET"],
+            )
+        )
+        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:
+
+        @app.exception_handler(InsufficientScopeError)
+        async def handle_insufficient_scope(request, exc: InsufficientScopeError):
+            """Return 403 with WWW-Authenticate header for scope challenges."""
+            resource_url = os.getenv(
+                "NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000"
+            )
+            scope_str = " ".join(exc.missing_scopes)
+
+            return JSONResponse(
+                status_code=403,
+                headers={
+                    "WWW-Authenticate": (
+                        f'Bearer error="insufficient_scope", '
+                        f'scope="{scope_str}", '
+                        f'resource_metadata="{resource_url}/.well-known/oauth-protected-resource/mcp"'
+                    )
+                },
+                content={
+                    "error": "insufficient_scope",
+                    "scopes_required": exc.missing_scopes,
+                },
+            )
+
+        logger.info("WWW-Authenticate scope challenge handler enabled")
 
     return app
 
@@ -474,6 +874,41 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     show_default=True,
     help="MCP server URL for OAuth callbacks (can also use NEXTCLOUD_MCP_SERVER_URL env var)",
 )
+@click.option(
+    "--nextcloud-host",
+    envvar="NEXTCLOUD_HOST",
+    help="Nextcloud instance URL (can also use NEXTCLOUD_HOST env var)",
+)
+@click.option(
+    "--nextcloud-username",
+    envvar="NEXTCLOUD_USERNAME",
+    help="Nextcloud username for BasicAuth (can also use NEXTCLOUD_USERNAME env var)",
+)
+@click.option(
+    "--nextcloud-password",
+    envvar="NEXTCLOUD_PASSWORD",
+    help="Nextcloud password for BasicAuth (can also use NEXTCLOUD_PASSWORD env var)",
+)
+@click.option(
+    "--oauth-scopes",
+    envvar="NEXTCLOUD_OIDC_SCOPES",
+    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 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",
+    envvar="NEXTCLOUD_OIDC_TOKEN_TYPE",
+    default="bearer",
+    show_default=True,
+    type=click.Choice(["bearer", "jwt"], case_sensitive=False),
+    help="OAuth token type (can also use NEXTCLOUD_OIDC_TOKEN_TYPE env var)",
+)
+@click.option(
+    "--public-issuer-url",
+    envvar="NEXTCLOUD_PUBLIC_ISSUER_URL",
+    help="Public issuer URL for OAuth (can also use NEXTCLOUD_PUBLIC_ISSUER_URL env var)",
+)
 def run(
     host: str,
     port: int,
@@ -485,6 +920,12 @@ def run(
     oauth_client_secret: str | None,
     oauth_storage_path: str,
     mcp_server_url: str,
+    nextcloud_host: str | None,
+    nextcloud_username: str | None,
+    nextcloud_password: str | None,
+    oauth_scopes: str,
+    oauth_token_type: str,
+    public_issuer_url: str | None,
 ):
     """
     Run the Nextcloud MCP server.
@@ -496,24 +937,52 @@ def run(
 
     \b
     Examples:
-      # BasicAuth mode (legacy)
+      # BasicAuth mode with CLI options
+      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com \\
+          --nextcloud-username=admin --nextcloud-password=secret
+
+      # BasicAuth mode with env vars (recommended for credentials)
+      $ export NEXTCLOUD_HOST=https://cloud.example.com
+      $ export NEXTCLOUD_USERNAME=admin
+      $ export NEXTCLOUD_PASSWORD=secret
       $ nextcloud-mcp-server --host 0.0.0.0 --port 8000
 
       # OAuth mode with auto-registration
-      $ nextcloud-mcp-server --oauth
+      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth
 
       # OAuth mode with pre-configured client
-      $ nextcloud-mcp-server --oauth --oauth-client-id=xxx --oauth-client-secret=yyy
+      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth \\
+          --oauth-client-id=xxx --oauth-client-secret=yyy
+
+      # OAuth mode with custom scopes and JWT tokens
+      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth \\
+          --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 \\
+          --public-issuer-url=http://localhost:8080
     """
-    # Set OAuth env vars from CLI options if provided
+    # Set env vars from CLI options if provided
+    if nextcloud_host:
+        os.environ["NEXTCLOUD_HOST"] = nextcloud_host
+    if nextcloud_username:
+        os.environ["NEXTCLOUD_USERNAME"] = nextcloud_username
+    if nextcloud_password:
+        os.environ["NEXTCLOUD_PASSWORD"] = nextcloud_password
     if oauth_client_id:
         os.environ["NEXTCLOUD_OIDC_CLIENT_ID"] = oauth_client_id
     if oauth_client_secret:
         os.environ["NEXTCLOUD_OIDC_CLIENT_SECRET"] = oauth_client_secret
     if oauth_storage_path:
         os.environ["NEXTCLOUD_OIDC_CLIENT_STORAGE"] = oauth_storage_path
+    if oauth_scopes:
+        os.environ["NEXTCLOUD_OIDC_SCOPES"] = oauth_scopes
+    if oauth_token_type:
+        os.environ["NEXTCLOUD_OIDC_TOKEN_TYPE"] = oauth_token_type
     if mcp_server_url:
         os.environ["NEXTCLOUD_MCP_SERVER_URL"] = mcp_server_url
+    if public_issuer_url:
+        os.environ["NEXTCLOUD_PUBLIC_ISSUER_URL"] = public_issuer_url
 
     # Force OAuth mode if explicitly requested
     if oauth is True:

nextcloud_mcp_server/auth/__init__.py

@@ -3,6 +3,17 @@
 from .bearer_auth import BearerAuth
 from .client_registration import load_or_register_client, register_client
 from .context_helper import get_client_from_context
+from .scope_authorization import (
+    InsufficientScopeError,
+    ScopeAuthorizationError,
+    check_scopes,
+    discover_all_scopes,
+    get_access_token_scopes,
+    get_required_scopes,
+    has_required_scopes,
+    is_jwt_token,
+    require_scopes,
+)
 from .token_verifier import NextcloudTokenVerifier
 
 __all__ = [
@@ -11,4 +22,13 @@ __all__ = [
     "register_client",
     "load_or_register_client",
     "get_client_from_context",
+    "require_scopes",
+    "ScopeAuthorizationError",
+    "InsufficientScopeError",
+    "check_scopes",
+    "discover_all_scopes",
+    "get_access_token_scopes",
+    "get_required_scopes",
+    "has_required_scopes",
+    "is_jwt_token",
 ]

nextcloud_mcp_server/auth/client_registration.py

@@ -1,5 +1,6 @@
 """Dynamic client registration for Nextcloud OIDC."""
 
+import datetime as dt
 import json
 import logging
 import os
@@ -7,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,
@@ -22,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:
@@ -41,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":
@@ -58,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"),
         )
 
 
@@ -67,6 +80,7 @@ async def register_client(
     client_name: str = "Nextcloud MCP Server",
     redirect_uris: list[str] | None = None,
     scopes: str = "openid profile email",
+    token_type: str = "Bearer",
 ) -> ClientInfo:
     """
     Register a new OAuth client with Nextcloud OIDC using dynamic client registration.
@@ -77,6 +91,7 @@ async def register_client(
         client_name: Name of the client application
         redirect_uris: List of redirect URIs (default: http://localhost:8000/oauth/callback)
         scopes: Space-separated list of scopes to request
+        token_type: Type of access tokens to issue (default: "Bearer", also supports "JWT")
 
     Returns:
         ClientInfo with registration details
@@ -95,6 +110,7 @@ async def register_client(
         "grant_types": ["authorization_code", "refresh_token"],
         "response_types": ["code"],
         "scope": scopes,
+        "token_type": token_type,
     }
 
     logger.info(f"Registering OAuth client with Nextcloud: {client_name}")
@@ -113,11 +129,24 @@ async def register_client(
             logger.info(
                 f"Successfully registered client: {client_info.get('client_id')}"
             )
+            expires_at = dt.datetime.fromtimestamp(
+                client_info.get("client_secret_expires_at")
+            )
             logger.info(
-                f"Client expires at: {client_info.get('client_secret_expires_at')} "
+                f"Client expires at: {expires_at} "
                 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"],
@@ -128,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:
@@ -205,12 +236,140 @@ 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,
     storage_path: str | Path,
     client_name: str = "Nextcloud MCP Server",
     redirect_uris: list[str] | None = None,
+    scopes: str = "openid profile email",
+    token_type: str = "Bearer",
 ) -> ClientInfo:
     """
     Load client from storage or register a new one if not found/expired.
@@ -227,6 +386,8 @@ async def load_or_register_client(
         storage_path: Path to store client credentials
         client_name: Name of the client application
         redirect_uris: List of redirect URIs
+        scopes: Space-separated list of scopes to request (default: "openid profile email")
+        token_type: Type of access tokens to issue (default: "Bearer", also supports "JWT")
 
     Returns:
         ClientInfo with valid credentials
@@ -249,6 +410,8 @@ async def load_or_register_client(
         registration_endpoint=registration_endpoint,
         client_name=client_name,
         redirect_uris=redirect_uris,
+        scopes=scopes,
+        token_type=token_type,
     )
 
     # Save to storage

nextcloud_mcp_server/auth/scope_authorization.py

@@ -0,0 +1,343 @@
+"""Scope-based authorization for MCP tools."""
+
+import logging
+from functools import wraps
+from typing import Callable
+
+from mcp.server.auth.middleware.auth_context import get_access_token
+from mcp.server.auth.provider import AccessToken
+from mcp.server.fastmcp import Context
+from mcp.server.fastmcp.utilities.context_injection import find_context_parameter
+
+logger = logging.getLogger(__name__)
+
+
+class ScopeAuthorizationError(Exception):
+    """Raised when a request lacks required scopes."""
+
+    pass
+
+
+class InsufficientScopeError(ScopeAuthorizationError):
+    """Raised when request lacks required scopes (enables step-up auth).
+
+    This exception triggers a 403 response with WWW-Authenticate header
+    containing the missing scopes, allowing clients to perform step-up
+    authorization to obtain additional permissions.
+    """
+
+    def __init__(self, missing_scopes: list[str], message: str | None = None):
+        self.missing_scopes = missing_scopes
+        super().__init__(
+            message or f"Missing required scopes: {', '.join(missing_scopes)}"
+        )
+
+
+def require_scopes(*required_scopes: str):
+    """
+    Decorator to require specific OAuth scopes for MCP tool execution.
+
+    This decorator:
+    1. Stores scope requirements as function metadata (_required_scopes attribute)
+    2. Checks that the access token contains all required scopes before execution
+    3. Raises ScopeAuthorizationError if any required scope is missing
+
+    The stored metadata enables dynamic tool filtering - tools can be hidden from
+    users who lack the necessary scopes.
+
+    Args:
+        *required_scopes: Variable number of scope strings required (e.g., "notes:read", "notes:write")
+
+    Returns:
+        Decorated function that checks scopes before execution
+
+    Example:
+        ```python
+        @mcp.tool()
+        @require_scopes("notes:read")
+        async def nc_notes_get_note(ctx: Context, note_id: int):
+            # This tool requires the notes:read scope
+            ...
+
+        @mcp.tool()
+        @require_scopes("notes:write")
+        async def nc_notes_create_note(ctx: Context, ...):
+            # This tool requires the notes:write scope
+            ...
+        ```
+
+    Raises:
+        ScopeAuthorizationError: If required scopes are not present in the access token
+    """
+
+    def decorator(func: Callable):
+        # Store scope requirements as function metadata for dynamic filtering
+        func._required_scopes = list(required_scopes)  # type: ignore
+
+        # Find which parameter receives the Context (FastMCP injects it by name)
+        context_param_name = find_context_parameter(func)
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # Extract context from kwargs (where FastMCP injected it)
+            ctx: Context | None = (
+                kwargs.get(context_param_name) if context_param_name else None
+            )
+
+            if ctx is None:
+                # No context parameter found - likely BasicAuth mode
+                # In BasicAuth mode, all operations are allowed
+                logger.debug(
+                    f"No context parameter for {func.__name__} - allowing (BasicAuth mode)"
+                )
+                return await func(*args, **kwargs)
+
+            # Check if we're in OAuth mode (access token available)
+            access_token: AccessToken | None = getattr(
+                ctx.request_context, "access_token", None
+            )
+
+            if access_token is None:
+                # Not in OAuth mode (BasicAuth or no auth)
+                # In BasicAuth mode, all operations are allowed
+                logger.debug(
+                    f"No access token present for {func.__name__} - allowing (BasicAuth mode)"
+                )
+                return await func(*args, **kwargs)
+
+            # Extract scopes from access token
+            token_scopes = set(access_token.scopes or [])
+            required_scopes_set = set(required_scopes)
+
+            # Check if all required scopes are present
+            missing_scopes = required_scopes_set - token_scopes
+            if missing_scopes:
+                error_msg = (
+                    f"Access denied to {func.__name__}: "
+                    f"Missing required scopes: {', '.join(sorted(missing_scopes))}. "
+                    f"Token has scopes: {', '.join(sorted(token_scopes)) if token_scopes else 'none'}"
+                )
+                logger.warning(error_msg)
+                raise InsufficientScopeError(list(missing_scopes), error_msg)
+
+            # All required scopes present - allow execution
+            logger.debug(
+                f"Scope authorization passed for {func.__name__}: {required_scopes}"
+            )
+            return await func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def get_access_token_scopes(ctx: Context | None = None) -> set[str]:
+    """
+    Extract scopes from the authenticated user's access token.
+
+    This function uses MCP SDK's contextvar to access the token, which works
+    across all request types including list_tools.
+
+    Args:
+        ctx: FastMCP context object (unused, kept for compatibility)
+
+    Returns:
+        Set of scope strings, empty set if no token or no scopes
+    """
+    # Use MCP SDK's get_access_token() which uses contextvars
+    # This works for all request types, including list_tools
+    access_token: AccessToken | None = get_access_token()
+
+    if access_token is None:
+        logger.debug("No access token found in auth context (likely BasicAuth mode)")
+        return set()
+
+    scopes = set(access_token.scopes or [])
+    logger.info(f"✅ Extracted scopes from access token: {scopes}")
+    return scopes
+
+
+def check_scopes(ctx: Context, *required_scopes: str) -> tuple[bool, set[str]]:
+    """
+    Check if the request context has all required scopes.
+
+    Utility function for manual scope checking without decorator.
+
+    Args:
+        ctx: FastMCP context object
+        *required_scopes: Variable number of required scope strings
+
+    Returns:
+        Tuple of (has_all_scopes: bool, missing_scopes: set[str])
+
+    Example:
+        ```python
+        async def my_tool(ctx: Context):
+            has_scopes, missing = check_scopes(ctx, "notes:read", "notes:write")
+            if not has_scopes:
+                # Handle missing scopes
+                ...
+        ```
+    """
+    token_scopes = get_access_token_scopes(ctx)
+
+    # If no access token, assume BasicAuth mode (all operations allowed)
+    if not token_scopes and getattr(ctx.request_context, "access_token", None) is None:
+        return True, set()
+
+    required_scopes_set = set(required_scopes)
+    missing_scopes = required_scopes_set - token_scopes
+
+    return len(missing_scopes) == 0, missing_scopes
+
+
+def get_required_scopes(func: Callable) -> list[str]:
+    """
+    Extract required scopes from a function decorated with @require_scopes.
+
+    Args:
+        func: Function to check (may be decorated)
+
+    Returns:
+        List of required scope strings, empty list if no scopes required
+
+    Example:
+        ```python
+        @require_scopes("notes:read", "notes:write")
+        async def my_tool():
+            pass
+
+        scopes = get_required_scopes(my_tool)  # ["notes:read", "notes:write"]
+        ```
+    """
+    return getattr(func, "_required_scopes", [])
+
+
+def is_jwt_token() -> bool:
+    """
+    Check if the current access token is in JWT format.
+
+    JWT tokens have 3 parts separated by dots (header.payload.signature).
+    Opaque tokens are random strings without this structure.
+
+    Returns:
+        True if current token is JWT format, False if opaque or no token
+    """
+    access_token: AccessToken | None = get_access_token()
+
+    if access_token is None:
+        logger.debug("No access token found - not JWT")
+        return False
+
+    # JWT tokens have exactly 2 dots (3 parts)
+    token_string = access_token.token
+    is_jwt = "." in token_string and token_string.count(".") == 2
+
+    logger.debug(f"Token format check: is_jwt={is_jwt}")
+    return is_jwt
+
+
+def has_required_scopes(func: Callable, user_scopes: set[str]) -> bool:
+    """
+    Check if a user has all scopes required by a function.
+
+    Used for dynamic tool filtering - determines if a tool should be visible
+    to a user based on their token scopes.
+
+    Args:
+        func: Function decorated with @require_scopes
+        user_scopes: Set of scopes the user possesses
+
+    Returns:
+        True if user has all required scopes (or no scopes required), False otherwise
+
+    Example:
+        ```python
+        @require_scopes("notes:write")
+        async def create_note():
+            pass
+
+        user_scopes = {"notes:read", "notes:write"}
+        can_see = has_required_scopes(create_note, user_scopes)  # True
+
+        limited_user_scopes = {"notes:read"}
+        can_see = has_required_scopes(create_note, limited_user_scopes)  # False
+        ```
+    """
+    required = get_required_scopes(func)
+
+    # No scopes required → always allow
+    if not required:
+        return True
+
+    # Empty user_scopes but scopes required → deny
+    if not user_scopes:
+        return False
+
+    # 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

@@ -5,6 +5,8 @@ import time
 from typing import Any
 
 import httpx
+import jwt
+from jwt import PyJWKClient
 from mcp.server.auth.provider import AccessToken, TokenVerifier
 
 logger = logging.getLogger(__name__)
@@ -12,22 +14,33 @@ logger = logging.getLogger(__name__)
 
 class NextcloudTokenVerifier(TokenVerifier):
     """
-    Validates access tokens using Nextcloud OIDC userinfo endpoint.
+    Validates access tokens using JWT verification with JWKS or userinfo endpoint fallback.
 
-    This verifier:
-    1. Calls the userinfo endpoint with the bearer token
-    2. Caches successful responses to avoid repeated API calls
-    3. Extracts username from the 'sub' or 'preferred_username' claim
-    4. Optionally supports JWT validation for performance (future enhancement)
+    This verifier supports both JWT and opaque tokens:
+    1. For JWT tokens: Verifies signature with JWKS and extracts scopes from payload
+    2. For opaque tokens: Falls back to userinfo endpoint validation
+    3. Caches successful responses to avoid repeated API calls/verifications
 
-    The userinfo endpoint validates the token and returns user claims if valid,
-    or returns HTTP 400/401 if the token is invalid or expired.
+    JWT validation provides:
+    - Faster validation (no HTTP call needed)
+    - Direct scope extraction from token payload
+    - Signature verification using JWKS
+
+    Userinfo fallback provides:
+    - Support for opaque tokens
+    - Backward compatibility
+    - Additional validation layer
     """
 
     def __init__(
         self,
         nextcloud_host: str,
         userinfo_uri: str,
+        jwks_uri: str | None = None,
+        issuer: str | None = None,
+        introspection_uri: str | None = None,
+        client_id: str | None = None,
+        client_secret: str | None = None,
         cache_ttl: int = 3600,
     ):
         """
@@ -36,26 +49,52 @@ class NextcloudTokenVerifier(TokenVerifier):
         Args:
             nextcloud_host: Base URL of the Nextcloud instance (e.g., https://cloud.example.com)
             userinfo_uri: Full URL to the userinfo endpoint
+            jwks_uri: Full URL to the JWKS endpoint (for JWT verification)
+            issuer: Expected issuer claim value (for JWT verification)
+            introspection_uri: Full URL to the introspection endpoint (for opaque tokens)
+            client_id: OAuth client ID (required for introspection)
+            client_secret: OAuth client secret (required for introspection)
             cache_ttl: Time-to-live for cached tokens in seconds (default: 3600)
         """
         self.nextcloud_host = nextcloud_host.rstrip("/")
         self.userinfo_uri = userinfo_uri
+        self.jwks_uri = jwks_uri
+        self.issuer = issuer
+        self.introspection_uri = introspection_uri
+        self.client_id = client_id
+        self.client_secret = client_secret
         self.cache_ttl = cache_ttl
 
         # Cache: token -> (userinfo, expiry_timestamp)
         self._token_cache: dict[str, tuple[dict[str, Any], float]] = {}
 
-        # HTTP client for userinfo requests
+        # HTTP client for userinfo/introspection requests
         self._client = httpx.AsyncClient(timeout=10.0)
 
+        # PyJWKClient for JWT verification (lazy initialization)
+        self._jwks_client: PyJWKClient | None = None
+        if jwks_uri:
+            logger.info(f"JWT verification enabled with JWKS URI: {jwks_uri}")
+            self._jwks_client = PyJWKClient(jwks_uri, cache_keys=True)
+
+        # Introspection support
+        if introspection_uri and client_id and client_secret:
+            logger.info(f"Token introspection enabled: {introspection_uri}")
+        elif introspection_uri:
+            logger.warning(
+                "Introspection URI provided but missing client credentials - introspection disabled"
+            )
+
     async def verify_token(self, token: str) -> AccessToken | None:
         """
-        Verify a bearer token by calling the userinfo endpoint.
+        Verify a bearer token using JWT verification, introspection, or userinfo endpoint.
 
         This method:
         1. Checks the cache first for recent validations
-        2. Calls the userinfo endpoint if not cached
-        3. Returns AccessToken with username stored in metadata
+        2. Attempts JWT verification if JWKS is configured and token looks like JWT
+        3. Falls back to introspection for opaque tokens (if configured)
+        4. Falls back to userinfo endpoint as last resort
+        5. Returns AccessToken with username and scopes
 
         Args:
             token: The bearer token to verify
@@ -69,13 +108,232 @@ class NextcloudTokenVerifier(TokenVerifier):
             logger.debug("Token found in cache")
             return cached
 
-        # Validate via userinfo endpoint
+        # Try JWT verification first if enabled and token looks like JWT
+        is_jwt_format = self._is_jwt_format(token)
+        logger.debug(
+            f"Token format check: is_jwt_format={is_jwt_format}, _jwks_client={self._jwks_client is not None}"
+        )
+        if self._jwks_client and is_jwt_format:
+            logger.debug("Attempting JWT verification...")
+            jwt_result = self._verify_jwt(token)
+            if jwt_result:
+                logger.info("Token validated via JWT verification")
+                return jwt_result
+            else:
+                logger.warning("JWT verification failed, will try other methods")
+
+        # For opaque tokens, try introspection if available
+        if self.introspection_uri and self.client_id and self.client_secret:
+            logger.debug("Attempting token introspection...")
+            try:
+                introspection_result = await self._verify_via_introspection(token)
+                if introspection_result:
+                    logger.info("Token validated via introspection")
+                    return introspection_result
+            except Exception as e:
+                logger.warning(f"Introspection failed: {e}")
+
+        # Fall back to userinfo endpoint validation (last resort)
+        logger.debug("Attempting userinfo endpoint validation...")
         try:
             return await self._verify_via_userinfo(token)
         except Exception as e:
             logger.warning(f"Token verification failed: {e}")
             return None
 
+    def _is_jwt_format(self, token: str) -> bool:
+        """
+        Check if token looks like a JWT (has 3 parts separated by dots).
+
+        Args:
+            token: The token to check
+
+        Returns:
+            True if token appears to be JWT format
+        """
+        return "." in token and token.count(".") == 2
+
+    def _verify_jwt(self, token: str) -> AccessToken | None:
+        """
+        Verify JWT token with signature validation using JWKS.
+
+        Args:
+            token: The JWT token to verify
+
+        Returns:
+            AccessToken if valid, None if invalid
+        """
+        try:
+            # Get signing key from JWKS
+            signing_key = self._jwks_client.get_signing_key_from_jwt(token)
+
+            # Verify and decode JWT
+            payload = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256"],
+                issuer=self.issuer,
+                options={
+                    "verify_signature": True,
+                    "verify_exp": True,
+                    "verify_iat": True,
+                    "verify_iss": True if self.issuer else False,
+                    "verify_aud": False,  # Skip audience validation for Bearer tokens
+                },
+            )
+
+            logger.debug(f"JWT verified successfully for user: {payload.get('sub')}")
+            logger.debug(f"Full JWT payload: {payload}")
+
+            # Extract username (sub claim)
+            username = payload.get("sub")
+            if not username:
+                logger.error("No 'sub' claim found in JWT payload")
+                return None
+
+            # Extract scopes from scope claim (space-separated string)
+            scope_string = payload.get("scope", "")
+            scopes = scope_string.split() if scope_string else []
+            logger.debug(
+                f"Extracted scopes from JWT - scope claim: '{scope_string}' -> scopes list: {scopes}"
+            )
+
+            # Extract expiration
+            exp = payload.get("exp")
+            if not exp:
+                logger.warning("No 'exp' claim in JWT, using default TTL")
+                exp = int(time.time() + self.cache_ttl)
+
+            # Cache the result
+            userinfo = {
+                "sub": username,
+                "scope": scope_string,
+                **{k: v for k, v in payload.items() if k not in ["sub", "scope"]},
+            }
+            self._token_cache[token] = (userinfo, exp)
+
+            return AccessToken(
+                token=token,
+                client_id=payload.get("client_id", ""),
+                scopes=scopes,
+                expires_at=exp,
+                resource=username,  # Store username in resource field (RFC 8707)
+            )
+
+        except jwt.ExpiredSignatureError:
+            logger.info("JWT token has expired")
+            return None
+        except jwt.InvalidIssuerError as e:
+            logger.warning(f"JWT issuer validation failed: {e}")
+            return None
+        except jwt.InvalidTokenError as e:
+            logger.warning(f"JWT validation failed: {e}")
+            return None
+        except Exception as e:
+            logger.error(f"Unexpected error during JWT verification: {e}")
+            return None
+
+    async def _verify_via_introspection(self, token: str) -> AccessToken | None:
+        """
+        Validate token by calling the introspection endpoint (RFC 7662).
+
+        This method validates opaque tokens and retrieves their scopes.
+
+        Args:
+            token: The bearer token to introspect
+
+        Returns:
+            AccessToken if active, None if inactive or invalid
+        """
+        try:
+            # Introspection requires client authentication
+            response = await self._client.post(
+                self.introspection_uri,
+                data={"token": token},
+                auth=(self.client_id, self.client_secret),
+            )
+
+            if response.status_code == 200:
+                introspection_data = response.json()
+
+                # Check if token is active
+                if not introspection_data.get("active", False):
+                    logger.info("Token introspection returned inactive=false")
+                    return None
+
+                logger.debug(
+                    f"Token introspected successfully for user: {introspection_data.get('sub')}"
+                )
+
+                # Extract username
+                username = introspection_data.get("sub") or introspection_data.get(
+                    "username"
+                )
+                if not username:
+                    logger.error("No username found in introspection response")
+                    return None
+
+                # Extract scopes (space-separated string)
+                scope_string = introspection_data.get("scope", "")
+                scopes = scope_string.split() if scope_string else []
+                logger.debug(f"Extracted scopes from introspection: {scopes}")
+
+                # Extract expiration
+                exp = introspection_data.get("exp")
+                if exp:
+                    expiry = float(exp)
+                else:
+                    logger.warning(
+                        "No 'exp' in introspection response, using default TTL"
+                    )
+                    expiry = time.time() + self.cache_ttl
+
+                # Cache the result
+                cache_data = {
+                    "sub": username,
+                    "scope": scope_string,
+                    **{
+                        k: v
+                        for k, v in introspection_data.items()
+                        if k not in ["sub", "scope", "active"]
+                    },
+                }
+                self._token_cache[token] = (cache_data, expiry)
+
+                return AccessToken(
+                    token=token,
+                    client_id=introspection_data.get("client_id", ""),
+                    scopes=scopes,
+                    expires_at=int(expiry),
+                    resource=username,
+                )
+
+            elif response.status_code in (400, 401, 403):
+                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"Response: {response.text[:200] if response.text else 'empty'}"
+                )
+                return None
+
+        except httpx.TimeoutException:
+            logger.error("Timeout while introspecting token")
+            return None
+        except httpx.RequestError as e:
+            logger.error(f"Network error while introspecting token: {e}")
+            return None
+        except Exception as e:
+            logger.error(f"Unexpected error during token introspection: {e}")
+            return None
+
     async def _verify_via_userinfo(self, token: str) -> AccessToken | None:
         """
         Validate token by calling the userinfo endpoint.
@@ -169,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:
@@ -194,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/client/__init__.py

@@ -9,7 +9,6 @@ from httpx import (
     BasicAuth,
     Request,
     Response,
-    Timeout,
 )
 
 from ..controllers.notes_search import NotesSearchController
@@ -21,8 +20,8 @@ from .groups import GroupsClient
 from .notes import NotesClient
 from .sharing import SharingClient
 from .tables import TablesClient
-from .webdav import WebDAVClient
 from .users import UsersClient
+from .webdav import WebDAVClient
 
 logger = logging.getLogger(__name__)
 
@@ -67,16 +66,15 @@ class NextcloudClient:
             auth=auth,
             transport=AsyncDisableCookieTransport(AsyncHTTPTransport()),
             event_hooks={"request": [log_request], "response": [log_response]},
-            timeout=Timeout(
-                30.0
-            ),  # 30 second timeout for all operations including recipe imports
         )
 
         # Initialize app clients
         self.notes = NotesClient(self._client, username)
         self.webdav = WebDAVClient(self._client, username)
         self.tables = TablesClient(self._client, username)
-        self.calendar = CalendarClient(self._client, username)
+        self.calendar = CalendarClient(
+            base_url, username, auth
+        )  # Uses AsyncDavClient internally
         self.contacts = ContactsClient(self._client, username)
         self.cookbook = CookbookClient(self._client, username)
         self.deck = DeckClient(self._client, username)
@@ -125,13 +123,14 @@ class NextcloudClient:
 
     async def notes_search_notes(self, *, query: str):
         """Search notes using token-based matching with relevance ranking."""
-        all_notes = await self.notes.get_all_notes()
-        return self._notes_search.search_notes(all_notes, query)
+        all_notes = self.notes.get_all_notes()
+        return await self._notes_search.search_notes(all_notes, query)
 
     def _get_webdav_base_path(self) -> str:
         """Helper to get the base WebDAV path for the authenticated user."""
         return f"/remote.php/dav/files/{self.username}"
 
     async def close(self):
-        """Close the HTTP client."""
+        """Close the HTTP client and CalDAV client."""
         await self._client.aclose()
+        await self.calendar.close()

nextcloud_mcp_server/client/cookbook.py

@@ -3,6 +3,8 @@
 import logging
 from typing import Any, Dict, List
 
+from httpx import Timeout
+
 from .base import BaseNextcloudClient
 
 logger = logging.getLogger(__name__)
@@ -127,7 +129,10 @@ class CookbookClient(BaseNextcloudClient):
         """
         logger.info(f"Importing recipe from URL: {url}")
         response = await self._make_request(
-            "POST", "/apps/cookbook/api/v1/import", json={"url": url}
+            "POST",
+            "/apps/cookbook/api/v1/import",
+            json={"url": url},
+            timeout=Timeout(300.0),
         )
         return response.json()
 

nextcloud_mcp_server/client/notes.py

@@ -1,7 +1,7 @@
 """Client for Nextcloud Notes app operations."""
 
 import logging
-from typing import Any, Dict, List, Optional
+from typing import Any, AsyncIterator, Dict, Optional
 
 from .base import BaseNextcloudClient
 
@@ -16,24 +16,22 @@ class NotesClient(BaseNextcloudClient):
         response = await self._make_request("GET", "/apps/notes/api/v1/settings")
         return response.json()
 
-    async def get_all_notes(self) -> List[Dict[str, Any]]:
-        """Get all notes."""
-        notes = []
+    async def get_all_notes(self) -> AsyncIterator[Dict[str, Any]]:
+        """Get all notes, yielding them one at a time."""
         cursor = ""
 
         while True:
             response = await self._make_request(
                 "GET",
                 "/apps/notes/api/v1/notes",
-                params={"chunkSize": 50, "chunkCursor": cursor},
+                params={"chunkSize": 10, "chunkCursor": cursor},
             )
-            notes.extend(response.json())
+            for note in response.json():
+                yield note
             if "X-Notes-Chunk-Cursor" not in response.headers:
                 break
             cursor = response.headers["X-Notes-Chunk-Cursor"]
 
-        return notes
-
     async def get_note(self, note_id: int) -> Dict[str, Any]:
         """Get a specific note by ID."""
         response = await self._make_request(

nextcloud_mcp_server/client/users.py

@@ -1,4 +1,5 @@
-from typing import List, Optional, Dict
+from typing import Dict, List, Optional
+
 from nextcloud_mcp_server.client.base import BaseNextcloudClient
 from nextcloud_mcp_server.models.users import UserDetails
 

nextcloud_mcp_server/client/webdav.py

@@ -570,3 +570,379 @@ class WebDAVClient(BaseNextcloudClient):
                 f"Unexpected error copying resource from '{source_path}' to '{destination_path}': {e}"
             )
             raise e
+
+    async def search_files(
+        self,
+        scope: str = "",
+        where_conditions: Optional[str] = None,
+        properties: Optional[List[str]] = None,
+        order_by: Optional[List[Tuple[str, str]]] = None,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """Search for files using WebDAV SEARCH method (RFC 5323).
+
+        Args:
+            scope: Directory path to search in (empty string for user root)
+            where_conditions: XML string for where clause conditions
+            properties: List of property names to retrieve (defaults to basic set)
+            order_by: List of (property, direction) tuples for sorting, e.g. [("getlastmodified", "descending")]
+            limit: Maximum number of results to return
+
+        Returns:
+            List of file/directory dictionaries with requested properties
+        """
+        # Default properties if not specified
+        if properties is None:
+            properties = [
+                "displayname",
+                "getcontentlength",
+                "getcontenttype",
+                "getlastmodified",
+                "resourcetype",
+                "getetag",
+            ]
+
+        # Build the SEARCH request XML
+        search_body = self._build_search_xml(
+            scope=scope,
+            where_conditions=where_conditions,
+            properties=properties,
+            order_by=order_by,
+            limit=limit,
+        )
+
+        # The SEARCH endpoint is at the dav root
+        search_path = "/remote.php/dav/"
+
+        headers = {"Content-Type": "text/xml", "OCS-APIRequest": "true"}
+
+        logger.debug(f"Searching files in scope: {scope}")
+
+        try:
+            response = await self._make_request(
+                "SEARCH", search_path, content=search_body, headers=headers
+            )
+            response.raise_for_status()
+
+            # Parse the XML response
+            results = self._parse_search_response(response.content, scope)
+
+            logger.debug(f"Search returned {len(results)} results")
+            return results
+
+        except HTTPStatusError as e:
+            logger.error(f"HTTP error during search: {e}")
+            raise e
+        except Exception as e:
+            logger.error(f"Unexpected error during search: {e}")
+            raise e
+
+    def _build_search_xml(
+        self,
+        scope: str,
+        where_conditions: Optional[str],
+        properties: List[str],
+        order_by: Optional[List[Tuple[str, str]]],
+        limit: Optional[int],
+    ) -> str:
+        """Build the XML body for a SEARCH request."""
+        # Construct the scope path
+        username = self.username
+        scope_path = f"/files/{username}"
+        if scope:
+            scope_path = f"{scope_path}/{scope.lstrip('/')}"
+
+        # Build property list
+        prop_xml = "\n".join([self._property_to_xml(prop) for prop in properties])
+
+        # Build where clause
+        where_xml = where_conditions if where_conditions else ""
+
+        # Build order by clause
+        orderby_xml = ""
+        if order_by:
+            order_elements = []
+            for prop, direction in order_by:
+                prop_element = self._property_to_xml(prop)
+                dir_element = (
+                    "<d:ascending/>"
+                    if direction.lower() == "ascending"
+                    else "<d:descending/>"
+                )
+                order_elements.append(f"<d:order>{prop_element}{dir_element}</d:order>")
+            orderby_xml = "\n".join(order_elements)
+        else:
+            orderby_xml = ""
+
+        # Build limit clause
+        limit_xml = (
+            f"<d:limit><d:nresults>{limit}</d:nresults></d:limit>" if limit else ""
+        )
+
+        # Construct the full SEARCH XML
+        search_xml = f"""<?xml version="1.0" encoding="UTF-8"?>
+<d:searchrequest xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
+    <d:basicsearch>
+        <d:select>
+            <d:prop>
+                {prop_xml}
+            </d:prop>
+        </d:select>
+        <d:from>
+            <d:scope>
+                <d:href>{scope_path}</d:href>
+                <d:depth>infinity</d:depth>
+            </d:scope>
+        </d:from>
+        <d:where>
+            {where_xml}
+        </d:where>
+        <d:orderby>
+            {orderby_xml}
+        </d:orderby>
+        {limit_xml}
+    </d:basicsearch>
+</d:searchrequest>"""
+
+        return search_xml
+
+    def _property_to_xml(self, prop: str) -> str:
+        """Convert a property name to its XML element."""
+        # Handle properties with namespace prefixes
+        if prop.startswith("{"):
+            # Already a full namespace
+            namespace_end = prop.index("}")
+            namespace = prop[1:namespace_end]
+            local_name = prop[namespace_end + 1 :]
+
+            # Map namespace URIs to prefixes
+            ns_map = {
+                "DAV:": "d",
+                "http://owncloud.org/ns": "oc",
+                "http://nextcloud.org/ns": "nc",
+            }
+
+            prefix = ns_map.get(namespace, "d")
+            return f"<{prefix}:{local_name}/>"
+        else:
+            # Guess namespace based on common properties
+            if prop in [
+                "displayname",
+                "getcontentlength",
+                "getcontenttype",
+                "getlastmodified",
+                "resourcetype",
+                "getetag",
+                "quota-available-bytes",
+                "quota-used-bytes",
+            ]:
+                return f"<d:{prop}/>"
+            elif prop in [
+                "fileid",
+                "size",
+                "permissions",
+                "favorite",
+                "tags",
+                "owner-id",
+                "owner-display-name",
+                "share-types",
+                "checksums",
+                "comments-count",
+                "comments-unread",
+            ]:
+                return f"<oc:{prop}/>"
+            else:
+                # Assume nc namespace for newer properties
+                return f"<nc:{prop}/>"
+
+    def _parse_search_response(
+        self, xml_content: bytes, scope: str
+    ) -> List[Dict[str, Any]]:
+        """Parse the XML response from a SEARCH request."""
+        root = ET.fromstring(xml_content)
+        items = []
+
+        # Process each response element
+        responses = root.findall(".//{DAV:}response")
+
+        for response_elem in responses:
+            href = response_elem.find(".//{DAV:}href")
+            if href is None:
+                continue
+
+            # Extract file/directory path from href
+            href_text = href.text or ""
+            # Remove the /remote.php/dav/files/username/ prefix to get relative path
+            path_parts = href_text.split("/files/")
+            if len(path_parts) > 1:
+                # Get the path after username
+                path_after_user = "/".join(path_parts[1].split("/")[1:])
+                relative_path = path_after_user.rstrip("/")
+            else:
+                relative_path = href_text.rstrip("/").split("/")[-1]
+
+            # Get properties
+            propstat = response_elem.find(".//{DAV:}propstat")
+            if propstat is None:
+                continue
+
+            prop = propstat.find(".//{DAV:}prop")
+            if prop is None:
+                continue
+
+            # Build item dictionary
+            item = {"path": relative_path, "href": href_text}
+
+            # Extract all properties
+            for child in prop:
+                tag = child.tag
+                value = child.text
+
+                # Remove namespace from tag
+                if "}" in tag:
+                    tag = tag.split("}", 1)[1]
+
+                # Handle special properties
+                if tag == "resourcetype":
+                    item["is_directory"] = child.find(".//{DAV:}collection") is not None
+                elif tag == "getcontentlength":
+                    item["size"] = int(value) if value else 0
+                elif tag == "displayname":
+                    item["name"] = value
+                elif tag == "getcontenttype":
+                    item["content_type"] = value
+                elif tag == "getlastmodified":
+                    item["last_modified"] = value
+                elif tag == "getetag":
+                    item["etag"] = value.strip('"') if value else None
+                elif tag == "fileid":
+                    item["file_id"] = int(value) if value else None
+                elif tag == "favorite":
+                    item["is_favorite"] = value == "1"
+                elif tag == "permissions":
+                    item["permissions"] = value
+                elif tag == "size":
+                    # oc:size includes folder sizes
+                    item["total_size"] = int(value) if value else 0
+                else:
+                    # Store other properties as-is
+                    item[tag] = value
+
+            items.append(item)
+
+        return items
+
+    async def find_by_name(
+        self, pattern: str, scope: str = "", limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Find files by name pattern using LIKE matching.
+
+        Args:
+            pattern: Name pattern to search for (supports % wildcard)
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            List of matching files/directories
+
+        Examples:
+            # Find all .txt files
+            results = await find_by_name("%.txt")
+
+            # Find files starting with "report"
+            results = await find_by_name("report%")
+        """
+        where_conditions = f"""
+            <d:like>
+                <d:prop>
+                    <d:displayname/>
+                </d:prop>
+                <d:literal>{pattern}</d:literal>
+            </d:like>
+        """
+
+        return await self.search_files(
+            scope=scope, where_conditions=where_conditions, limit=limit
+        )
+
+    async def find_by_type(
+        self, mime_type: str, scope: str = "", limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Find files by MIME type.
+
+        Args:
+            mime_type: MIME type to search for (supports % wildcard, e.g., "image/%")
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            List of matching files
+
+        Examples:
+            # Find all images
+            results = await find_by_type("image/%")
+
+            # Find all PDFs
+            results = await find_by_type("application/pdf")
+        """
+        where_conditions = f"""
+            <d:like>
+                <d:prop>
+                    <d:getcontenttype/>
+                </d:prop>
+                <d:literal>{mime_type}</d:literal>
+            </d:like>
+        """
+
+        return await self.search_files(
+            scope=scope, where_conditions=where_conditions, limit=limit
+        )
+
+    async def list_favorites(
+        self, scope: str = "", limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """List all favorite files.
+
+        Args:
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            List of favorite files/directories
+
+        Examples:
+            # List all favorites
+            results = await list_favorites()
+
+            # List favorites in a specific folder
+            results = await list_favorites(scope="Documents")
+        """
+        # Use REPORT method for favorites as it's more efficient
+        # But we can also use SEARCH as fallback
+        where_conditions = """
+            <d:eq>
+                <d:prop>
+                    <oc:favorite/>
+                </d:prop>
+                <d:literal>1</d:literal>
+            </d:eq>
+        """
+
+        # Request favorite property
+        properties = [
+            "displayname",
+            "getcontentlength",
+            "getcontenttype",
+            "getlastmodified",
+            "resourcetype",
+            "getetag",
+            "fileid",
+            "favorite",
+        ]
+
+        return await self.search_files(
+            scope=scope,
+            where_conditions=where_conditions,
+            properties=properties,
+            limit=limit,
+        )

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/controllers/notes_search.py

@@ -1,13 +1,13 @@
 """Controller for notes search functionality."""
 
-from typing import Any, Dict, List
+from typing import Any, AsyncIterable, Dict, List
 
 
 class NotesSearchController:
     """Handles notes search logic and scoring."""
 
-    def search_notes(
-        self, notes: List[Dict[str, Any]], query: str
+    async def search_notes(
+        self, notes: AsyncIterable[Dict[str, Any]], query: str
     ) -> List[Dict[str, Any]]:
         """
         Search notes using token-based matching with relevance ranking.
@@ -21,7 +21,7 @@ class NotesSearchController:
             return []
 
         # Process and score each note
-        for note in notes:
+        async for note in notes:
             title_tokens, content_tokens = self._process_note_content(note)
             score = self._calculate_score(query_tokens, title_tokens, content_tokens)
 

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/__init__.py

@@ -65,11 +65,14 @@ from .tables import (
 
 # WebDAV models
 from .webdav import (
+    CopyResourceResponse,
     CreateDirectoryResponse,
     DeleteResourceResponse,
     DirectoryListing,
     FileInfo,
+    MoveResourceResponse,
     ReadFileResponse,
+    SearchFilesResponse,
     WriteFileResponse,
 )
 
@@ -133,4 +136,7 @@ __all__ = [
     "WriteFileResponse",
     "CreateDirectoryResponse",
     "DeleteResourceResponse",
+    "MoveResourceResponse",
+    "CopyResourceResponse",
+    "SearchFilesResponse",
 ]

nextcloud_mcp_server/models/calendar.py

@@ -180,3 +180,71 @@ class ManageCalendarResponse(BaseResponse):
         None, description="List of calendars (for list action)"
     )
     message: str = Field(description="Success message")
+
+
+# ============= Todo/Task Models =============
+
+
+class Todo(BaseModel):
+    """Model for a CalDAV todo/task (VTODO)."""
+
+    uid: str = Field(description="Todo UID")
+    summary: str = Field(description="Todo summary/title")
+    description: str = Field(default="", description="Todo description")
+    status: str = Field(
+        default="NEEDS-ACTION",
+        description="Todo status: NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED",
+    )
+    priority: int = Field(
+        default=0, description="Todo priority (0=undefined, 1=highest, 9=lowest)"
+    )
+    percent_complete: int = Field(default=0, description="Percentage complete (0-100)")
+    due: Optional[str] = Field(None, description="Due date/time (ISO format)")
+    dtstart: Optional[str] = Field(None, description="Start date/time (ISO format)")
+    completed: Optional[str] = Field(
+        None, description="Completion timestamp (ISO format)"
+    )
+    categories: str = Field(default="", description="Comma-separated categories")
+    href: str = Field(default="", description="CalDAV href")
+    etag: str = Field(default="", description="ETag for versioning")
+    calendar_name: Optional[str] = Field(
+        None, description="Calendar containing this todo"
+    )
+    calendar_display_name: Optional[str] = Field(
+        None, description="Display name of calendar containing this todo"
+    )
+
+
+class ListTodosResponse(BaseResponse):
+    """Response model for listing todos."""
+
+    todos: List[Todo] = Field(description="List of todos/tasks")
+    calendar_name: Optional[str] = Field(
+        None, description="Calendar name (if filtered to one calendar)"
+    )
+    total_count: int = Field(description="Total number of todos found")
+
+
+class CreateTodoResponse(BaseResponse):
+    """Response model for todo creation."""
+
+    todo: Todo = Field(description="The created todo")
+    calendar_name: str = Field(
+        description="Name of the calendar the todo was created in"
+    )
+
+
+class UpdateTodoResponse(BaseResponse):
+    """Response model for todo updates."""
+
+    todo: Todo = Field(description="The updated todo")
+    calendar_name: str = Field(description="Name of the calendar the todo belongs to")
+
+
+class DeleteTodoResponse(StatusResponse):
+    """Response model for todo deletion."""
+
+    deleted_uid: str = Field(description="UID of the deleted todo")
+    calendar_name: str = Field(
+        description="Name of the calendar the todo was deleted from"
+    )

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/users.py

@@ -1,4 +1,5 @@
 from typing import Any, Dict, List, Optional, Union
+
 from pydantic import BaseModel, ConfigDict, Field
 
 

nextcloud_mcp_server/models/webdav.py

@@ -22,6 +22,8 @@ class FileInfo(BaseModel):
         None, description="Last modification time (ISO format)"
     )
     etag: Optional[str] = Field(None, description="ETag for versioning")
+    file_id: Optional[int] = Field(None, description="Nextcloud file ID")
+    is_favorite: Optional[bool] = Field(None, description="Whether file is favorited")
 
     @property
     def last_modified_datetime(self) -> Optional[datetime]:
@@ -38,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")
@@ -106,3 +108,14 @@ class CopyResourceResponse(StatusResponse):
     overwrite: bool = Field(
         description="Whether the destination was overwritten if it existed"
     )
+
+
+class SearchFilesResponse(BaseResponse):
+    """Response model for WebDAV search operations."""
+
+    results: List[FileInfo] = Field(description="Search results")
+    total_found: int = Field(description="Total number of files found")
+    scope: str = Field(description="The scope/path that was searched")
+    filters_applied: Optional[dict] = Field(
+        None, description="Filters that were applied to the search"
+    )

nextcloud_mcp_server/server/calendar.py

@@ -4,8 +4,14 @@ from typing import Optional
 
 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.calendar import Calendar, ListCalendarsResponse
+from nextcloud_mcp_server.models.calendar import (
+    Calendar,
+    ListCalendarsResponse,
+    ListTodosResponse,
+    Todo,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -13,6 +19,7 @@ logger = logging.getLogger(__name__)
 def configure_calendar_tools(mcp: FastMCP):
     # Calendar tools
     @mcp.tool()
+    @require_scopes("calendar:read")
     async def nc_calendar_list_calendars(ctx: Context) -> ListCalendarsResponse:
         """List all available calendars for the user"""
         client = get_client(ctx)
@@ -22,6 +29,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return ListCalendarsResponse(calendars=calendars, total_count=len(calendars))
 
     @mcp.tool()
+    @require_scopes("calendar:write")
     async def nc_calendar_create_event(
         calendar_name: str,
         title: str,
@@ -97,6 +105,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return await client.calendar.create_event(calendar_name, event_data)
 
     @mcp.tool()
+    @require_scopes("calendar:read")
     async def nc_calendar_list_events(
         calendar_name: str,
         ctx: Context,
@@ -198,6 +207,7 @@ def configure_calendar_tools(mcp: FastMCP):
             return events
 
     @mcp.tool()
+    @require_scopes("calendar:read")
     async def nc_calendar_get_event(
         calendar_name: str,
         event_uid: str,
@@ -209,6 +219,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return event_data
 
     @mcp.tool()
+    @require_scopes("calendar:write")
     async def nc_calendar_update_event(
         calendar_name: str,
         event_uid: str,
@@ -281,6 +292,7 @@ def configure_calendar_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("calendar:write")
     async def nc_calendar_delete_event(
         calendar_name: str,
         event_uid: str,
@@ -291,6 +303,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return await client.calendar.delete_event(calendar_name, event_uid)
 
     @mcp.tool()
+    @require_scopes("calendar:write")
     async def nc_calendar_create_meeting(
         title: str,
         date: str,
@@ -356,6 +369,7 @@ def configure_calendar_tools(mcp: FastMCP):
         return await client.calendar.create_event(calendar_name, event_data)
 
     @mcp.tool()
+    @require_scopes("calendar:read")
     async def nc_calendar_get_upcoming_events(
         ctx: Context,
         calendar_name: str = "",  # Empty = all calendars
@@ -405,6 +419,7 @@ def configure_calendar_tools(mcp: FastMCP):
             return all_events[:limit]
 
     @mcp.tool()
+    @require_scopes("calendar:read")
     async def nc_calendar_find_availability(
         duration_minutes: int,
         ctx: Context,
@@ -484,6 +499,7 @@ def configure_calendar_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("calendar:write")
     async def nc_calendar_bulk_operations(
         operation: str,  # "update", "delete", "move"
         ctx: Context,
@@ -732,6 +748,7 @@ def configure_calendar_tools(mcp: FastMCP):
             }
 
     @mcp.tool()
+    @require_scopes("calendar:write")
     async def nc_calendar_manage_calendar(
         action: str,  # "create", "delete", "update", "list"
         ctx: Context,
@@ -796,3 +813,214 @@ def configure_calendar_tools(mcp: FastMCP):
 
         else:
             raise ValueError("Action must be 'create', 'delete', 'update', or 'list'")
+
+    # ============= Todo/Task Tools =============
+
+    @mcp.tool()
+    @require_scopes("todo:read", "calendar:read")
+    async def nc_calendar_list_todos(
+        calendar_name: str,
+        ctx: Context,
+        status: Optional[str] = None,
+        min_priority: Optional[int] = None,
+        categories: Optional[str] = None,
+        summary_contains: Optional[str] = None,
+    ) -> ListTodosResponse:
+        """List todos/tasks in a calendar with optional filtering.
+
+        Args:
+            calendar_name: Name of the calendar to list todos from
+            ctx: MCP context
+            status: Filter by status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
+            min_priority: Filter by minimum priority (1=highest, 9=lowest)
+            categories: Filter by categories (comma-separated, e.g., "work,urgent")
+            summary_contains: Filter todos where summary contains this text
+
+        Returns:
+            List of todos matching the filters
+        """
+        client = get_client(ctx)
+
+        # Build filters dictionary
+        filters = {}
+        if status is not None:
+            filters["status"] = status
+        if min_priority is not None:
+            filters["min_priority"] = min_priority
+        if categories is not None:
+            filters["categories"] = [cat.strip() for cat in categories.split(",")]
+        if summary_contains is not None:
+            filters["summary_contains"] = summary_contains
+
+        todos_data = await client.calendar.list_todos(
+            calendar_name, filters if filters else None
+        )
+
+        todos = [Todo(**todo_data) for todo_data in todos_data]
+        return ListTodosResponse(
+            todos=todos, calendar_name=calendar_name, total_count=len(todos)
+        )
+
+    @mcp.tool()
+    @require_scopes("todo:write", "calendar:read")
+    async def nc_calendar_create_todo(
+        calendar_name: str,
+        summary: str,
+        ctx: Context,
+        description: str = "",
+        status: str = "NEEDS-ACTION",
+        priority: int = 0,
+        due: str = "",
+        dtstart: str = "",
+        categories: str = "",
+    ):
+        """Create a new todo/task in a calendar.
+
+        Args:
+            calendar_name: Name of the calendar to create the todo in
+            summary: Todo title/summary
+            ctx: MCP context
+            description: Detailed description of the todo
+            status: Todo status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
+            priority: Priority (0=undefined, 1=highest, 9=lowest)
+            due: Due date/time (ISO format, e.g., "2025-01-15T14:00:00")
+            dtstart: Start date/time (ISO format)
+            categories: Comma-separated categories (e.g., "work,urgent")
+
+        Returns:
+            Dict with todo creation result
+        """
+        client = get_client(ctx)
+
+        todo_data = {
+            "summary": summary,
+            "description": description,
+            "status": status,
+            "priority": priority,
+            "due": due,
+            "dtstart": dtstart,
+            "categories": categories,
+        }
+
+        return await client.calendar.create_todo(calendar_name, todo_data)
+
+    @mcp.tool()
+    @require_scopes("todo:write", "calendar:read")
+    async def nc_calendar_update_todo(
+        calendar_name: str,
+        todo_uid: str,
+        ctx: Context,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        status: Optional[str] = None,
+        priority: Optional[int] = None,
+        percent_complete: Optional[int] = None,
+        due: Optional[str] = None,
+        dtstart: Optional[str] = None,
+        completed: Optional[str] = None,
+        categories: Optional[str] = None,
+    ):
+        """Update an existing todo/task.
+
+        Args:
+            calendar_name: Name of the calendar containing the todo
+            todo_uid: UID of the todo to update
+            ctx: MCP context
+            summary: New summary/title
+            description: New description
+            status: New status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
+            priority: New priority (0-9)
+            percent_complete: New completion percentage (0-100)
+            due: New due date/time (ISO format)
+            dtstart: New start date/time (ISO format)
+            completed: Completion timestamp (ISO format)
+            categories: New categories (comma-separated)
+
+        Returns:
+            Dict with todo update result
+        """
+        client = get_client(ctx)
+
+        # Build update data with only non-None values
+        todo_data = {}
+        if summary is not None:
+            todo_data["summary"] = summary
+        if description is not None:
+            todo_data["description"] = description
+        if status is not None:
+            todo_data["status"] = status
+        if priority is not None:
+            todo_data["priority"] = priority
+        if percent_complete is not None:
+            todo_data["percent_complete"] = percent_complete
+        if due is not None:
+            todo_data["due"] = due
+        if dtstart is not None:
+            todo_data["dtstart"] = dtstart
+        if completed is not None:
+            todo_data["completed"] = completed
+        if categories is not None:
+            todo_data["categories"] = categories
+
+        return await client.calendar.update_todo(calendar_name, todo_uid, todo_data)
+
+    @mcp.tool()
+    @require_scopes("todo:write", "calendar:read")
+    async def nc_calendar_delete_todo(
+        calendar_name: str,
+        todo_uid: str,
+        ctx: Context,
+    ):
+        """Delete a todo/task from a calendar.
+
+        Args:
+            calendar_name: Name of the calendar containing the todo
+            todo_uid: UID of the todo to delete
+            ctx: MCP context
+
+        Returns:
+            Dict with deletion status
+        """
+        client = get_client(ctx)
+        return await client.calendar.delete_todo(calendar_name, todo_uid)
+
+    @mcp.tool()
+    @require_scopes("todo:read", "calendar:read")
+    async def nc_calendar_search_todos(
+        ctx: Context,
+        status: Optional[str] = None,
+        min_priority: Optional[int] = None,
+        categories: Optional[str] = None,
+        summary_contains: Optional[str] = None,
+    ):
+        """Search todos across all calendars with optional filtering.
+
+        Args:
+            ctx: MCP context
+            status: Filter by status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
+            min_priority: Filter by minimum priority (1=highest, 9=lowest)
+            categories: Filter by categories (comma-separated, e.g., "work,urgent")
+            summary_contains: Filter todos where summary contains this text
+
+        Returns:
+            List of todos matching the filters from all calendars
+        """
+        client = get_client(ctx)
+
+        # Build filters dictionary
+        filters = {}
+        if status is not None:
+            filters["status"] = status
+        if min_priority is not None:
+            filters["min_priority"] = min_priority
+        if categories is not None:
+            filters["categories"] = [cat.strip() for cat in categories.split(",")]
+        if summary_contains is not None:
+            filters["summary_contains"] = summary_contains
+
+        todos_data = await client.calendar.search_todos_across_calendars(
+            filters if filters else None
+        )
+
+        todos = [Todo(**todo_data) for todo_data in todos_data]
+        return ListTodosResponse(todos=todos, total_count=len(todos))

nextcloud_mcp_server/server/contacts.py

@@ -2,6 +2,7 @@ import logging
 
 from mcp.server.fastmcp import Context, FastMCP
 
+from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
 
 logger = logging.getLogger(__name__)
@@ -10,18 +11,21 @@ logger = logging.getLogger(__name__)
 def configure_contacts_tools(mcp: FastMCP):
     # Contacts tools
     @mcp.tool()
+    @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("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("contacts:write")
     async def nc_contacts_create_addressbook(
         ctx: Context, *, name: str, display_name: str
     ):
@@ -37,12 +41,14 @@ def configure_contacts_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @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("contacts:write")
     async def nc_contacts_create_contact(
         ctx: Context, *, addressbook: str, uid: str, contact_data: dict
     ):
@@ -59,12 +65,14 @@ def configure_contacts_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @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("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

@@ -5,6 +5,7 @@ from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
 from mcp.types import ErrorData
 
+from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models.cookbook import (
     Category,
@@ -70,6 +71,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @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.
 
@@ -126,6 +128,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:read")
     async def nc_cookbook_list_recipes(ctx: Context) -> ListRecipesResponse:
         """Get all recipes in the database"""
         client = get_client(ctx)
@@ -150,6 +153,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @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)
@@ -174,6 +178,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:write")
     async def nc_cookbook_create_recipe(
         name: str,
         description: str | None = None,
@@ -252,6 +257,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:write")
     async def nc_cookbook_update_recipe(
         recipe_id: int,
         name: str | None = None,
@@ -340,6 +346,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:write")
     async def nc_cookbook_delete_recipe(
         recipe_id: int, ctx: Context
     ) -> DeleteRecipeResponse:
@@ -374,6 +381,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:read")
     async def nc_cookbook_search_recipes(
         query: str, ctx: Context
     ) -> SearchRecipesResponse:
@@ -409,6 +417,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:read")
     async def nc_cookbook_list_categories(ctx: Context) -> ListCategoriesResponse:
         """Get all known categories.
 
@@ -435,6 +444,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:read")
     async def nc_cookbook_get_recipes_in_category(
         category: str, ctx: Context
     ) -> ListRecipesResponse:
@@ -470,6 +480,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:read")
     async def nc_cookbook_list_keywords(ctx: Context) -> ListKeywordsResponse:
         """Get all known keywords/tags"""
         client = get_client(ctx)
@@ -494,6 +505,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:read")
     async def nc_cookbook_get_recipes_with_keywords(
         keywords: list[str], ctx: Context
     ) -> ListRecipesResponse:
@@ -527,6 +539,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("cookbook:write")
     async def nc_cookbook_set_config(
         folder: str | None = None,
         update_interval: int | None = None,
@@ -569,6 +582,7 @@ def configure_cookbook_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @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

@@ -3,6 +3,7 @@ from typing import Optional
 
 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.deck import (
     CardOperationResponse,
@@ -116,6 +117,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Read Tools (converted from resources)
 
     @mcp.tool()
+    @require_scopes("deck:read")
     async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
         """Get all Nextcloud Deck boards"""
         client = get_client(ctx)
@@ -123,6 +125,7 @@ def configure_deck_tools(mcp: FastMCP):
         return boards
 
     @mcp.tool()
+    @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)
@@ -130,6 +133,7 @@ def configure_deck_tools(mcp: FastMCP):
         return board
 
     @mcp.tool()
+    @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)
@@ -137,6 +141,7 @@ def configure_deck_tools(mcp: FastMCP):
         return stacks
 
     @mcp.tool()
+    @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)
@@ -144,6 +149,7 @@ def configure_deck_tools(mcp: FastMCP):
         return stack
 
     @mcp.tool()
+    @require_scopes("deck:read")
     async def deck_get_cards(
         ctx: Context, board_id: int, stack_id: int
     ) -> list[DeckCard]:
@@ -155,6 +161,7 @@ def configure_deck_tools(mcp: FastMCP):
         return []
 
     @mcp.tool()
+    @require_scopes("deck:read")
     async def deck_get_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> DeckCard:
@@ -164,6 +171,7 @@ def configure_deck_tools(mcp: FastMCP):
         return card
 
     @mcp.tool()
+    @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)
@@ -171,6 +179,7 @@ def configure_deck_tools(mcp: FastMCP):
         return board.labels
 
     @mcp.tool()
+    @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)
@@ -180,6 +189,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Create/Update/Delete Tools
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_create_board(
         ctx: Context, title: str, color: str
     ) -> CreateBoardResponse:
@@ -196,6 +206,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Stack Tools
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_create_stack(
         ctx: Context, board_id: int, title: str, order: int
     ) -> CreateStackResponse:
@@ -211,6 +222,7 @@ def configure_deck_tools(mcp: FastMCP):
         return CreateStackResponse(id=stack.id, title=stack.title, order=stack.order)
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_update_stack(
         ctx: Context,
         board_id: int,
@@ -236,6 +248,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_delete_stack(
         ctx: Context, board_id: int, stack_id: int
     ) -> StackOperationResponse:
@@ -256,6 +269,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Card Tools
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_create_card(
         ctx: Context,
         board_id: int,
@@ -289,6 +303,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_update_card(
         ctx: Context,
         board_id: int,
@@ -341,6 +356,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_delete_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> CardOperationResponse:
@@ -362,6 +378,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_archive_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> CardOperationResponse:
@@ -383,6 +400,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_unarchive_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> CardOperationResponse:
@@ -404,6 +422,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_reorder_card(
         ctx: Context,
         board_id: int,
@@ -435,6 +454,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Label Tools
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_create_label(
         ctx: Context, board_id: int, title: str, color: str
     ) -> CreateLabelResponse:
@@ -450,6 +470,7 @@ def configure_deck_tools(mcp: FastMCP):
         return CreateLabelResponse(id=label.id, title=label.title, color=label.color)
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_update_label(
         ctx: Context,
         board_id: int,
@@ -475,6 +496,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("deck:write")
     async def deck_delete_label(
         ctx: Context, board_id: int, label_id: int
     ) -> LabelOperationResponse:
@@ -495,6 +517,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Card-Label Assignment Tools
     @mcp.tool()
+    @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:
@@ -517,6 +540,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @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:
@@ -540,6 +564,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Card-User Assignment Tools
     @mcp.tool()
+    @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:
@@ -562,6 +587,7 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @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

@@ -5,6 +5,7 @@ from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
 from mcp.types import ErrorData
 
+from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models.notes import (
     AppendContentResponse,
@@ -84,10 +85,11 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("notes:write")
     async def nc_notes_create_note(
         title: str, content: str, category: str, ctx: Context
     ) -> CreateNoteResponse:
-        """Create a new note"""
+        """Create a new note (requires notes:write scope)"""
         client = get_client(ctx)
         try:
             note_data = await client.notes.create_note(
@@ -129,6 +131,7 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("notes:write")
     async def nc_notes_update_note(
         note_id: int,
         etag: str,
@@ -137,7 +140,7 @@ def configure_notes_tools(mcp: FastMCP):
         category: str | None,
         ctx: Context,
     ) -> UpdateNoteResponse:
-        """Update an existing note's title, content, or category.
+        """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.
@@ -193,6 +196,7 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("notes:write")
     async def nc_notes_append_content(
         note_id: int, content: str, ctx: Context
     ) -> AppendContentResponse:
@@ -242,8 +246,9 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @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."""
+        """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)
@@ -287,8 +292,9 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("notes:read")
     async def nc_notes_get_note(note_id: int, ctx: Context) -> Note:
-        """Get a specific note by its ID"""
+        """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)
@@ -315,6 +321,7 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @require_scopes("notes:read")
     async def nc_notes_get_attachment(
         note_id: int, attachment_filename: str, ctx: Context
     ) -> dict[str, str]:
@@ -360,6 +367,7 @@ def configure_notes_tools(mcp: FastMCP):
                 )
 
     @mcp.tool()
+    @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

@@ -2,9 +2,11 @@
 
 import json
 
-from nextcloud_mcp_server.context import get_client
 from mcp.server.fastmcp import Context, FastMCP
 
+from nextcloud_mcp_server.auth import require_scopes
+from nextcloud_mcp_server.context import get_client
+
 
 def configure_sharing_tools(mcp: FastMCP):
     """Configure sharing-related MCP tools.
@@ -14,6 +16,7 @@ def configure_sharing_tools(mcp: FastMCP):
     """
 
     @mcp.tool()
+    @require_scopes("sharing:write")
     async def nc_share_create(
         path: str,
         share_with: str,
@@ -52,6 +55,7 @@ def configure_sharing_tools(mcp: FastMCP):
         return json.dumps(share_data, indent=2)
 
     @mcp.tool()
+    @require_scopes("sharing:write")
     async def nc_share_delete(share_id: int, ctx: Context) -> str:
         """Delete a share by its ID.
 
@@ -70,6 +74,7 @@ def configure_sharing_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("sharing:write")
     async def nc_share_get(share_id: int, ctx: Context) -> str:
         """Get information about a specific share.
 
@@ -87,6 +92,7 @@ def configure_sharing_tools(mcp: FastMCP):
         return json.dumps(share_data, indent=2)
 
     @mcp.tool()
+    @require_scopes("sharing:write")
     async def nc_share_list(
         ctx: Context, path: str | None = None, shared_with_me: bool = False
     ) -> str:
@@ -107,6 +113,7 @@ def configure_sharing_tools(mcp: FastMCP):
         return json.dumps(shares, indent=2)
 
     @mcp.tool()
+    @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

@@ -2,6 +2,7 @@ import logging
 
 from mcp.server.fastmcp import Context, FastMCP
 
+from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
 
 logger = logging.getLogger(__name__)
@@ -10,18 +11,21 @@ logger = logging.getLogger(__name__)
 def configure_tables_tools(mcp: FastMCP):
     # Tables tools
     @mcp.tool()
+    @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("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("tables:read")
     async def nc_tables_read_table(
         table_id: int,
         ctx: Context,
@@ -33,6 +37,7 @@ def configure_tables_tools(mcp: FastMCP):
         return await client.tables.get_table_rows(table_id, limit, offset)
 
     @mcp.tool()
+    @require_scopes("tables:write")
     async def nc_tables_insert_row(table_id: int, data: dict, ctx: Context):
         """Insert a new row into a table.
 
@@ -42,6 +47,7 @@ def configure_tables_tools(mcp: FastMCP):
         return await client.tables.create_row(table_id, data)
 
     @mcp.tool()
+    @require_scopes("tables:write")
     async def nc_tables_update_row(row_id: int, data: dict, ctx: Context):
         """Update an existing row in a table.
 
@@ -51,6 +57,7 @@ def configure_tables_tools(mcp: FastMCP):
         return await client.tables.update_row(row_id, data)
 
     @mcp.tool()
+    @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

@@ -2,7 +2,13 @@ import logging
 
 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 DirectoryListing, FileInfo, SearchFilesResponse
+from nextcloud_mcp_server.utils.document_parser import (
+    is_parseable_document,
+    parse_document,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -10,26 +16,40 @@ logger = logging.getLogger(__name__)
 def configure_webdav_tools(mcp: FastMCP):
     # WebDAV file system tools
     @mcp.tool()
-    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
-
-        Examples:
-            # List root directory
-            await nc_webdav_list_directory("")
-
-            # List a specific folder
-            await nc_webdav_list_directory("Documents/Projects")
+            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("files:read")
     async def nc_webdav_read_file(path: str, ctx: Context):
         """Read the content of a file from NextCloud.
 
@@ -37,14 +57,21 @@ 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'
@@ -52,6 +79,31 @@ def configure_webdav_tools(mcp: FastMCP):
         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:
@@ -77,6 +129,7 @@ def configure_webdav_tools(mcp: FastMCP):
         }
 
     @mcp.tool()
+    @require_scopes("files:write")
     async def nc_webdav_write_file(
         path: str, content: str, ctx: Context, content_type: str | None = None
     ):
@@ -89,13 +142,6 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code indicating success
-
-        Examples:
-            # Write a text file
-            await nc_webdav_write_file("Documents/notes.md", "# My Notes\nContent here...")
-
-            # Write binary data (base64 encoded)
-            await nc_webdav_write_file("files/data.bin", base64_content, "application/octet-stream;base64")
         """
         client = get_client(ctx)
 
@@ -111,6 +157,7 @@ def configure_webdav_tools(mcp: FastMCP):
         return await client.webdav.write_file(path, content_bytes, content_type)
 
     @mcp.tool()
+    @require_scopes("files:write")
     async def nc_webdav_create_directory(path: str, ctx: Context):
         """Create a directory in NextCloud.
 
@@ -119,18 +166,12 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code (201 for created, 405 if already exists)
-
-        Examples:
-            # Create a single directory
-            await nc_webdav_create_directory("NewProject")
-
-            # Create nested directories (parent must exist)
-            await nc_webdav_create_directory("Projects/MyApp/docs")
         """
         client = get_client(ctx)
         return await client.webdav.create_directory(path)
 
     @mcp.tool()
+    @require_scopes("files:write")
     async def nc_webdav_delete_resource(path: str, ctx: Context):
         """Delete a file or directory in NextCloud.
 
@@ -139,18 +180,12 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code indicating result (404 if not found)
-
-        Examples:
-            # Delete a file
-            await nc_webdav_delete_resource("old_document.txt")
-
-            # Delete a directory (will delete all contents)
-            await nc_webdav_delete_resource("temp_folder")
         """
         client = get_client(ctx)
         return await client.webdav.delete_resource(path)
 
     @mcp.tool()
+    @require_scopes("files:write")
     async def nc_webdav_move_resource(
         source_path: str, destination_path: str, ctx: Context, overwrite: bool = False
     ):
@@ -163,19 +198,6 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code indicating result (404 if source not found, 412 if destination exists and overwrite is False)
-
-        Examples:
-            # Rename a file
-            await nc_webdav_move_resource("document.txt", "new_name.txt")
-
-            # Move a file to another directory
-            await nc_webdav_move_resource("document.txt", "Archive/document.txt")
-
-            # Move a directory
-            await nc_webdav_move_resource("Projects/OldProject", "Projects/NewProject")
-
-            # Move and overwrite if destination exists
-            await nc_webdav_move_resource("document.txt", "Archive/document.txt", overwrite=True)
         """
         client = get_client(ctx)
         return await client.webdav.move_resource(
@@ -183,6 +205,7 @@ def configure_webdav_tools(mcp: FastMCP):
         )
 
     @mcp.tool()
+    @require_scopes("files:write")
     async def nc_webdav_copy_resource(
         source_path: str, destination_path: str, ctx: Context, overwrite: bool = False
     ):
@@ -195,21 +218,202 @@ def configure_webdav_tools(mcp: FastMCP):
 
         Returns:
             Dict with status_code indicating result (404 if source not found, 412 if destination exists and overwrite is False)
-
-        Examples:
-            # Copy a file
-            await nc_webdav_copy_resource("document.txt", "document_copy.txt")
-
-            # Copy a file to another directory
-            await nc_webdav_copy_resource("document.txt", "Backup/document.txt")
-
-            # Copy a directory
-            await nc_webdav_copy_resource("Projects/ProjectA", "Projects/ProjectA_Backup")
-
-            # Copy and overwrite if destination exists
-            await nc_webdav_copy_resource("document.txt", "Backup/document.txt", overwrite=True)
         """
         client = get_client(ctx)
         return await client.webdav.copy_resource(
             source_path, destination_path, overwrite
         )
+
+    @mcp.tool()
+    @require_scopes("files:read")
+    async def nc_webdav_search_files(
+        ctx: Context,
+        scope: str = "",
+        name_pattern: str | None = None,
+        mime_type: str | None = None,
+        only_favorites: bool = False,
+        limit: int | None = None,
+    ) -> SearchFilesResponse:
+        """Search for files in NextCloud using WebDAV SEARCH.
+
+        This is a high-level search tool that supports common search patterns.
+        For more complex queries, use the specific search tools.
+
+        Args:
+            scope: Directory path to search in (empty string for user root)
+            name_pattern: File name pattern (supports % wildcard, e.g., "%.txt" for all text files)
+            mime_type: MIME type to filter by (supports % wildcard, e.g., "image/%" for all images)
+            only_favorites: If True, only return favorited files
+            limit: Maximum number of results to return
+
+        Returns:
+            SearchFilesResponse with list of matching files
+        """
+        client = get_client(ctx)
+
+        # Build where conditions based on filters
+        conditions = []
+
+        if name_pattern:
+            conditions.append(
+                f"""
+                <d:like>
+                    <d:prop>
+                        <d:displayname/>
+                    </d:prop>
+                    <d:literal>{name_pattern}</d:literal>
+                </d:like>
+            """
+            )
+
+        if mime_type:
+            conditions.append(
+                f"""
+                <d:like>
+                    <d:prop>
+                        <d:getcontenttype/>
+                    </d:prop>
+                    <d:literal>{mime_type}</d:literal>
+                </d:like>
+            """
+            )
+
+        if only_favorites:
+            conditions.append(
+                """
+                <d:eq>
+                    <d:prop>
+                        <oc:favorite/>
+                    </d:prop>
+                    <d:literal>1</d:literal>
+                </d:eq>
+            """
+            )
+
+        # Combine conditions with AND if multiple
+        if len(conditions) > 1:
+            where_conditions = f"""
+                <d:and>
+                    {"".join(conditions)}
+                </d:and>
+            """
+        elif len(conditions) == 1:
+            where_conditions = conditions[0]
+        else:
+            where_conditions = None
+
+        # Include extended properties
+        properties = [
+            "displayname",
+            "getcontentlength",
+            "getcontenttype",
+            "getlastmodified",
+            "resourcetype",
+            "getetag",
+            "fileid",
+            "favorite",
+        ]
+
+        results = await client.webdav.search_files(
+            scope=scope,
+            where_conditions=where_conditions,
+            properties=properties,
+            limit=limit,
+        )
+
+        # Convert to FileInfo models
+        file_infos = [FileInfo(**result) for result in results]
+
+        # Build filters applied dict
+        filters = {}
+        if name_pattern:
+            filters["name_pattern"] = name_pattern
+        if mime_type:
+            filters["mime_type"] = mime_type
+        if only_favorites:
+            filters["only_favorites"] = True
+
+        return SearchFilesResponse(
+            results=file_infos,
+            total_found=len(file_infos),
+            scope=scope,
+            filters_applied=filters if filters else None,
+        )
+
+    @mcp.tool()
+    @require_scopes("files:read")
+    async def nc_webdav_find_by_name(
+        pattern: str, ctx: Context, scope: str = "", limit: int | None = None
+    ) -> SearchFilesResponse:
+        """Find files by name pattern in NextCloud.
+
+        Args:
+            pattern: Name pattern to search for (supports % wildcard)
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            SearchFilesResponse with list of matching files
+        """
+        client = get_client(ctx)
+        results = await client.webdav.find_by_name(
+            pattern=pattern, scope=scope, limit=limit
+        )
+        file_infos = [FileInfo(**result) for result in results]
+        return SearchFilesResponse(
+            results=file_infos,
+            total_found=len(file_infos),
+            scope=scope,
+            filters_applied={"name_pattern": pattern},
+        )
+
+    @mcp.tool()
+    @require_scopes("files:read")
+    async def nc_webdav_find_by_type(
+        mime_type: str, ctx: Context, scope: str = "", limit: int | None = None
+    ) -> SearchFilesResponse:
+        """Find files by MIME type in NextCloud.
+
+        Args:
+            mime_type: MIME type to search for (supports % wildcard)
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            SearchFilesResponse with list of matching files
+        """
+        client = get_client(ctx)
+        results = await client.webdav.find_by_type(
+            mime_type=mime_type, scope=scope, limit=limit
+        )
+        file_infos = [FileInfo(**result) for result in results]
+        return SearchFilesResponse(
+            results=file_infos,
+            total_found=len(file_infos),
+            scope=scope,
+            filters_applied={"mime_type": mime_type},
+        )
+
+    @mcp.tool()
+    @require_scopes("files:read")
+    async def nc_webdav_list_favorites(
+        ctx: Context, scope: str = "", limit: int | None = None
+    ) -> SearchFilesResponse:
+        """List all favorite files in NextCloud.
+
+        Args:
+            scope: Directory path to search in (empty string for all favorites)
+            limit: Maximum number of results to return
+
+        Returns:
+            SearchFilesResponse with list of favorite files
+        """
+        client = get_client(ctx)
+        results = await client.webdav.list_favorites(scope=scope, limit=limit)
+        file_infos = [FileInfo(**result) for result in results]
+        return SearchFilesResponse(
+            results=file_infos,
+            total_found=len(file_infos),
+            scope=scope,
+            filters_applied={"only_favorites": True},
+        )

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,36 +1,62 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.15.2"
-description = ""
+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"}
+    {name = "Chris Coutinho", email = "chris@coutinho.io"}
 ]
 readme = "README.md"
+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)",
     "pythonvcard4>=0.2.0",
     "pydantic>=2.11.4",
     "click>=8.1.8",
+    "caldav",
+    "pyjwt[crypto]>=2.8.0", # Async I/O library for better compatibility
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Communications",
+    "Topic :: Internet :: WWW/HTTP",
 ]
 
+[project.urls]
+Homepage = "https://github.com/cbcoutinho/nextcloud-mcp-server"
+Documentation = "https://github.com/cbcoutinho/nextcloud-mcp-server#readme"
+Repository = "https://github.com/cbcoutinho/nextcloud-mcp-server"
+"Bug Tracker" = "https://github.com/cbcoutinho/nextcloud-mcp-server/issues"
+Changelog = "https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/CHANGELOG.md"
+
 [tool.pytest.ini_options]
-asyncio_mode = "auto"
-asyncio_default_test_loop_scope = "session"
-asyncio_default_fixture_loop_scope = "session"
+anyio_mode = "auto"
+addopts = "-p no:asyncio -x"  # Disable pytest-asyncio plugin, use only anyio
 log_cli = 1
-log_cli_level = "WARN"
-log_level = "WARN"
+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",
 ]
+# Timeout settings to prevent tests from hanging indefinitely
+timeout = 180  # 3 minutes default timeout per test (includes fixture setup)
+timeout_func_only = false  # Timeout includes fixture setup/teardown
 
 [tool.commitizen]
 name = "cz_conventional_commits"
@@ -40,9 +66,19 @@ version_provider = "uv"
 update_changelog_on_bump = true
 major_version_zero = true
 
+[tool.ruff.lint]
+extend-select = ["I"]
+
+[tool.uv.sources]
+caldav = { git = "https://github.com/cbcoutinho/caldav", branch = "feature/httpx" }
+
 [build-system]
-requires = ["poetry-core>=2.0.0,<3.0.0"]
-build-backend = "poetry.core.masonry.api"
+requires = ["uv_build>=0.9.4,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "nextcloud_mcp_server"
+module-root = ""
 
 [dependency-groups]
 dev = [
@@ -50,11 +86,19 @@ dev = [
     "ipython>=9.2.0",
     "playwright>=1.49.1",
     "pytest>=8.3.5",
-    "pytest-asyncio>=1.0.0",
     "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]
 nextcloud-mcp-server = "nextcloud_mcp_server.app:run"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

scripts/add_scope_decorators.py

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+"""Script to automatically add @require_scopes decorators to MCP tools.
+
+This script parses server module files and adds appropriate scope decorators
+based on the operation type (read vs write).
+
+Usage:
+    python scripts/add_scope_decorators.py [--dry-run] [--file FILE]
+"""
+
+import argparse
+import ast
+import re
+from pathlib import Path
+from typing import List, Tuple
+
+# Operation patterns for classification
+READ_PATTERNS = [
+    r".*_get_.*",
+    r".*_get$",
+    r".*_list_.*",
+    r".*_list$",
+    r".*_search_.*",
+    r".*_search$",
+    r".*_read_.*",
+    r".*_read$",
+    r".*_find_.*",
+    r".*_find$",
+    r".*_fetch_.*",
+    r".*_fetch$",
+    r".*_retrieve_.*",
+    r".*_retrieve$",
+]
+
+WRITE_PATTERNS = [
+    r".*_create_.*",
+    r".*_create$",
+    r".*_update_.*",
+    r".*_update$",
+    r".*_delete_.*",
+    r".*_delete$",
+    r".*_append_.*",
+    r".*_append$",
+    r".*_modify_.*",
+    r".*_modify$",
+    r".*_set_.*",
+    r".*_set$",
+    r".*_add_.*",
+    r".*_add$",
+    r".*_remove_.*",
+    r".*_remove$",
+    r".*_edit_.*",
+    r".*_edit$",
+    r".*_move_.*",
+    r".*_move$",
+    r".*_copy_.*",
+    r".*_copy$",
+    r".*_upload_.*",
+    r".*_upload$",
+    r".*_download_.*",
+    r".*_download$",
+    r".*_share_.*",
+    r".*_share$",
+    r".*_unshare_.*",
+    r".*_unshare$",
+    r".*_bulk_.*",  # Bulk operations are typically writes
+]
+
+
+def classify_operation(func_name: str) -> str | None:
+    """Classify a function as read or write operation.
+
+    Args:
+        func_name: Function name to classify
+
+    Returns:
+        "nc:read", "nc:write", or None if cannot classify
+    """
+    # Check write patterns first (more specific)
+    for pattern in WRITE_PATTERNS:
+        if re.match(pattern, func_name):
+            return "nc:write"
+
+    # Check read patterns
+    for pattern in READ_PATTERNS:
+        if re.match(pattern, func_name):
+            return "nc:read"
+
+    return None
+
+
+def has_scope_decorator(decorators: List[ast.expr]) -> bool:
+    """Check if function already has @require_scopes decorator."""
+    for decorator in decorators:
+        if isinstance(decorator, ast.Call):
+            if (
+                isinstance(decorator.func, ast.Name)
+                and decorator.func.id == "require_scopes"
+            ):
+                return True
+        elif isinstance(decorator, ast.Name) and decorator.name == "require_scopes":
+            return True
+    return False
+
+
+def has_mcp_tool_decorator(decorators: List[ast.expr]) -> bool:
+    """Check if function has @mcp.tool() decorator."""
+    for decorator in decorators:
+        if isinstance(decorator, ast.Call):
+            if isinstance(decorator.func, ast.Attribute):
+                if decorator.func.attr == "tool":
+                    return True
+    return False
+
+
+def find_tools_needing_decorators(
+    file_path: Path, verbose: bool = False
+) -> List[Tuple[str, int, str]]:
+    """Find all tools that need scope decorators.
+
+    Returns:
+        List of (function_name, line_number, required_scope)
+    """
+    with open(file_path) as f:
+        content = f.read()
+
+    try:
+        tree = ast.parse(content)
+    except SyntaxError as e:
+        print(f"  ⚠️  Syntax error in {file_path}: {e}")
+        return []
+
+    tools_to_update = []
+    total_functions = 0
+    mcp_tools = 0
+    already_has_scope = 0
+    cannot_classify = 0
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef):
+            total_functions += 1
+
+            if verbose and node.decorator_list:
+                decorators_str = [
+                    ast.unparse(d) if hasattr(ast, "unparse") else str(d)
+                    for d in node.decorator_list
+                ]
+                print(f"  Function {node.name} has decorators: {decorators_str}")
+
+            # Check if it's an MCP tool
+            if not has_mcp_tool_decorator(node.decorator_list):
+                continue
+
+            mcp_tools += 1
+
+            # Check if it already has scope decorator
+            if has_scope_decorator(node.decorator_list):
+                already_has_scope += 1
+                continue
+
+            # Classify operation
+            scope = classify_operation(node.name)
+            if scope:
+                tools_to_update.append((node.name, node.lineno, scope))
+            else:
+                cannot_classify += 1
+                if verbose:
+                    print(f"  ⚠️  Cannot classify: {node.name}")
+
+    if verbose:
+        print(
+            f"  Debug: total_functions={total_functions}, mcp_tools={mcp_tools}, already_has_scope={already_has_scope}, cannot_classify={cannot_classify}"
+        )
+
+    return tools_to_update
+
+
+def add_decorator_to_file(
+    file_path: Path, dry_run: bool = False, verbose: bool = False
+) -> int:
+    """Add @require_scopes decorators to tools in a file.
+
+    Returns:
+        Number of decorators added
+    """
+    tools = find_tools_needing_decorators(file_path, verbose=verbose)
+
+    if not tools:
+        return 0
+
+    print(f"\n📝 {file_path.relative_to(Path.cwd())}")
+
+    with open(file_path) as f:
+        lines = f.readlines()
+
+    # Check if require_scopes is already imported
+    has_import = False
+    import_line_idx = None
+    for i, line in enumerate(lines):
+        if "from nextcloud_mcp_server.auth import" in line and "require_scopes" in line:
+            has_import = True
+            break
+        elif "from nextcloud_mcp_server.auth import" in line:
+            import_line_idx = i
+
+    # Add import if needed
+    if not has_import:
+        if import_line_idx is not None:
+            # Add require_scopes to existing import
+            old_line = lines[import_line_idx]
+            if "(" in old_line:
+                # Multi-line import
+                print(
+                    "  ⚠️  Multi-line import detected, please add manually: from nextcloud_mcp_server.auth import require_scopes"
+                )
+            else:
+                # Single line import - add require_scopes
+                lines[import_line_idx] = (
+                    old_line.rstrip().rstrip(")").rstrip() + ", require_scopes)\n"
+                )
+                print("  ✓ Added require_scopes to import")
+        else:
+            # No auth import exists, add new import
+            # Find first import line
+            for i, line in enumerate(lines):
+                if line.startswith("from nextcloud_mcp_server"):
+                    lines.insert(
+                        i, "from nextcloud_mcp_server.auth import require_scopes\n"
+                    )
+                    print(
+                        "  ✓ Added import: from nextcloud_mcp_server.auth import require_scopes"
+                    )
+                    break
+
+    # Add decorators to tools (in reverse order to preserve line numbers)
+    for func_name, line_num, scope in reversed(tools):
+        # Find the @mcp.tool() decorator line
+        for i in range(line_num - 1, max(0, line_num - 10), -1):
+            if "@mcp.tool()" in lines[i]:
+                # Get indentation from @mcp.tool() line
+                indent = len(lines[i]) - len(lines[i].lstrip())
+                decorator_line = " " * indent + f'@require_scopes("{scope}")\n'
+                lines.insert(i + 1, decorator_line)
+                print(f'  ✓ {func_name}:{line_num} → @require_scopes("{scope}")')
+                break
+
+    if not dry_run:
+        with open(file_path, "w") as f:
+            f.writelines(lines)
+        print("  💾 Saved changes")
+    else:
+        print("  🔍 DRY RUN - no changes written")
+
+    return len(tools)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Add @require_scopes decorators to MCP tools"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be changed without modifying files",
+    )
+    parser.add_argument(
+        "--file",
+        type=Path,
+        help="Process a single file instead of all server modules",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show debug information",
+    )
+    args = parser.parse_args()
+
+    server_dir = Path(__file__).parent.parent / "nextcloud_mcp_server" / "server"
+
+    if args.file:
+        files = [args.file]
+    else:
+        files = sorted(server_dir.glob("*.py"))
+        files = [f for f in files if f.name != "__init__.py"]
+
+    print("🔍 Scanning for tools needing scope decorators...")
+    print(
+        f"   {'DRY RUN MODE - No changes will be made' if args.dry_run else 'LIVE MODE - Files will be modified'}"
+    )
+
+    total_added = 0
+    for file_path in files:
+        added = add_decorator_to_file(
+            file_path, dry_run=args.dry_run, verbose=args.verbose
+        )
+        total_added += added
+
+    print(f"\n{'📊 Summary (dry run)' if args.dry_run else '✅ Complete'}")
+    print(f"   Total decorators added: {total_added}")
+
+    if args.dry_run:
+        print("\n💡 Run without --dry-run to apply changes")
+
+
+if __name__ == "__main__":
+    main()

scripts/add_scope_decorators_simple.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Simpler script to add @require_scopes decorators using regex.
+
+This script uses regex patterns to find @mcp.tool() decorators and adds
+the appropriate @require_scopes decorator based on function name patterns.
+
+Usage:
+    python scripts/add_scope_decorators_simple.py [--dry-run]
+"""
+
+import argparse
+import re
+from pathlib import Path
+
+# Operation patterns for classification
+READ_KEYWORDS = [
+    "get",
+    "list",
+    "search",
+    "read",
+    "find",
+    "fetch",
+    "retrieve",
+    "upcoming",
+]
+WRITE_KEYWORDS = [
+    "create",
+    "update",
+    "delete",
+    "append",
+    "modify",
+    "set",
+    "add",
+    "remove",
+    "edit",
+    "move",
+    "copy",
+    "upload",
+    "download",
+    "share",
+    "unshare",
+    "bulk",
+    "manage",
+    "import",
+    "reindex",
+    "archive",
+    "unarchive",
+    "reorder",
+    "assign",
+    "unassign",
+    "insert",
+    "write",
+]
+
+
+def classify_function(func_name: str) -> str | None:
+    """Classify a function name as read or write operation."""
+    func_lower = func_name.lower()
+
+    # Check write keywords first (more specific)
+    for keyword in WRITE_KEYWORDS:
+        if f"_{keyword}_" in func_lower or func_lower.endswith(f"_{keyword}"):
+            return "nc:write"
+
+    # Check read keywords
+    for keyword in READ_KEYWORDS:
+        if f"_{keyword}_" in func_lower or func_lower.endswith(f"_{keyword}"):
+            return "nc:read"
+
+    return None
+
+
+def process_file(file_path: Path, dry_run: bool = False) -> int:
+    """Process a single file to add @require_scopes decorators.
+
+    Returns:
+        Number of decorators added
+    """
+    with open(file_path) as f:
+        lines = f.readlines()
+
+    # Check if require_scopes is already imported
+    has_import = False
+    import_line_idx = None
+
+    for i, line in enumerate(lines):
+        if "from nextcloud_mcp_server.auth import" in line:
+            if "require_scopes" in line:
+                has_import = True
+            else:
+                import_line_idx = i
+
+    modified = False
+    decorators_added = 0
+
+    # Find all @mcp.tool() decorators
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+
+        # Look for @mcp.tool() decorator
+        if re.match(r"\s*@mcp\.tool\(\)", line):
+            # Check if next line already has @require_scopes
+            if i + 1 < len(lines) and "@require_scopes" in lines[i + 1]:
+                i += 1
+                continue
+
+            # Find the function definition (should be on next line or after other decorators)
+            func_line_idx = i + 1
+            while func_line_idx < len(lines) and not lines[
+                func_line_idx
+            ].strip().startswith("async def"):
+                func_line_idx += 1
+
+            if func_line_idx >= len(lines):
+                i += 1
+                continue
+
+            # Extract function name
+            func_match = re.match(r"\s*async def (\w+)\(", lines[func_line_idx])
+            if not func_match:
+                i += 1
+                continue
+
+            func_name = func_match.group(1)
+            scope = classify_function(func_name)
+
+            if scope:
+                # Get indentation from @mcp.tool() line
+                indent = len(line) - len(line.lstrip())
+                decorator_line = " " * indent + f'@require_scopes("{scope}")\n'
+
+                # Insert after @mcp.tool()
+                lines.insert(i + 1, decorator_line)
+                decorators_added += 1
+                modified = True
+                print(f'  ✓ {func_name} → @require_scopes("{scope}")')
+            else:
+                print(f"  ⚠️  Cannot classify: {func_name}")
+
+        i += 1
+
+    # Add import if needed and decorators were added
+    if decorators_added > 0 and not has_import:
+        if import_line_idx is not None:
+            # Add to existing import
+            old_line = lines[import_line_idx]
+            if old_line.rstrip().endswith(")"):
+                lines[import_line_idx] = old_line.rstrip()[:-1] + ", require_scopes)\n"
+            else:
+                lines[import_line_idx] = old_line.rstrip() + ", require_scopes\n"
+            print("  ✓ Added require_scopes to existing import")
+            modified = True
+        else:
+            # No auth import exists, add new import after last 'from nextcloud_mcp_server' import
+            last_nc_import_idx = None
+            for i, line in enumerate(lines):
+                if line.startswith("from nextcloud_mcp_server"):
+                    last_nc_import_idx = i
+
+            if last_nc_import_idx is not None:
+                lines.insert(
+                    last_nc_import_idx + 1,
+                    "from nextcloud_mcp_server.auth import require_scopes\n",
+                )
+                print(
+                    "  ✓ Added new import: from nextcloud_mcp_server.auth import require_scopes"
+                )
+                modified = True
+            else:
+                print("  ⚠️  Could not find place to add require_scopes import")
+
+    # Write changes
+    if modified and not dry_run:
+        with open(file_path, "w") as f:
+            f.writelines(lines)
+        print(f"  💾 Saved changes to {file_path.name}")
+    elif dry_run and decorators_added > 0:
+        print(f"  🔍 DRY RUN - would add {decorators_added} decorators")
+
+    return decorators_added
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Add @require_scopes decorators to MCP tools"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be changed without modifying files",
+    )
+    parser.add_argument(
+        "--file",
+        type=Path,
+        help="Process a single file instead of all server modules",
+    )
+    args = parser.parse_args()
+
+    server_dir = Path(__file__).parent.parent / "nextcloud_mcp_server" / "server"
+
+    if args.file:
+        files = [args.file]
+    else:
+        files = sorted(server_dir.glob("*.py"))
+        files = [f for f in files if f.name != "__init__.py"]
+
+    print("🔍 Scanning for tools needing scope decorators...")
+    print(
+        f"   {'DRY RUN MODE - No changes will be made' if args.dry_run else 'LIVE MODE - Files will be modified'}"
+    )
+
+    total_added = 0
+    for file_path in files:
+        file_path = file_path.resolve()  # Convert to absolute path
+        try:
+            display_path = file_path.relative_to(Path.cwd())
+        except ValueError:
+            display_path = file_path.name
+        print(f"\n📝 {display_path}")
+        added = process_file(file_path, dry_run=args.dry_run)
+        total_added += added
+
+    print(f"\n{'📊 Summary (dry run)' if args.dry_run else '✅ Complete'}")
+    print(f"   Total decorators added: {total_added}")
+
+    if args.dry_run and total_added > 0:
+        print("\n💡 Run without --dry-run to apply changes")
+
+
+if __name__ == "__main__":
+    main()

tests/client/calendar/conftest.py

@@ -0,0 +1,11 @@
+"""Shared fixtures for calendar integration tests.
+
+Note: The temporary_calendar fixture is defined in tests/conftest.py and uses
+a shared session-scoped calendar to avoid Nextcloud rate limiting issues.
+This conftest.py exists for any calendar-specific fixtures that might be needed
+in the future.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)

tests/client/calendar/test_calendar_operations.py

@@ -1,4 +1,9 @@
-"""Integration tests for Calendar CalDAV operations."""
+"""Integration tests for Calendar CalDAV operations.
+
+Note: These tests use the shared temporary_calendar fixture from conftest.py
+which reuses a session-scoped calendar to avoid Nextcloud rate limiting issues.
+Each test cleans up its own events/todos but shares the same calendar.
+"""
 
 import logging
 import uuid
@@ -15,50 +20,13 @@ logger = logging.getLogger(__name__)
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-def test_calendar_name():
-    """Unique calendar name for testing."""
-    return f"test_calendar_{uuid.uuid4().hex[:8]}"
-
-
-@pytest.fixture
-async def temporary_calendar(nc_client: NextcloudClient, test_calendar_name: str):
-    """Create a temporary calendar for testing and clean up afterward."""
-    calendar_name = test_calendar_name
-
-    try:
-        # Create a test calendar
-        logger.info(f"Creating temporary calendar: {calendar_name}")
-        result = await nc_client.calendar.create_calendar(
-            calendar_name=calendar_name,
-            display_name=f"Test Calendar {calendar_name}",
-            description="Temporary calendar for integration testing",
-            color="#FF5722",
-        )
-
-        if result["status_code"] not in [200, 201]:
-            pytest.skip(f"Failed to create temporary calendar: {result}")
-
-        logger.info(f"Created temporary calendar: {calendar_name}")
-        yield calendar_name
-
-    except Exception as e:
-        logger.error(f"Error setting up temporary calendar: {e}")
-        pytest.skip(f"Calendar setup failed: {e}")
-
-    finally:
-        # Cleanup: Delete the temporary calendar
-        try:
-            logger.info(f"Cleaning up temporary calendar: {calendar_name}")
-            await nc_client.calendar.delete_calendar(calendar_name)
-            logger.info(f"Successfully deleted temporary calendar: {calendar_name}")
-        except Exception as e:
-            logger.error(f"Error deleting temporary calendar {calendar_name}: {e}")
-
-
 @pytest.fixture
 async def temporary_event(nc_client: NextcloudClient, temporary_calendar: str):
-    """Create a temporary event for testing and clean up afterward."""
+    """Create a temporary event for testing and clean up afterward.
+
+    Uses the shared temporary_calendar fixture from conftest.py which reuses
+    a session-scoped calendar to avoid Nextcloud rate limiting.
+    """
     event_uid = None
     calendar_name = temporary_calendar
 
@@ -351,11 +319,11 @@ async def test_get_nonexistent_event(
     calendar_name = temporary_calendar
     fake_uid = f"nonexistent-{uuid.uuid4()}"
 
-    with pytest.raises(HTTPStatusError) as exc_info:
+    # caldav library raises generic Exception for missing events, not HTTPStatusError
+    with pytest.raises(Exception, match="not found"):
         await nc_client.calendar.get_event(calendar_name, fake_uid)
 
-    assert exc_info.value.response.status_code == 404
-    logger.info(f"Correctly got 404 for nonexistent event: {fake_uid}")
+    logger.info(f"Correctly raised exception for nonexistent event: {fake_uid}")
 
 
 async def test_delete_nonexistent_event(
@@ -420,7 +388,11 @@ async def test_calendar_operations_error_handling(
     # Test with non-existent calendar
     fake_calendar = f"nonexistent_calendar_{uuid.uuid4().hex}"
 
-    with pytest.raises(HTTPStatusError):
-        await nc_client.calendar.get_calendar_events(fake_calendar)
+    # caldav library returns empty list for non-existent calendars, doesn't raise
+    # Testing that it doesn't crash and returns empty results
+    events = await nc_client.calendar.get_calendar_events(fake_calendar)
+    assert isinstance(events, list)
+    # Empty list is expected for non-existent calendar
+    assert len(events) == 0
 
     logger.info("Error handling tests completed successfully")

tests/client/calendar/test_field_preservation.py

@@ -15,7 +15,7 @@ logger = logging.getLogger(__name__)
 
 @pytest.mark.integration
 async def test_calendar_event_custom_fields_preservation(nc_client):
-    """Test that demonstrates loss of non-supported iCal fields during round-trip operations."""
+    """Test that custom iCal fields are preserved during round-trip update operations."""
     calendar_name = "personal"
 
     # Create an event with standard fields
@@ -32,7 +32,12 @@ async def test_calendar_event_custom_fields_preservation(nc_client):
     event_uid = result["uid"]
 
     try:
-        # Now manually inject a custom iCal property by creating a new version with raw iCal
+        # Get the calendar object from the caldav library
+        calendar = nc_client.calendar._get_calendar(calendar_name)
+        event = await calendar.event_by_uid(event_uid)
+        await event.load()
+
+        # Now manually inject custom iCal properties into the raw data
         # This simulates what would happen if the event was created by another CalDAV client
         # with extended properties
         custom_ical = f"""BEGIN:VCALENDAR
@@ -57,22 +62,15 @@ LAST-MODIFIED:{datetime.now().strftime("%Y%m%dT%H%M%SZ")}
 END:VEVENT
 END:VCALENDAR"""
 
-        # Direct CalDAV PUT to inject the custom iCal
-        event_path = f"/remote.php/dav/calendars/{nc_client.calendar.username}/{calendar_name}/{event_uid}.ics"
-        await nc_client.calendar._make_request(
-            "PUT",
-            event_path,
-            content=custom_ical,
-            headers={"Content-Type": "text/calendar; charset=utf-8"},
-        )
+        # Update the event's raw data and save
+        event.data = custom_ical
+        await event.save()
 
         logger.info(f"Injected custom iCal properties into event {event_uid}")
 
-        # Retrieve the event to confirm custom fields are present in raw iCal
-        response = await nc_client.calendar._make_request(
-            "GET", event_path, headers={"Accept": "text/calendar"}
-        )
-        raw_ical_before = response.text
+        # Reload the event to confirm custom fields are present
+        await event.load()
+        raw_ical_before = event.data
 
         logger.info("Raw iCal before update:")
         logger.info(raw_ical_before)
@@ -93,31 +91,24 @@ END:VCALENDAR"""
         await nc_client.calendar.update_event(calendar_name, event_uid, update_data)
         logger.info(f"Updated event {event_uid} through MCP client")
 
-        # Retrieve the event again to see if custom fields survived
-        response_after = await nc_client.calendar._make_request(
-            "GET", event_path, headers={"Accept": "text/calendar"}
-        )
-        raw_ical_after = response_after.text
+        # Reload the event to see if custom fields survived
+        await event.load()
+        raw_ical_after = event.data
 
         logger.info("Raw iCal after update:")
         logger.info(raw_ical_after)
 
-        # THIS IS THE TEST THAT SHOULD FAIL - custom fields should be preserved but won't be
-        try:
-            assert (
-                "X-CUSTOM-FIELD:This is a custom field that should be preserved"
-                in raw_ical_after
-            ), "Custom field X-CUSTOM-FIELD was lost during round-trip update"
-            assert "X-VENDOR-SPECIFIC:Vendor specific data" in raw_ical_after, (
-                "Custom field X-VENDOR-SPECIFIC was lost during round-trip update"
-            )
-            logger.info(
-                "✓ Custom fields were preserved (unexpected - this should fail with current implementation)"
-            )
-        except AssertionError as e:
-            logger.error(f"✗ Custom fields were lost during round-trip update: {e}")
-            # Re-raise to show the test failure
-            raise
+        # THIS IS THE CRITICAL TEST - custom fields should be preserved
+        assert (
+            "X-CUSTOM-FIELD:This is a custom field that should be preserved"
+            in raw_ical_after
+        ), "Custom field X-CUSTOM-FIELD was lost during round-trip update"
+
+        assert "X-VENDOR-SPECIFIC:Vendor specific data" in raw_ical_after, (
+            "Custom field X-VENDOR-SPECIFIC was lost during round-trip update"
+        )
+
+        logger.info("✓ Custom fields were preserved during update")
 
     finally:
         # Cleanup
@@ -299,7 +290,7 @@ END:VCARD"""
 
 @pytest.mark.integration
 async def test_calendar_event_roundtrip_data_loss_demonstration(nc_client):
-    """Demonstrates specific data loss scenarios in calendar events."""
+    """Test that extended iCal properties are preserved during round-trip update operations."""
     calendar_name = "personal"
 
     event_data = {
@@ -313,6 +304,11 @@ async def test_calendar_event_roundtrip_data_loss_demonstration(nc_client):
     event_uid = result["uid"]
 
     try:
+        # Get the calendar object and event
+        calendar = nc_client.calendar._get_calendar(calendar_name)
+        event = await calendar.event_by_uid(event_uid)
+        await event.load()
+
         # Inject additional iCal properties that are valid but not supported by our parser
         extended_ical = f"""BEGIN:VCALENDAR
 VERSION:2.0
@@ -342,20 +338,13 @@ LAST-MODIFIED:{datetime.now().strftime("%Y%m%dT%H%M%SZ")}
 END:VEVENT
 END:VCALENDAR"""
 
-        # Inject the extended iCal
-        event_path = f"/remote.php/dav/calendars/{nc_client.calendar.username}/{calendar_name}/{event_uid}.ics"
-        await nc_client.calendar._make_request(
-            "PUT",
-            event_path,
-            content=extended_ical,
-            headers={"Content-Type": "text/calendar; charset=utf-8"},
-        )
+        # Update the event's raw data and save
+        event.data = extended_ical
+        await event.save()
 
-        # Verify extended properties are present
-        response = await nc_client.calendar._make_request(
-            "GET", event_path, headers={"Accept": "text/calendar"}
-        )
-        original_ical = response.text
+        # Reload to verify extended properties are present
+        await event.load()
+        original_ical = event.data
 
         # Confirm extended properties exist
         extended_properties = [
@@ -392,11 +381,9 @@ END:VCALENDAR"""
         update_data = {"location": "Conference Room B"}  # Simple location change
         await nc_client.calendar.update_event(calendar_name, event_uid, update_data)
 
-        # Check what survived the round-trip
-        response_after = await nc_client.calendar._make_request(
-            "GET", event_path, headers={"Accept": "text/calendar"}
-        )
-        updated_ical = response_after.text
+        # Reload the event to check what survived the round-trip
+        await event.load()
+        updated_ical = event.data
 
         logger.info("Checking which properties survived the update...")
 
@@ -423,13 +410,16 @@ END:VCALENDAR"""
                     lost.append(prop)
 
         logger.info(f"Properties that SURVIVED: {survived}")
-        logger.error(f"Properties that were LOST: {lost}")
+        if lost:
+            logger.error(f"Properties that were LOST: {lost}")
 
-        # This test should fail - we expect data loss
+        # Assert that all extended properties were preserved
         assert len(lost) == 0, (
             f"Round-trip update lost {len(lost)} extended properties: {lost}"
         )
 
+        logger.info("✓ All extended properties preserved during update")
+
     finally:
         try:
             await nc_client.calendar.delete_event(calendar_name, event_uid)

tests/client/calendar/test_task_operations.py

@@ -0,0 +1,498 @@
+"""Integration tests for Calendar VTODO (task) operations."""
+
+import logging
+import uuid
+from datetime import datetime, timedelta
+
+import pytest
+from httpx import HTTPStatusError
+
+from nextcloud_mcp_server.client import NextcloudClient
+
+logger = logging.getLogger(__name__)
+
+# Mark all tests in this module as integration tests
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture
+async def temporary_todo(nc_client: NextcloudClient, temporary_calendar: str):
+    """Create a temporary todo for testing and clean up afterward."""
+    todo_uid = None
+    calendar_name = temporary_calendar
+
+    # Create a test todo
+    tomorrow = datetime.now() + timedelta(days=1)
+    todo_data = {
+        "summary": f"Test Task {uuid.uuid4().hex[:8]}",
+        "description": "Test todo created by integration tests",
+        "status": "NEEDS-ACTION",
+        "priority": 5,
+        "due": tomorrow.strftime("%Y-%m-%dT18:00:00"),
+        "categories": "testing",
+    }
+
+    try:
+        logger.info(f"Creating temporary todo in calendar: {calendar_name}")
+        result = await nc_client.calendar.create_todo(calendar_name, todo_data)
+        todo_uid = result.get("uid")
+
+        if not todo_uid:
+            pytest.fail("Failed to create temporary todo")
+
+        logger.info(f"Created temporary todo with UID: {todo_uid}")
+        yield {"uid": todo_uid, "calendar_name": calendar_name, "data": todo_data}
+
+    finally:
+        # Cleanup
+        if todo_uid:
+            try:
+                logger.info(f"Cleaning up temporary todo: {todo_uid}")
+                await nc_client.calendar.delete_todo(calendar_name, todo_uid)
+                logger.info(f"Successfully deleted temporary todo: {todo_uid}")
+            except HTTPStatusError as e:
+                if e.response.status_code != 404:
+                    logger.error(f"Error deleting temporary todo {todo_uid}: {e}")
+            except Exception as e:
+                logger.error(
+                    f"Unexpected error deleting temporary todo {todo_uid}: {e}"
+                )
+
+
+# ============= Basic CRUD Tests =============
+
+
+async def test_create_and_delete_todo(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test creating and deleting a basic todo."""
+    calendar_name = temporary_calendar
+
+    # Create todo
+    tomorrow = datetime.now() + timedelta(days=1)
+    todo_data = {
+        "summary": "Integration Test Task",
+        "description": "Test task for integration testing",
+        "status": "NEEDS-ACTION",
+        "priority": 3,
+        "due": tomorrow.strftime("%Y-%m-%dT18:00:00"),
+        "categories": "testing,integration",
+    }
+
+    try:
+        result = await nc_client.calendar.create_todo(calendar_name, todo_data)
+        assert "uid" in result
+        assert result["status_code"] in [200, 201, 204]
+
+        todo_uid = result["uid"]
+        logger.info(f"Created todo with UID: {todo_uid}")
+
+        # Verify todo was created by listing todos
+        todos = await nc_client.calendar.list_todos(calendar_name)
+        todo_uids = [todo.get("uid") for todo in todos]
+        assert todo_uid in todo_uids
+
+        # Find our todo in the list
+        our_todo = next((t for t in todos if t.get("uid") == todo_uid), None)
+        assert our_todo is not None
+        assert our_todo["summary"] == "Integration Test Task"
+        assert our_todo["status"] == "NEEDS-ACTION"
+        assert our_todo["priority"] == 3
+
+        # Delete todo
+        delete_result = await nc_client.calendar.delete_todo(calendar_name, todo_uid)
+        assert delete_result["status_code"] in [200, 204, 404]
+
+        logger.info(f"Successfully deleted todo: {todo_uid}")
+
+    except Exception as e:
+        logger.error(f"Test failed: {e}")
+        raise
+
+
+async def test_list_todos(nc_client: NextcloudClient, temporary_calendar: str):
+    """Test listing todos in a calendar."""
+    calendar_name = temporary_calendar
+
+    # Create multiple todos
+    todo_uids = []
+    for i in range(3):
+        todo_data = {
+            "summary": f"Test Task {i + 1}",
+            "description": f"Task number {i + 1}",
+            "status": "NEEDS-ACTION",
+            "priority": i + 1,
+        }
+        result = await nc_client.calendar.create_todo(calendar_name, todo_data)
+        todo_uids.append(result["uid"])
+
+    try:
+        # List todos
+        todos = await nc_client.calendar.list_todos(calendar_name)
+
+        assert isinstance(todos, list)
+        assert len(todos) >= 3  # At least our 3 todos
+
+        # Check structure
+        for todo in todos:
+            assert "uid" in todo
+            assert "summary" in todo
+            assert "status" in todo
+            assert "priority" in todo
+
+        # Verify our todos are in the list
+        listed_uids = [todo["uid"] for todo in todos]
+        for uid in todo_uids:
+            assert uid in listed_uids
+
+        logger.info(f"Found {len(todos)} todos in calendar")
+
+    finally:
+        # Cleanup
+        for uid in todo_uids:
+            try:
+                await nc_client.calendar.delete_todo(calendar_name, uid)
+            except Exception:
+                pass
+
+
+async def test_update_todo(nc_client: NextcloudClient, temporary_todo: dict):
+    """Test updating an existing todo."""
+    calendar_name = temporary_todo["calendar_name"]
+    todo_uid = temporary_todo["uid"]
+
+    # Update todo data
+    updated_data = {
+        "summary": "Updated Test Task Title",
+        "description": "Updated description for test task",
+        "status": "IN-PROCESS",
+        "priority": 1,  # High priority
+        "percent_complete": 50,
+    }
+
+    try:
+        result = await nc_client.calendar.update_todo(
+            calendar_name, todo_uid, updated_data
+        )
+        assert result["uid"] == todo_uid
+
+        # Verify updates by listing todos
+        todos = await nc_client.calendar.list_todos(calendar_name)
+        updated_todo = next((t for t in todos if t["uid"] == todo_uid), None)
+
+        assert updated_todo is not None
+        assert updated_todo["summary"] == "Updated Test Task Title"
+        assert updated_todo["description"] == "Updated description for test task"
+        assert updated_todo["status"] == "IN-PROCESS"
+        assert updated_todo["priority"] == 1
+        assert updated_todo["percent_complete"] == 50
+
+        logger.info(f"Successfully updated todo: {todo_uid}")
+
+    except Exception as e:
+        logger.error(f"Todo update test failed: {e}")
+        raise
+
+
+async def test_todo_with_dates(nc_client: NextcloudClient, temporary_calendar: str):
+    """Test creating a todo with start, due, and completed dates."""
+    calendar_name = temporary_calendar
+
+    now = datetime.now()
+    start_date = now + timedelta(days=1)
+    due_date = now + timedelta(days=7)
+
+    todo_data = {
+        "summary": "Task with Dates",
+        "description": "Test task with various date fields",
+        "status": "NEEDS-ACTION",
+        "dtstart": start_date.strftime("%Y-%m-%dT09:00:00"),
+        "due": due_date.strftime("%Y-%m-%dT17:00:00"),
+    }
+
+    try:
+        result = await nc_client.calendar.create_todo(calendar_name, todo_data)
+        todo_uid = result["uid"]
+        logger.info(f"Created todo with dates, UID: {todo_uid}")
+
+        # Verify dates
+        todos = await nc_client.calendar.list_todos(calendar_name)
+        created_todo = next((t for t in todos if t["uid"] == todo_uid), None)
+
+        assert created_todo is not None
+        assert created_todo["summary"] == "Task with Dates"
+        assert "dtstart" in created_todo
+        assert "due" in created_todo
+
+        # Cleanup
+        await nc_client.calendar.delete_todo(calendar_name, todo_uid)
+
+    except Exception as e:
+        logger.error(f"Date handling test failed: {e}")
+        raise
+
+
+# ============= Advanced Feature Tests =============
+
+
+async def test_todo_status_transitions(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test transitioning through different todo statuses."""
+    calendar_name = temporary_calendar
+
+    todo_data = {
+        "summary": "Status Transition Test",
+        "description": "Testing status changes",
+        "status": "NEEDS-ACTION",
+    }
+
+    result = await nc_client.calendar.create_todo(calendar_name, todo_data)
+    todo_uid = result["uid"]
+
+    try:
+        # Transition: NEEDS-ACTION → IN-PROCESS
+        await nc_client.calendar.update_todo(
+            calendar_name,
+            todo_uid,
+            {"status": "IN-PROCESS", "percent_complete": 25},
+        )
+
+        todos = await nc_client.calendar.list_todos(calendar_name)
+        todo = next((t for t in todos if t["uid"] == todo_uid), None)
+        assert todo["status"] == "IN-PROCESS"
+        assert todo["percent_complete"] == 25
+
+        # Transition: IN-PROCESS → COMPLETED
+        completed_time = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+        await nc_client.calendar.update_todo(
+            calendar_name,
+            todo_uid,
+            {
+                "status": "COMPLETED",
+                "percent_complete": 100,
+                "completed": completed_time,
+            },
+        )
+
+        todos = await nc_client.calendar.list_todos(calendar_name)
+        todo = next((t for t in todos if t["uid"] == todo_uid), None)
+        assert todo["status"] == "COMPLETED"
+        assert todo["percent_complete"] == 100
+        assert "completed" in todo
+
+        logger.info(f"Successfully transitioned todo through statuses: {todo_uid}")
+
+    finally:
+        await nc_client.calendar.delete_todo(calendar_name, todo_uid)
+
+
+async def test_todo_priority_levels(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test different priority levels (0=undefined, 1=highest, 9=lowest)."""
+    calendar_name = temporary_calendar
+    priorities = [0, 1, 5, 9]
+    priority_labels = {0: "Undefined", 1: "Highest", 5: "Medium", 9: "Lowest"}
+    todo_uids = []
+
+    try:
+        # Create todos with different priorities
+        for priority in priorities:
+            todo_data = {
+                "summary": f"Priority {priority} Task ({priority_labels[priority]})",
+                "status": "NEEDS-ACTION",
+                "priority": priority,
+            }
+            result = await nc_client.calendar.create_todo(calendar_name, todo_data)
+            todo_uids.append((result["uid"], priority))
+
+        # Verify all priorities
+        todos = await nc_client.calendar.list_todos(calendar_name)
+
+        for uid, expected_priority in todo_uids:
+            todo = next((t for t in todos if t["uid"] == uid), None)
+            assert todo is not None
+            assert todo["priority"] == expected_priority
+
+        logger.info(f"Successfully tested priority levels: {priorities}")
+
+    finally:
+        # Cleanup
+        for uid, _ in todo_uids:
+            try:
+                await nc_client.calendar.delete_todo(calendar_name, uid)
+            except Exception:
+                pass
+
+
+async def test_todo_with_categories(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test creating a todo with multiple categories."""
+    calendar_name = temporary_calendar
+
+    todo_data = {
+        "summary": "Task with Categories",
+        "description": "Testing category support",
+        "status": "NEEDS-ACTION",
+        "categories": "work,meeting,important,quarterly",
+    }
+
+    try:
+        result = await nc_client.calendar.create_todo(calendar_name, todo_data)
+        todo_uid = result["uid"]
+        logger.info(f"Created todo with categories, UID: {todo_uid}")
+
+        # Verify categories
+        todos = await nc_client.calendar.list_todos(calendar_name)
+        created_todo = next((t for t in todos if t["uid"] == todo_uid), None)
+
+        assert created_todo is not None
+        assert "categories" in created_todo
+        categories_str = created_todo["categories"]
+        assert "work" in categories_str
+        assert "meeting" in categories_str
+        assert "important" in categories_str
+        assert "quarterly" in categories_str
+
+        # Cleanup
+        await nc_client.calendar.delete_todo(calendar_name, todo_uid)
+
+    except Exception as e:
+        logger.error(f"Categories test failed: {e}")
+        raise
+
+
+async def test_search_todos_across_calendars(
+    nc_client: NextcloudClient, temporary_calendar: str, shared_calendar_2: str
+):
+    """Test searching for todos across multiple calendars.
+
+    Uses two shared test calendars to avoid rate limiting.
+    """
+    # Use existing shared calendars to avoid rate limits
+    cal1_name = temporary_calendar  # First shared test calendar
+    cal2_name = shared_calendar_2  # Second shared test calendar
+
+    try:
+        # Create todos in both calendars
+        todo1_data = {"summary": "Task in Calendar 1", "status": "NEEDS-ACTION"}
+        todo2_data = {"summary": "Task in Calendar 2", "status": "IN-PROCESS"}
+
+        result1 = await nc_client.calendar.create_todo(cal1_name, todo1_data)
+        result2 = await nc_client.calendar.create_todo(cal2_name, todo2_data)
+
+        # Search across all calendars
+        all_todos = await nc_client.calendar.search_todos_across_calendars()
+
+        assert isinstance(all_todos, list)
+
+        # Find our todos
+        todo1 = next((t for t in all_todos if t["uid"] == result1["uid"]), None)
+        todo2 = next((t for t in all_todos if t["uid"] == result2["uid"]), None)
+
+        assert todo1 is not None
+        assert todo2 is not None
+        assert "calendar_name" in todo1
+        assert "calendar_name" in todo2
+        assert todo1["calendar_name"] == cal1_name
+        assert todo2["calendar_name"] == cal2_name
+
+        logger.info(f"Found {len(all_todos)} todos across all calendars")
+
+    finally:
+        # Cleanup: Delete only the todos we created (calendars are reused/built-in)
+        try:
+            await nc_client.calendar.delete_todo(cal1_name, result1["uid"])
+        except Exception:
+            pass
+        try:
+            await nc_client.calendar.delete_todo(cal2_name, result2["uid"])
+        except Exception:
+            pass
+
+
+# ============= Edge Case Tests =============
+
+
+async def test_get_nonexistent_todo(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test attempting to retrieve a non-existent todo."""
+    calendar_name = temporary_calendar
+    fake_uid = f"nonexistent-{uuid.uuid4()}"
+
+    # List todos to ensure it doesn't exist
+    todos = await nc_client.calendar.list_todos(calendar_name)
+    matching_todos = [t for t in todos if t.get("uid") == fake_uid]
+    assert len(matching_todos) == 0
+
+    logger.info(f"Verified nonexistent todo UID: {fake_uid}")
+
+
+async def test_delete_nonexistent_todo(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test deleting a non-existent todo."""
+    calendar_name = temporary_calendar
+    fake_uid = f"nonexistent-{uuid.uuid4()}"
+
+    result = await nc_client.calendar.delete_todo(calendar_name, fake_uid)
+    assert result["status_code"] == 404
+    logger.info(f"Correctly got 404 for deleting nonexistent todo: {fake_uid}")
+
+
+async def test_list_todos_with_filters(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test listing todos with various filters."""
+    calendar_name = temporary_calendar
+
+    # Create todos with different statuses and priorities
+    test_todos = [
+        {
+            "summary": "High Priority Task",
+            "status": "NEEDS-ACTION",
+            "priority": 1,
+            "categories": "urgent",
+        },
+        {
+            "summary": "In Progress Task",
+            "status": "IN-PROCESS",
+            "priority": 5,
+            "categories": "work",
+        },
+        {
+            "summary": "Low Priority Task",
+            "status": "NEEDS-ACTION",
+            "priority": 9,
+            "categories": "someday",
+        },
+    ]
+
+    created_uids = []
+
+    try:
+        # Create test todos
+        for todo_data in test_todos:
+            result = await nc_client.calendar.create_todo(calendar_name, todo_data)
+            created_uids.append(result["uid"])
+
+        # Test basic list without filters
+        all_todos = await nc_client.calendar.list_todos(calendar_name)
+        assert len(all_todos) >= 3
+
+        # Verify all our todos are in the list
+        our_todo_uids = [t["uid"] for t in all_todos if t["uid"] in created_uids]
+        assert len(our_todo_uids) == 3
+
+        logger.info(f"Successfully created and listed {len(created_uids)} test todos")
+
+    finally:
+        # Cleanup
+        for uid in created_uids:
+            try:
+                await nc_client.calendar.delete_todo(calendar_name, uid)
+            except Exception:
+                pass

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_oauth.py

@@ -30,7 +30,7 @@ async def test_oauth_client_capabilities(nc_oauth_client: NextcloudClient):
 
 async def test_oauth_client_notes_list(nc_oauth_client: NextcloudClient):
     """Test that OAuth client can list notes."""
-    notes = await nc_oauth_client.notes.get_all_notes()
+    notes = [note async for note in nc_oauth_client.notes.get_all_notes()]
 
     assert isinstance(notes, list)
     logger.info(f"OAuth client successfully listed {len(notes)} notes")
@@ -95,7 +95,7 @@ async def test_invalid_token_fails():
     # Attempt to use a protected endpoint - should fail with 401
     # Note: capabilities endpoint is public and doesn't require auth
     with pytest.raises(HTTPStatusError) as exc_info:
-        await invalid_client.notes.get_all_notes()
+        _ = [note async for note in invalid_client.notes.get_all_notes()]
 
     assert exc_info.value.response.status_code == 401
 

tests/client/test_oauth_playwright.py

@@ -27,6 +27,6 @@ async def test_oauth_client_with_playwright_flow(nc_oauth_client):
     logger.info("OAuth client (Playwright) successfully fetched capabilities")
 
     # Test 2: List notes
-    notes = await nc_oauth_client.notes.get_all_notes()
+    notes = [note async for note in nc_oauth_client.notes.get_all_notes()]
     assert isinstance(notes, list)
     logger.info(f"OAuth client (Playwright) successfully listed {len(notes)} notes")

tests/client/test_sharing_api.py

@@ -9,7 +9,6 @@ logger = logging.getLogger(__name__)
 pytestmark = pytest.mark.integration
 
 
-@pytest.mark.asyncio
 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.asyncio
 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.asyncio
 async def test_list_shares(nc_client):
     """Test listing all shares."""
     # Create a test user to share with

tests/client/webdav/test_webdav_search.py

@@ -0,0 +1,268 @@
+"""Integration tests for WebDAV search operations."""
+
+import logging
+import uuid
+
+import pytest
+
+from nextcloud_mcp_server.client import NextcloudClient
+
+logger = logging.getLogger(__name__)
+
+# Mark all tests in this module as integration tests
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture
+async def test_search_setup(nc_client: NextcloudClient):
+    """Create test files and directories for search testing."""
+    test_dir = f"mcp_search_test_{uuid.uuid4().hex[:8]}"
+
+    # Create base directory
+    await nc_client.webdav.create_directory(test_dir)
+
+    # Create various test files
+    test_files = [
+        # Text files
+        (f"{test_dir}/document1.txt", b"Sample document content", "text/plain"),
+        (f"{test_dir}/document2.txt", b"Another document", "text/plain"),
+        (f"{test_dir}/report.txt", b"Report content", "text/plain"),
+        # Markdown files
+        (f"{test_dir}/readme.md", b"# README\nMarkdown content", "text/markdown"),
+        (f"{test_dir}/notes.md", b"# Notes\nSome notes here", "text/markdown"),
+        # PDF (simulated as binary)
+        (
+            f"{test_dir}/presentation.pdf",
+            b"%PDF-1.4 fake pdf content",
+            "application/pdf",
+        ),
+        # Subdirectory with files
+        (f"{test_dir}/subdir/nested.txt", b"Nested file content", "text/plain"),
+    ]
+
+    # Create subdirectory
+    await nc_client.webdav.create_directory(f"{test_dir}/subdir")
+
+    # Write all test files
+    for file_path, content, content_type in test_files:
+        await nc_client.webdav.write_file(file_path, content, content_type)
+
+    logger.info(f"Created test directory with {len(test_files)} files: {test_dir}")
+
+    yield test_dir
+
+    # Cleanup
+    try:
+        await nc_client.webdav.delete_resource(test_dir)
+        logger.info(f"Cleaned up test directory: {test_dir}")
+    except Exception as e:
+        logger.warning(f"Failed to cleanup test directory {test_dir}: {e}")
+
+
+async def test_find_by_name_exact(nc_client: NextcloudClient, test_search_setup: str):
+    """Test finding files by exact name."""
+    results = await nc_client.webdav.find_by_name("readme.md", scope=test_search_setup)
+
+    assert len(results) >= 1, "Should find at least one readme.md file"
+
+    # Check that we found the right file
+    readme_files = [r for r in results if r.get("name") == "readme.md"]
+    assert len(readme_files) >= 1, "Should find readme.md"
+
+    logger.info(f"Found {len(results)} files matching 'readme.md'")
+
+
+async def test_find_by_name_wildcard_extension(
+    nc_client: NextcloudClient, test_search_setup: str
+):
+    """Test finding files by extension using wildcard."""
+    # Find all .txt files
+    results = await nc_client.webdav.find_by_name("%.txt", scope=test_search_setup)
+
+    assert len(results) >= 3, "Should find at least 3 .txt files"
+
+    # Verify all results are .txt files
+    for result in results:
+        name = result.get("name", "")
+        assert name.endswith(".txt"), f"Expected .txt file, got {name}"
+
+    logger.info(f"Found {len(results)} .txt files")
+
+
+async def test_find_by_name_wildcard_prefix(
+    nc_client: NextcloudClient, test_search_setup: str
+):
+    """Test finding files by name prefix using wildcard."""
+    # Find all files starting with "document"
+    results = await nc_client.webdav.find_by_name("document%", scope=test_search_setup)
+
+    assert len(results) >= 2, "Should find at least 2 files starting with 'document'"
+
+    # Verify all results start with "document"
+    for result in results:
+        name = result.get("name", "")
+        assert name.startswith("document"), (
+            f"Expected name to start with 'document', got {name}"
+        )
+
+    logger.info(f"Found {len(results)} files starting with 'document'")
+
+
+async def test_find_by_type_text(nc_client: NextcloudClient, test_search_setup: str):
+    """Test finding files by MIME type (text files)."""
+    # Find all text files
+    results = await nc_client.webdav.find_by_type("text/%", scope=test_search_setup)
+
+    assert len(results) >= 5, "Should find at least 5 text files"
+
+    # Verify all results are text files
+    for result in results:
+        content_type = result.get("content_type", "")
+        assert content_type.startswith("text/"), (
+            f"Expected text/* type, got {content_type}"
+        )
+
+    logger.info(f"Found {len(results)} text files")
+
+
+async def test_find_by_type_specific(
+    nc_client: NextcloudClient, test_search_setup: str
+):
+    """Test finding files by specific MIME type."""
+    # Find PDF files
+    results = await nc_client.webdav.find_by_type(
+        "application/pdf", scope=test_search_setup
+    )
+
+    assert len(results) >= 1, "Should find at least 1 PDF file"
+
+    # Verify result is PDF
+    for result in results:
+        content_type = result.get("content_type", "")
+        assert content_type == "application/pdf", (
+            f"Expected application/pdf, got {content_type}"
+        )
+
+    logger.info(f"Found {len(results)} PDF files")
+
+
+async def test_search_with_limit(nc_client: NextcloudClient, test_search_setup: str):
+    """Test search with result limit."""
+    # Search for .txt files with limit of 2
+    results = await nc_client.webdav.find_by_name(
+        "%.txt", scope=test_search_setup, limit=2
+    )
+
+    # Should return at most 2 results
+    assert len(results) <= 2, f"Should return at most 2 results, got {len(results)}"
+    assert len(results) > 0, "Should return at least 1 result"
+
+    logger.info(f"Found {len(results)} files with limit=2")
+
+
+async def test_search_files_combined_filters(
+    nc_client: NextcloudClient, test_search_setup: str
+):
+    """Test search with multiple filters combined."""
+    # This test uses the search_files method directly to test combined conditions
+    # Search for .txt files that match a specific pattern
+    where_conditions = """
+        <d:and>
+            <d:like>
+                <d:prop>
+                    <d:displayname/>
+                </d:prop>
+                <d:literal>%.txt</d:literal>
+            </d:like>
+            <d:like>
+                <d:prop>
+                    <d:displayname/>
+                </d:prop>
+                <d:literal>document%</d:literal>
+            </d:like>
+        </d:and>
+    """
+
+    results = await nc_client.webdav.search_files(
+        scope=test_search_setup, where_conditions=where_conditions
+    )
+
+    # Should find document1.txt and document2.txt
+    assert len(results) >= 2, "Should find at least 2 files matching both conditions"
+
+    # Verify results match both conditions
+    for result in results:
+        name = result.get("name", "")
+        assert name.endswith(".txt"), f"Expected .txt file, got {name}"
+        assert name.startswith("document"), (
+            f"Expected name to start with 'document', got {name}"
+        )
+
+    logger.info(f"Found {len(results)} files matching combined filters")
+
+
+async def test_search_empty_scope(nc_client: NextcloudClient, test_search_setup: str):
+    """Test search in empty scope (user root)."""
+    # Search entire user root for a unique filename
+    unique_name = "readme.md"
+    results = await nc_client.webdav.find_by_name(unique_name, scope="")
+
+    # Should find at least the one we created
+    assert len(results) >= 1, f"Should find at least 1 file named {unique_name}"
+
+    logger.info(f"Found {len(results)} files in root scope")
+
+
+async def test_search_subdirectory(nc_client: NextcloudClient, test_search_setup: str):
+    """Test search within a subdirectory."""
+    # Search in the subdir for the nested file
+    results = await nc_client.webdav.find_by_name(
+        "nested.txt", scope=f"{test_search_setup}/subdir"
+    )
+
+    assert len(results) >= 1, "Should find nested.txt in subdirectory"
+
+    # Verify the file path
+    nested_file = results[0]
+    assert "nested.txt" in nested_file.get("name", ""), "Should find nested.txt"
+
+    logger.info(f"Found file in subdirectory: {nested_file.get('name')}")
+
+
+async def test_search_no_results(nc_client: NextcloudClient, test_search_setup: str):
+    """Test search that returns no results."""
+    # Search for a non-existent pattern
+    results = await nc_client.webdav.find_by_name(
+        "nonexistent_file_xyz123.txt", scope=test_search_setup
+    )
+
+    assert len(results) == 0, "Should return empty results for non-existent file"
+
+    logger.info("Search correctly returned no results for non-existent file")
+
+
+async def test_search_properties_returned(
+    nc_client: NextcloudClient, test_search_setup: str
+):
+    """Test that search returns expected properties."""
+    results = await nc_client.webdav.find_by_name("readme.md", scope=test_search_setup)
+
+    assert len(results) >= 1, "Should find at least one file"
+
+    result = results[0]
+
+    # Check for expected properties
+    assert "name" in result, "Should include name property"
+    assert "path" in result, "Should include path property"
+    assert "is_directory" in result, "Should include is_directory property"
+    assert result["is_directory"] is False, "readme.md should not be a directory"
+
+    # Optional properties that may be present
+    optional_props = ["size", "content_type", "last_modified", "etag"]
+    logger.info(f"Result properties: {list(result.keys())}")
+
+    # At least some optional properties should be present
+    present_optional = [prop for prop in optional_props if prop in result]
+    assert len(present_optional) > 0, f"Should have at least one of {optional_props}"
+
+    logger.info(f"Search returned properties: {list(result.keys())}")

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/README_OAUTH.md

@@ -0,0 +1,534 @@
+# OAuth Multi-User Load Testing Framework
+
+Comprehensive multi-user benchmarking system for testing OAuth-authenticated Nextcloud MCP server with realistic collaborative workflows.
+
+## Quick Start
+
+```bash
+# 1. Ensure docker-compose is running
+docker-compose up -d
+
+# 2. Run a benchmark with 2 users for 30 seconds
+uv run python -m tests.load.oauth_benchmark --users 2 --duration 30
+
+# 3. Clean up test users (IMPORTANT - always run after benchmark)
+uv run python -m tests.load.cleanup_loadtest_users
+
+# Optional: Verify cleanup
+uv run python -m tests.load.cleanup_loadtest_users --dry-run
+```
+
+## Overview
+
+This framework extends the basic load testing infrastructure to support:
+- **Multiple OAuth-authenticated users** running concurrently
+- **Coordinated workflows** spanning multiple users (sharing, collaboration, permissions)
+- **Per-user metrics** tracking individual user performance
+- **Workflow-specific metrics** measuring cross-user operation latencies
+- **Realistic scenarios** mimicking actual user collaboration patterns
+- **Concurrent user creation** - all users created and authenticated in parallel for fast setup
+
+## Architecture
+
+### Components
+
+```
+tests/load/
+├── oauth_pool.py          # OAuth user pool management
+├── oauth_workloads.py     # Multi-user workflow definitions
+├── oauth_metrics.py       # Enhanced metrics collection
+├── oauth_benchmark.py     # Main CLI entry point
+└── README_OAUTH.md        # This file
+```
+
+### Key Classes
+
+**OAuthUserPool** (`oauth_pool.py`)
+- Manages N OAuth-authenticated users
+- Handles token acquisition and storage
+- Creates and manages MCP sessions per user
+- Tracks per-user operation statistics
+
+**UserSessionWrapper** (`oauth_pool.py`)
+- Wraps MCP ClientSession for a specific user
+- Automatic operation tracking
+- Convenient tool/resource access methods
+
+**Workflow** (`oauth_workloads.py`)
+- Base class for multi-user coordinated workflows
+- Step-by-step execution with timing
+- Comprehensive error handling and reporting
+
+**OAuthBenchmarkMetrics** (`oauth_metrics.py`)
+- Per-user operation counts and latencies
+- Workflow completion rates and timings
+- Baseline operation statistics
+- Detailed reporting and JSON export
+
+## Available Workflows
+
+### 1. NoteShareWorkflow
+**Scenario**: Alice creates a note and shares it with Bob, who then reads it.
+
+**Steps**:
+1. User A creates a note
+2. User A shares note with User B (read-only permissions)
+3. User B lists their shared notes (measures propagation delay)
+4. User B reads the shared note
+
+**Metrics**: Creation latency, share propagation time, read latency
+
+### 2. CollaborativeEditWorkflow
+**Scenario**: Multiple users concurrently edit the same note.
+
+**Steps**:
+1. Owner creates a note
+2. All users read the note simultaneously
+3. All users append content concurrently
+4. Owner verifies final state
+
+**Metrics**: Concurrent read latency, concurrent write conflicts, final state consistency
+
+### 3. FileShareAndDownloadWorkflow
+**Scenario**: Alice uploads a file, shares it with Bob, who then downloads it.
+
+**Steps**:
+1. User A creates a file via WebDAV
+2. User A shares file with User B (read-only)
+3. User B lists their shares
+4. User B downloads the file
+
+**Metrics**: Upload latency, share creation, download latency
+
+### 4. MixedOAuthWorkload
+**Distribution**:
+- 50% Baseline operations (individual user CRUD)
+- 30% Note sharing workflows
+- 15% Collaborative editing workflows
+- 5% File sharing workflows
+
+## Usage
+
+### Basic Usage
+
+```bash
+# 4 users, 60-second test with mixed workload
+uv run python -m tests.load.oauth_benchmark --users 4 --duration 60
+
+# 10 users, 5-minute test
+uv run python -m tests.load.oauth_benchmark -u 10 -d 300
+
+# Export results to JSON
+uv run python -m tests.load.oauth_benchmark -u 5 -d 120 --output results.json
+```
+
+### Advanced Options
+
+```bash
+# Sharing-focused workload
+uv run python -m tests.load.oauth_benchmark --workload sharing -u 8 -d 180
+
+# Collaborative editing workload
+uv run python -m tests.load.oauth_benchmark --workload collaboration -u 6 -d 120
+
+# Baseline operations only (no workflows)
+uv run python -m tests.load.oauth_benchmark --workload baseline -u 10 -d 60
+
+# Verbose logging for debugging
+uv run python -m tests.load.oauth_benchmark -u 2 -d 30 --verbose
+```
+
+### CLI Options
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--users` | `-u` | 2 | Number of concurrent users (dynamically created) |
+| `--duration` | `-d` | 30.0 | Test duration in seconds |
+| `--warmup` | `-w` | 5.0 | Warmup period before metrics collection (seconds) |
+| `--url` | | `http://localhost:8001/mcp` | MCP OAuth server URL |
+| `--output` | `-o` | None | JSON output file path |
+| `--workload` | | `mixed` | Workload type: mixed, sharing, collaboration, baseline |
+| `--user-prefix` | | `loadtest` | Prefix for dynamically created usernames |
+| `--cleanup/--no-cleanup` | | `cleanup` | Delete created users after benchmark |
+| `--browser` | | `chromium` | Playwright browser: firefox, chromium, webkit |
+| `--headed` | | False | Run browser in headed mode (visible window) |
+| `--verbose` | `-v` | False | Enable verbose logging |
+
+## Test User Creation
+
+The framework **dynamically creates test users** on-demand with OAuth authentication:
+
+- **Naming**: Users are created with the pattern `{prefix}_user_{n}` (default: `loadtest_user_1`, `loadtest_user_2`, etc.)
+- **Customization**: Use `--user-prefix` to change the prefix (e.g., `--user-prefix mytest` → `mytest_user_1`)
+- **Scalability**: No limit on user count - create as many concurrent users as your system can handle
+- **Credentials**: Each user gets a randomly generated secure password
+- **OAuth Tokens**: All users authenticate via automated OAuth flow using Playwright
+- **Cleanup**: Users are automatically deleted after the benchmark (disable with `--no-cleanup`)
+
+**Example**: Running `--users 5` creates:
+- `loadtest_user_1` (Display: Load Test User 1, Email: loadtest_user_1@benchmark.local)
+- `loadtest_user_2` (Display: Load Test User 2, Email: loadtest_user_2@benchmark.local)
+- `loadtest_user_3` (Display: Load Test User 3, Email: loadtest_user_3@benchmark.local)
+- `loadtest_user_4` (Display: Load Test User 4, Email: loadtest_user_4@benchmark.local)
+- `loadtest_user_5` (Display: Load Test User 5, Email: loadtest_user_5@benchmark.local)
+
+## Metrics Output
+
+### Console Report
+
+```
+================================================================================
+OAUTH MULTI-USER BENCHMARK RESULTS
+================================================================================
+
+Duration: 120.45s
+Total Users: 5
+Total Workflows Executed: 312
+Total Baseline Operations: 678
+
+--------------------------------------------------------------------------------
+WORKFLOW STATISTICS
+--------------------------------------------------------------------------------
+Workflow                         Total  Success     Rate        P50        P95
+--------------------------------------------------------------------------------
+note_share                         112      109    97.3%   0.2341s   0.4782s
+collaborative_edit                  65       61    93.8%   0.5123s   0.9234s
+file_share                          29       29   100.0%   0.3456s   0.6123s
+
+--------------------------------------------------------------------------------
+PER-USER STATISTICS
+--------------------------------------------------------------------------------
+User                  Total Ops    Success   Errors     Rate        P50
+--------------------------------------------------------------------------------
+loadtest_user_1              289        283        6    97.9%   0.2456s
+loadtest_user_2              245        241        4    98.4%   0.2123s
+loadtest_user_3              231        226        5    97.8%   0.2345s
+loadtest_user_4              198        195        3    98.5%   0.2234s
+loadtest_user_5              187        184        3    98.4%   0.2189s
+
+--------------------------------------------------------------------------------
+BASELINE OPERATIONS
+--------------------------------------------------------------------------------
+Total Operations: 678
+Success Rate: 98.2%
+Latency: min=0.0234s, p50=0.1234s, p95=0.3456s, max=0.8123s
+================================================================================
+```
+
+### JSON Export
+
+```json
+{
+  "summary": {
+    "duration": 120.45,
+    "total_workflows": 312,
+    "total_baseline_ops": 678,
+    "total_users": 5
+  },
+  "workflows": {
+    "note_share": {
+      "total_executions": 112,
+      "successful_executions": 109,
+      "failed_executions": 3,
+      "success_rate": 97.3,
+      "latency": {
+        "min": 0.1234,
+        "max": 0.8765,
+        "mean": 0.2891,
+        "median": 0.2341,
+        "p90": 0.4123,
+        "p95": 0.4782,
+        "p99": 0.7234
+      },
+      "step_latencies": {
+        "create_note": {...},
+        "share_note": {...},
+        "list_shared_with_me": {...},
+        "read_shared_note": {...}
+      }
+    }
+  },
+  "users": {
+    "loadtest_user_1": {
+      "total_operations": 289,
+      "successful_operations": 283,
+      "failed_operations": 6,
+      "success_rate": 97.9,
+      "latency": {...},
+      "operations_breakdown": {...},
+      "errors_breakdown": {...}
+    },
+    "loadtest_user_2": {...},
+    "loadtest_user_3": {...},
+    "loadtest_user_4": {...},
+    "loadtest_user_5": {...}
+  },
+  "baseline": {...}
+}
+```
+
+## Implementation Status
+
+### ✅ Completed Components
+
+**Framework:**
+- OAuth user pool management with dynamic user creation
+- User session wrappers with automatic tracking
+- Workflow base classes and framework
+- 3 example workflows (note share, collaborative edit, file share)
+- Enhanced metrics with per-user and workflow tracking
+- CLI interface with multiple workload options
+- Comprehensive reporting (console + JSON)
+
+**OAuth Integration:**
+- ✅ Playwright browser automation for OAuth login
+- ✅ OAuth callback server for auth code capture
+- ✅ Token exchange with OIDC provider
+- ✅ OAuth token injection into MCP sessions via Authorization headers
+- ✅ Cancel scope error handling for reliable cleanup
+- ✅ Dynamic user creation and deletion via Nextcloud Users API
+
+**Implementation Details:**
+The benchmark now successfully:
+1. Creates Nextcloud users dynamically with unique passwords
+2. Acquires OAuth tokens via automated Playwright browser flows
+3. Creates MCP client sessions with proper `Authorization: Bearer {token}` headers
+4. Executes coordinated multi-user workflows
+5. Tracks per-user and per-workflow metrics
+6. Provides standalone cleanup utility for test users
+
+**Key Fix (oauth_pool.py:163-164)**:
+```python
+# Pass OAuth token as Authorization header
+headers = {"Authorization": f"Bearer {profile.token}"}
+streamable_context = streamablehttp_client(mcp_url, headers=headers)
+```
+
+## Creating Custom Workflows
+
+### Example: Permission Escalation Workflow
+
+```python
+class PermissionEscalationWorkflow(Workflow):
+    """Test sharing permission changes."""
+
+    def __init__(self):
+        super().__init__("permission_escalation")
+
+    async def execute(self, users: list[UserSessionWrapper]) -> WorkflowResult:
+        self.start_time = time.time()
+
+        if len(users) < 2:
+            return self._finish(False, error="Requires 2+ users")
+
+        owner, collaborator = users[0], users[1]
+
+        # Step 1: Owner creates note
+        create_result = await self._execute_step(
+            "create_note",
+            owner,
+            lambda: owner.call_tool("nc_notes_create_note", {...})
+        )
+
+        # Step 2: Share read-only
+        await self._execute_step(
+            "share_readonly",
+            owner,
+            lambda: owner.call_tool("nc_share_create", {
+                "permissions": 1  # Read-only
+            })
+        )
+
+        # Step 3: Upgrade to edit permissions
+        await self._execute_step(
+            "upgrade_permissions",
+            owner,
+            lambda: owner.call_tool("nc_share_update", {
+                "permissions": 15  # Read+update+create+delete
+            })
+        )
+
+        # Step 4: Collaborator edits
+        await self._execute_step(
+            "collaborator_edit",
+            collaborator,
+            lambda: collaborator.call_tool("nc_notes_update_note", {...})
+        )
+
+        return self._finish(success=True)
+```
+
+### Registering Custom Workflows
+
+```python
+# In oauth_workloads.py
+class MixedOAuthWorkload:
+    def __init__(self, users: list[UserSessionWrapper]):
+        self.users = users
+        self.workflows = {
+            "note_share": NoteShareWorkflow(),
+            "collaborative_edit": CollaborativeEditWorkflow(),
+            "file_share": FileShareAndDownloadWorkflow(),
+            "permission_escalation": PermissionEscalationWorkflow(),  # Add your workflow
+        }
+```
+
+## Performance Expectations
+
+### Baseline Performance (basic auth, from existing benchmarks)
+- **Throughput**: 50-200 RPS for mixed workload
+- **Latency**: p50 <100ms, p95 <500ms, p99 <1000ms
+
+### OAuth Multi-User Expectations
+- **Lower throughput**: ~30-60% of baseline due to:
+  - OAuth token validation overhead
+  - Cross-user synchronization delays
+  - Workflow coordination overhead
+- **Higher p99 latency**: Due to workflow step dependencies
+- **Focus**: End-to-end workflow completion time more important than raw RPS
+
+### Common Bottlenecks
+1. **OAuth token validation**: Per-request overhead
+2. **Share propagation**: Time for shares to become visible to recipients
+3. **Concurrent edit conflicts**: ETags and conflict resolution
+4. **Permission checks**: Cross-user access validation
+
+## Best Practices
+
+1. **Start Small**: Begin with 2-3 users to validate workflows
+2. **Monitor Errors**: Watch for permission errors and conflicts
+3. **Adjust Delays**: Tune sleep delays between operations based on server response
+4. **Profile Workflows**: Use step latencies to identify bottlenecks
+5. **Export Results**: Always export to JSON for historical comparison
+
+## Performance Optimizations
+
+### Concurrent User Creation
+
+The benchmark creates and authenticates users **concurrently** for maximum performance:
+
+**Step 5: User Creation & OAuth Authentication**
+- All N users are created in parallel using `asyncio.gather()`
+- Each user runs through the full OAuth flow simultaneously
+- Multiple Playwright browser contexts operate independently
+
+**Step 6: MCP Session Creation**
+- All user sessions are created concurrently
+- OAuth tokens passed as Authorization headers to each session
+
+**Performance Impact:**
+- **Sequential** (old): ~10-12s per user → 40-48s for 4 users
+- **Concurrent** (new): ~12-15s total for 4 users (3-4x speedup!)
+
+Example output showing concurrent execution:
+```
+Step 5/6: Creating 4 users and acquiring OAuth tokens...
+(Running concurrently for faster setup)
+
+  [1/4] Creating user 'loadtest_user_1'...
+  [2/4] Creating user 'loadtest_user_2'...
+  [3/4] Creating user 'loadtest_user_3'...
+  [4/4] Creating user 'loadtest_user_4'...
+  ✓ User 'loadtest_user_4' authenticated
+  ✓ User 'loadtest_user_2' authenticated
+  ✓ User 'loadtest_user_1' authenticated
+  ✓ User 'loadtest_user_3' authenticated
+
+✓ Successfully created and authenticated 4 users
+```
+
+**Implementation** (oauth_benchmark.py:402-437):
+```python
+# Create tasks for all users
+tasks = [
+    create_user_task(i, browser, callback_server.auth_states)
+    for i in range(num_users)
+]
+# Run all concurrently
+results = await asyncio.gather(*tasks, return_exceptions=True)
+```
+
+## Cleanup
+
+**Important**: Due to asyncio scoping issues with the MCP client library, automatic cleanup in the benchmark's finally block may not execute reliably. Always use the cleanup utility after running benchmarks.
+
+### Cleanup Utility (Recommended)
+
+Use the cleanup utility to remove test users:
+
+```bash
+# Dry run - see what would be deleted
+uv run python -m tests.load.cleanup_loadtest_users --dry-run
+
+# Delete all loadtest users
+uv run python -m tests.load.cleanup_loadtest_users
+
+# Delete users with custom prefix
+uv run python -m tests.load.cleanup_loadtest_users --prefix mytest
+```
+
+### Disable Automatic Cleanup
+
+To keep test users after the benchmark for inspection:
+
+```bash
+uv run python -m tests.load.oauth_benchmark --users 2 --no-cleanup
+```
+
+## Troubleshooting
+
+### Leftover Test Users
+**Symptom**: Test users remain in Nextcloud after benchmark crashes
+
+**Solution**: Run the cleanup utility:
+```bash
+uv run python -m tests.load.cleanup_loadtest_users
+```
+
+### "User X not in pool" Error
+- Ensure user count doesn't exceed configured limits
+- Check that user creation succeeded in previous steps
+
+### CancelledError During Benchmark
+**Symptom**: Error message like `'CancelledError' object has no attribute 'username'` appears in logs
+
+**Cause**: Async task cancellation during benchmark shutdown or errors can cause race conditions in error handling
+
+**Solution**: This has been mitigated with defensive error handling. The worker now:
+- Catches `asyncio.CancelledError` specifically before general exceptions
+- Logs cancellation gracefully without attempting to access potentially invalid state
+- Re-raises the exception to allow proper cleanup chain
+
+If you still see this error, it's likely harmless and occurs during shutdown. The benchmark results should still be valid.
+
+### High Error Rates
+- Increase delay between operations (`await asyncio.sleep()` in worker)
+- Check OAuth token validity
+- Verify MCP OAuth server is running and accessible (port 8001)
+- Rebuild mcp-oauth container after code changes: `docker-compose up --build -d mcp-oauth`
+
+### Workflows Failing
+- Check step-by-step latencies to identify failing steps
+- Verify users have correct permissions
+- Review server logs for errors
+
+### MCP Session Creation Fails (401 Unauthorized)
+**Solution**: This issue has been fixed! OAuth tokens are now properly passed as Authorization headers when creating MCP sessions.
+
+If you still see 401 errors:
+- Rebuild the mcp-oauth container: `docker-compose up --build -d mcp-oauth`
+- Verify OAuth tokens are being acquired successfully in verbose mode
+- Check that the token hasn't expired (use shorter test durations during troubleshooting)
+
+## Future Enhancements
+
+- [x] Dynamic user creation (beyond 4 default users) - **COMPLETED**
+- [x] OAuth token injection for MCP sessions - **COMPLETED**
+- [x] Cancel scope error handling - **COMPLETED**
+- [x] Concurrent user creation and authentication - **COMPLETED** (3-4x speedup!)
+- [ ] Workflow templates for common patterns
+- [ ] Real-time dashboard for live monitoring
+- [ ] Historical comparison and regression detection
+- [ ] Load ramping (gradual user increase)
+- [ ] Geographic distribution simulation (latency injection)
+- [ ] Improve cleanup reliability in finally block

tests/load/__init__.py

@@ -0,0 +1 @@
+"""Load testing utilities for Nextcloud MCP Server."""