build: bump submodule

feat: Vector visualization enhancements and search optimizations

.env.keycloak.sample

@@ -0,0 +1,138 @@
+# Keycloak OAuth Configuration for Nextcloud MCP Server
+#
+# This configuration uses Keycloak as the OAuth/OIDC identity provider
+# while still accessing Nextcloud APIs. Nextcloud's user_oidc app validates
+# Keycloak bearer tokens and provisions users automatically.
+#
+# Architecture: Client → Keycloak (OAuth) → MCP Server → Nextcloud (user_oidc validates) → APIs
+#
+# This enables ADR-002 authentication patterns without admin credentials!
+
+# ==============================================================================
+# OAUTH PROVIDER SELECTION
+# ==============================================================================
+
+# OAuth provider: "keycloak" or "nextcloud" (default)
+OAUTH_PROVIDER=keycloak
+
+# ==============================================================================
+# KEYCLOAK CONFIGURATION
+# ==============================================================================
+
+# Keycloak base URL (accessible from MCP server container)
+KEYCLOAK_URL=http://keycloak:8080
+
+# Keycloak realm name
+KEYCLOAK_REALM=nextcloud-mcp
+
+# OAuth client credentials (from Keycloak realm export or manual configuration)
+KEYCLOAK_CLIENT_ID=nextcloud-mcp-server
+KEYCLOAK_CLIENT_SECRET=mcp-secret-change-in-production
+
+# OIDC discovery URL (auto-constructed from URL + realm, or specify explicitly)
+KEYCLOAK_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+
+# ==============================================================================
+# NEXTCLOUD CONFIGURATION
+# ==============================================================================
+
+# Nextcloud URL (accessible from MCP server container)
+# Used for API access - Keycloak tokens are validated by user_oidc app
+NEXTCLOUD_HOST=http://app:80
+
+# MCP server URL (for OAuth redirect URIs)
+# This is the publicly accessible URL that OAuth clients connect to
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002
+
+# Public Keycloak issuer URL (accessible from OAuth clients)
+# If clients access Keycloak via a different URL than the internal one,
+# set this to the public URL for OAuth flows
+NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888
+
+# ==============================================================================
+# REFRESH TOKEN STORAGE (ADR-002 Tier 1: Offline Access)
+# ==============================================================================
+
+# Enable offline_access scope to get refresh tokens
+ENABLE_OFFLINE_ACCESS=true
+
+# Encryption key for storing refresh tokens (generate with instructions below)
+# IMPORTANT: Keep this secret! Tokens are encrypted at rest using this key.
+#
+# Generate a key:
+#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+#
+# Example (DO NOT use this in production!):
+# TOKEN_ENCRYPTION_KEY=your-base64-encoded-fernet-key-here
+
+# Path to SQLite database for token storage
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# ==============================================================================
+# DOCKER COMPOSE NOTES
+# ==============================================================================
+
+# When running via docker-compose, the mcp-keycloak service is pre-configured
+# with these environment variables. See docker-compose.yml for the full config.
+#
+# Start services:
+#   docker-compose up -d keycloak app mcp-keycloak
+#
+# View logs:
+#   docker-compose logs -f mcp-keycloak
+#
+# Check Keycloak realm:
+#   curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
+#
+# Check user_oidc provider:
+#   docker compose exec app php occ user_oidc:provider keycloak
+
+# ==============================================================================
+# KEYCLOAK SETUP VERIFICATION
+# ==============================================================================
+
+# 1. Verify Keycloak is running and realm is imported:
+#    curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
+#
+# 2. Verify Nextcloud user_oidc provider is configured:
+#    docker compose exec app php occ user_oidc:provider keycloak
+#
+# 3. Test OAuth flow manually:
+#    - Get token from Keycloak:
+#      curl -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
+#        -d "grant_type=password" \
+#        -d "client_id=nextcloud-mcp-server" \
+#        -d "client_secret=mcp-secret-change-in-production" \
+#        -d "username=admin" \
+#        -d "password=admin" \
+#        -d "scope=openid profile email offline_access"
+#
+#    - Use token with Nextcloud API:
+#      curl -H "Authorization: Bearer <access_token>" \
+#        http://localhost:8080/ocs/v2.php/cloud/capabilities
+#
+# 4. Connect MCP client to server:
+#    - Point your MCP client to http://localhost:8002
+#    - Complete OAuth flow via Keycloak (credentials: admin/admin)
+#    - Client should receive access token and be able to call MCP tools
+
+# ==============================================================================
+# TROUBLESHOOTING
+# ==============================================================================
+
+# If OAuth flow fails:
+# - Check that Keycloak is accessible: curl http://localhost:8888
+# - Check that user_oidc provider is configured: docker compose exec app php occ user_oidc:provider keycloak
+# - Check MCP server logs: docker-compose logs mcp-keycloak
+# - Verify redirect URIs match in Keycloak client configuration
+#
+# If token validation fails:
+# - Verify user_oidc has bearer validation enabled (--check-bearer=1)
+# - Check Nextcloud logs: docker compose exec app tail -f /var/www/html/data/nextcloud.log
+# - Verify Keycloak discovery URL is accessible from Nextcloud container:
+#   docker compose exec app curl http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+#
+# If offline_access/refresh tokens not working:
+# - Verify TOKEN_ENCRYPTION_KEY is set and valid
+# - Check token storage database: ls -lah /app/data/tokens.db (inside container)
+# - Check that offline_access scope is requested in realm configuration

.github/workflows/bump-version.yml

@@ -25,7 +25,7 @@ jobs:
           github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
           changelog_increment_filename: body.md
       - name: Release
-        uses: softprops/action-gh-release@6da8fa9354ddfdc4aeace5fc48d7f679b5214090 # v2.4.1
+        uses: softprops/action-gh-release@5be0e66d93ac7ed76da52eca8bb058f665c3a5fe # v2.4.2
         with:
           body_path: "body.md"
           tag_name: v${{ env.REVISION }}

.github/workflows/docker-build-publish.yml

@@ -16,7 +16,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # v5
+        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5
         with:
           # list of Docker images to use as base name for tags
           images: |

.github/workflows/helm-release.yml

@@ -0,0 +1,134 @@
+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@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+        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: Install Helm
+        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4.3.1
+        with:
+          version: v3.16.0
+
+      - name: Add Helm repositories and update dependencies
+        run: |
+          helm repo add qdrant https://qdrant.github.io/qdrant-helm
+          helm repo add ollama https://otwld.github.io/ollama-helm
+          helm repo update
+          helm dependency build charts/nextcloud-mcp-server
+
+      - name: Run chart-releaser
+        uses: helm/chart-releaser-action@cae68fefc6b5f367a0275617c9f83181ba54714f # v1.7.0
+        env:
+          CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Update gh-pages with Chart README and Index
+        run: |
+          # Get the repository name
+          REPO_NAME="${GITHUB_REPOSITORY##*/}"
+          REPO_OWNER="${GITHUB_REPOSITORY%/*}"
+
+          # Switch to gh-pages branch
+          git fetch origin gh-pages
+          git checkout gh-pages
+
+          # Copy Chart README to root
+          git checkout ${GITHUB_REF#refs/tags/} -- charts/nextcloud-mcp-server/README.md
+          mv charts/nextcloud-mcp-server/README.md README.md || true
+          rm -rf charts 2>/dev/null || true
+
+          # Create index.html with installation instructions
+          cat > index.html <<'EOF'
+          <!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://REPO_OWNER.github.io/REPO_NAME/
+          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/REPO_OWNER/REPO_NAME">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>
+          EOF
+
+          # Replace placeholders
+          sed -i "s/REPO_OWNER/$REPO_OWNER/g" index.html
+          sed -i "s/REPO_NAME/$REPO_NAME/g" index.html
+
+          # Commit changes
+          git add README.md index.html
+          git commit -m "Update README and index from chart release" || echo "No changes to commit"
+          git push origin gh-pages

.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@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
+      - 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,13 +11,16 @@ jobs:
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
       - name: Check format
         run: |
           uv run --frozen ruff format --diff
       - name: Linting
         run: |
           uv run --frozen ruff check
+      - name: Linting
+        run: |
+          uv run --frozen ty check -- nextcloud_mcp_server
 
 
   integration-test:
@@ -25,15 +28,35 @@ 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
         with:
           compose-file: "./docker-compose.yml"
+          #compose-flags: "--profile qdrant"
           up-flags: "--build"
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
 
       - name: Install Playwright dependencies
         run: |
@@ -62,4 +85,4 @@ jobs:
           NEXTCLOUD_USERNAME: "admin"
           NEXTCLOUD_PASSWORD: "admin"
         run: |
-          uv run pytest -v --log-level=INFO
+          uv run pytest -v --log-cli-level=WARN -m smoke

.gitignore

@@ -5,5 +5,11 @@ __pycache__/
 .env.local
 .env.*.local
 
+# Git
+worktrees/
+
+docker-compose.override.yml
+
 # Generated by pytest used to login users
 .nextcloud_oauth_*.json
+.playwright-mcp/

.gitmodules

@@ -0,0 +1,9 @@
+[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
+[submodule "third_party/notes"]
+	path = third_party/notes
+	url = https://github.com/cbcoutinho/notes

.pre-commit-config.yaml

@@ -18,3 +18,9 @@ repos:
       entry: uv run ruff format
       language: system
       types: [python]
+    - id: ty-check
+      name: ty-check
+      language: system
+      types: [python]
+      exclude: tests/.*
+      entry: uv run ty check

CHANGELOG.md

@@ -1,3 +1,416 @@
+## v0.36.0 (2025-11-15)
+
+### BREAKING CHANGE
+
+- Search algorithms now require Qdrant to be populated.
+Vector sync must be enabled and documents indexed for search to work.
+
+### Feat
+
+- Normalize hybrid search RRF scores to 0-1 range
+- Enhance vector visualization UI and parallelize search verification
+- Add Vector Viz tab to app home page
+- Add vector visualization pane with multi-select document types
+- Implement custom PCA to remove sklearn dependency
+- Add multi-document Protocol with cross-app search support
+- Update nc_semantic_search tool with algorithm selection
+- Implement unified search algorithm module
+
+### Fix
+
+- Reorder tabs and fix viz pane session access
+
+### Refactor
+
+- Optimize Nextcloud access verification with centralized filtering
+- Make all search algorithms query Qdrant payload, not Nextcloud
+
+### Perf
+
+- Exclude vector-sync status polling from distributed tracing
+
+## v0.35.0 (2025-11-15)
+
+### Feat
+
+- Enable SSE transport for mcp service and update test fixtures
+
+## v0.34.2 (2025-11-13)
+
+### Fix
+
+- Use NEXTCLOUD_OIDC_CLIENT_ID/SECRET env vars consistently
+
+## v0.34.1 (2025-11-13)
+
+### Fix
+
+- return all notes when search query is empty
+
+## v0.34.0 (2025-11-13)
+
+### Feat
+
+- Complete Phase 5 - Instrument all 93 MCP tools
+- Add instrumentation decorator and apply to notes tools (Phase 5)
+- Add OAuth token and database metrics (Phases 3-4)
+- Add metrics instrumentation for queue, health, and database operations
+
+## v0.33.1 (2025-11-13)
+
+### Fix
+
+- Move grafana_folder from labels to annotations
+
+## v0.33.0 (2025-11-13)
+
+### Feat
+
+- Add Grafana dashboard and vector sync metric instrumentation
+
+## v0.32.1 (2025-11-12)
+
+### Fix
+
+- add dynamic dimension detection for Ollama embedding models
+
+## v0.32.0 (2025-11-11)
+
+### Feat
+
+- **ollama**: Pull model on startup if not available in ollama
+- add dynamic vector sync status updates with htmx polling
+- add webhook management UI and BeforeNodeDeletedEvent support
+- validate Nextcloud webhook schemas and document findings
+
+### Fix
+
+- improve webapp tab UI with CSS Grid and viewport-filling container
+
+### Refactor
+
+- move webapp from /user/page to /app
+- consolidate database storage for webhooks and OAuth tokens
+
+## v0.31.1 (2025-11-10)
+
+### Refactor
+
+- simplify OpenTelemetry tracing configuration
+
+## v0.31.0 (2025-11-10)
+
+### Feat
+
+- skip tracing for health and metrics endpoints
+
+### Fix
+
+- add retry logic for ETag conflicts in category change test
+- optimize Notes API pagination with pruneBefore parameter
+
+## v0.30.0 (2025-11-10)
+
+### Feat
+
+- **helm**: Add document chunking configuration
+- **vector**: Add configurable chunk size and overlap for document embedding
+- **vector**: Support multiple embedding models with auto-generated collection names
+
+### Fix
+
+- Support in-memory Qdrant for CI testing
+
+## v0.29.2 (2025-11-09)
+
+### Fix
+
+- **helm**: Set default strategy to Recreate
+
+## v0.29.1 (2025-11-09)
+
+### Fix
+
+- **observability**: isolate metrics endpoint to dedicated port
+
+## v0.29.0 (2025-11-09)
+
+### Feat
+
+- **helm**: Add observability support with ServiceMonitor and Grafana dashboard
+
+### Fix
+
+- **readiness**: Only check external Qdrant in network mode
+
+## v0.28.0 (2025-11-09)
+
+### Feat
+
+- **observability**: Add comprehensive monitoring with Prometheus and OpenTelemetry
+
+### Fix
+
+- **vector**: Handle missing 'modified' field in notes gracefully
+
+## v0.27.3 (2025-11-09)
+
+### Fix
+
+- **ci**: Use helm dependency build instead of update to use Chart.lock
+
+## v0.27.2 (2025-11-09)
+
+### Fix
+
+- **helm**: update Qdrant dependency condition to match new mode structure
+
+## v0.27.1 (2025-11-09)
+
+### Fix
+
+- **ci**: add Helm repository setup to chart release workflow
+
+## v0.27.0 (2025-11-09)
+
+### Feat
+
+- **helm**: add Qdrant local mode support with three deployment options [skip ci]
+- add Qdrant local mode support with in-memory and persistent storage
+- implement ADR-009 - refactor semantic search to use generic semantic:read scope
+- implement MCP sampling for semantic search RAG (ADR-008)
+- add optional vector database and semantic search to helm chart
+- add vector sync processing status to /app endpoint
+- implement semantic search tool and fix vector sync issues (ADR-007 Phase 3)
+- implement vector sync scanner and processor (ADR-007 Phase 2)
+
+### Fix
+
+- implement deletion grace period and vector sync status tool
+- remove unnecessary urllib3<2.0 constraint
+- integrate vector sync tasks with Starlette lifespan for streamable-http
+
+### Refactor
+
+- migrate vector sync from asyncio.Queue to anyio memory object streams
+- update to Qdrant query_points API and fix Playwright Keycloak login
+
+## v0.26.1 (2025-11-08)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.21,<1.22
+
+## v0.26.0 (2025-11-08)
+
+### Feat
+
+- add real elicitation integration test with python-sdk MCP client
+- unify session architecture and enhance login status visibility
+
+### Fix
+
+- Consolidate OAuth callbacks and implement PKCE for all flows
+
+## v0.25.0 (2025-11-05)
+
+### BREAKING CHANGE
+
+- All OAuth deployments must be reconfigured to specify
+resource URIs (NEXTCLOUD_MCP_SERVER_URL and NEXTCLOUD_RESOURCE_URI) and
+choose between multi-audience or token exchange mode.
+
+### Feat
+
+- Implement ADR-005 unified token verifier to eliminate token passthrough vulnerability
+
+### Fix
+
+- Implement proper OAuth resource parameters and PRM-based discovery
+- Simplify token verifier to be RFC 7519 compliant
+- Use Keycloak client ID for NEXTCLOUD_RESOURCE_URI in token exchange
+- Correct OAuth token audience validation for multi-audience mode
+
+### Refactor
+
+- Eliminate duplicate validation logic in UnifiedTokenVerifier
+
+## v0.24.1 (2025-11-04)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.20,<1.21
+
+## v0.24.0 (2025-11-04)
+
+### Feat
+
+- add scope protection to OAuth provisioning tools
+- enable authorization services for token exchange in Keycloak
+- implement scope-based audience mapping and RFC 9728 support
+- integrate token exchange into MCP server application
+- implement RFC 8693 Standard Token Exchange for Keycloak
+- Add userinfo route/page
+- add browser-based user info page with separate OAuth flow
+- Implement ADR-004 Progressive Consent foundation (partial)
+- Complete ADR-004 Progressive Consent OAuth flows implementation
+- Implement ADR-004 Progressive Consent foundation components
+- Implement ADR-004 Hybrid Flow with comprehensive integration tests
+
+### Fix
+
+- add missing await for get_nextcloud_client in capabilities resource
+- use valid Fernet encryption keys in token exchange tests
+- accept resource URL in token audience for Nextcloud JWT tokens
+- remove token-exchange-nextcloud scope and accept tokens without audience
+- move audience mapper from scope to nextcloud-mcp-server client
+- move token-exchange-nextcloud from default to optional scopes
+- restructure routes to prevent SessionAuthBackend from interfering with FastMCP OAuth
+- allow OAuth Bearer tokens on /mcp endpoint by excluding from session auth
+- correct OAuth token audience validation using RFC 8707 resource parameter
+- remove remaining references to deleted oauth_callback and oauth_token
+- remove Hybrid Flow, make Progressive Consent default (ADR-004)
+- browser OAuth userinfo endpoint and refresh token rotation
+- make ENABLE_PROGRESSIVE_CONSENT consistently opt-in (default false)
+- make provisioning checks opt-in (default false)
+- Disable Progressive Consent for mcp-oauth to enable Hybrid Flow tests
+
+### Refactor
+
+- integrate token exchange into unified get_client() pattern
+
+## v0.23.0 (2025-11-03)
+
+### Feat
+
+- Auto-configure impersonation role in Keycloak realm import
+- Implement dual-tier token exchange (Standard V2 + Legacy V1 impersonation)
+- Add Keycloak external IdP integration with custom scopes
+- Implement RFC 8693 token exchange for Keycloak (ADR-002 Tier 2)
+- Add Keycloak OAuth provider support with refresh token storage
+
+### Fix
+
+- Complete Keycloak external IdP integration with all tests passing
+- Complete Keycloak external IdP integration with all tests passing
+- Update DCR token_type tests for OIDC app changes
+
+### Refactor
+
+- Remove NEXTCLOUD_OIDC_CLIENT_STORAGE environment variable
+- Remove unnecessary user_oidc patch - CORSMiddleware patch is sufficient
+- Unify OAuth configuration to be provider-agnostic
+
+## v0.22.7 (2025-10-29)
+
+### Fix
+
+- **helm**: Remove image tag overide
+
+## v0.22.6 (2025-10-29)
+
+### Fix
+
+- **helm**: Update helm chart with extraArgs
+
+## v0.22.5 (2025-10-29)
+
+### Fix
+
+- Update helm chart variables
+
+## v0.22.4 (2025-10-29)
+
+### Fix
+
+- **helm**: Update helm version with release
+- **helm**: Update helm version with release
+
+## v0.22.3 (2025-10-29)
+
+### Fix
+
+- **helm**: Update helm version with release
+
+## v0.22.2 (2025-10-29)
+
+### Fix
+
+- **helm**: Update helm version with release
+
+## v0.22.1 (2025-10-29)
+
+### Fix
+
+- Trigger release
+
+## 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

CLAUDE.md

@@ -2,253 +2,396 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Development Commands
+## Coding Conventions
+
+### async/await Patterns
+- **Use anyio + asyncio hybrid** - Both libraries are available
+  - pytest runs in `anyio` mode (`anyio_mode = "auto"` in pyproject.toml)
+  - asyncio used in auth modules (refresh_token_storage.py, token_exchange.py, token_broker.py)
+  - anyio used in calendar.py, client_registration.py, app.py
+  - Prefer standard async/await syntax without explicit library imports when possible
+
+### Type Hints
+- **Use Python 3.10+ union syntax**: `str | None` instead of `Optional[str]`
+- **Use lowercase generics**: `dict[str, Any]` instead of `Dict[str, Any]`
+- **Type all function signatures** - Parameters and return types
+- **No explicit type checker configured** - Ruff handles linting only
+
+### Code Quality
+- **Run ruff before committing**:
+  ```bash
+  uv run ruff check
+  uv run ruff format
+  ```
+- **Ruff configuration** in pyproject.toml (extends select: ["I"] for import sorting)
+
+### Error Handling
+- **Use custom decorators**: `@retry_on_429` for rate limiting (see base_client.py)
+- **Standard exceptions**: `HTTPStatusError` from httpx, `McpError` for MCP-specific errors
+- **Logging patterns**:
+  - `logger.debug()` for expected 404s and normal operations
+  - `logger.warning()` for retries and non-critical issues
+  - `logger.error()` for actual errors
+
+### Testing Patterns
+- **Use existing fixtures** from `tests/conftest.py` (2888 lines of test infrastructure)
+- **Session-scoped fixtures** handle anyio/pytest-asyncio incompatibility
+- **Mocked unit tests** use `mocker.AsyncMock(spec=httpx.AsyncClient)`
+- **pytest-timeout**: 180s default per test
+- **Mark tests appropriately**: `@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.oauth`, `@pytest.mark.smoke`
+
+### Architectural Patterns
+- **Base classes**: `BaseNextcloudClient` for all API clients
+- **Pydantic responses**: All MCP tools return Pydantic models inheriting from `BaseResponse`
+- **Decorators**: `@require_scopes`, `@require_provisioning` for access control
+- **Context pattern**: `await get_client(ctx)` to access authenticated NextcloudClient (async!)
+- **FastMCP decorators**: `@mcp.tool()`, `@mcp.resource()`
+- **Token acquisition**: `get_client()` handles both pass-through and token exchange modes
+  - Pass-through (default): Simple, stateless (ENABLE_TOKEN_EXCHANGE=false)
+  - Token exchange (opt-in): RFC 8693 delegation (ENABLE_TOKEN_EXCHANGE=true)
+
+### Project Structure
+- `nextcloud_mcp_server/client/` - HTTP clients for Nextcloud APIs
+- `nextcloud_mcp_server/server/` - MCP tool/resource definitions
+- `nextcloud_mcp_server/auth/` - OAuth/OIDC authentication
+- `nextcloud_mcp_server/models/` - Pydantic response models
+- `tests/` - Layered test suite (unit, smoke, integration, load)
+
+## Development Commands (Quick Reference)
 
 ### Testing
 ```bash
-# Run all tests
-uv run pytest
+# Fast feedback (recommended)
+uv run pytest tests/unit/ -v                    # Unit tests (~5s)
+uv run pytest -m smoke -v                       # Smoke tests (~30-60s)
 
-# Run integration tests only
-uv run pytest -m integration
+# Integration tests
+uv run pytest -m "integration and not oauth" -v # Without OAuth (~2-3min)
+uv run pytest -m oauth -v                       # OAuth only (~3min)
+uv run pytest                                   # Full suite (~4-5min)
 
-# Run tests with coverage
+# Coverage
 uv run pytest --cov
 
-# Skip integration tests
-uv run pytest -m "not integration"
+# Specific tests after changes
+uv run pytest tests/server/test_mcp.py -k "notes" -v
+uv run pytest tests/client/notes/test_notes_api.py -v
+```
+
+**Important**: After code changes, rebuild the correct container:
+- Single-user tests: `docker-compose up --build -d mcp`
+- OAuth tests: `docker-compose up --build -d mcp-oauth`
+- Keycloak tests: `docker-compose up --build -d mcp-keycloak`
+
+### Running the Server
+```bash
+# Local development
+export $(grep -v '^#' .env | xargs)
+mcp run --transport sse nextcloud_mcp_server.app:mcp
+
+# Docker development (rebuilds after code changes)
+docker-compose up --build -d mcp        # Single-user (port 8000)
+docker-compose up --build -d mcp-oauth  # Nextcloud OAuth (port 8001)
+docker-compose up --build -d mcp-keycloak  # Keycloak OAuth (port 8002)
+```
+
+### Environment Setup
+```bash
+uv sync                # Install dependencies
+uv sync --group dev    # Install with dev dependencies
 ```
 
 ### Load Testing
 ```bash
-# Run benchmark with default settings (10 workers, 30 seconds)
+# Quick test (default: 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
+# Custom concurrency and duration
+uv run python -m tests.load.benchmark -c 20 -d 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
+# Export results for analysis
+uv run python -m tests.load.benchmark --output results.json --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
+**Expected Performance**: 50-200 RPS for mixed workload, p50 <100ms, p95 <500ms, p99 <1000ms.
 
-**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
+## Database Inspection
 
-**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
+**Credentials**: root/password, nextcloud/password, database: `nextcloud`
 
-### Code Quality
 ```bash
-# Format and lint code
-uv run ruff check
-uv run ruff format
+# Connect to database
+docker compose exec db mariadb -u root -ppassword nextcloud
 
-# Type checking
-# No explicit type checker configured - this is a Python project using ruff for linting
+# 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;"
 ```
 
-### Running the Server
-```bash
-# Local development - load environment variables and run
-export $(grep -v '^#' .env | xargs)
-mcp run --transport sse nextcloud_mcp_server.app:mcp
+**Important Tables**:
+- `oc_oidc_clients` - OAuth client registrations (DCR)
+- `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
+- `oc_oidc_redirect_uris` - Redirect URIs
 
-# Docker development environment with Nextcloud instance
-docker-compose up
+## Architecture Quick Reference
 
-# After code changes, rebuild and restart the appropriate MCP server container:
-# For basic auth changes (most common) - uses admin credentials
-docker-compose up --build -d mcp
+**For detailed architecture, see:**
+- `docs/comparison-context-agent.md` - Overall architecture
+- `docs/oauth-architecture.md` - OAuth integration patterns
+- `docs/ADR-004-progressive-consent.md` - Progressive consent implementation
 
-# For OAuth changes - uses OAuth authentication flow
-docker-compose up --build -d mcp-oauth
+**Core Components**:
+- `nextcloud_mcp_server/app.py` - FastMCP server entry point
+- `nextcloud_mcp_server/client/` - HTTP clients (Notes, Calendar, Contacts, Tables, WebDAV)
+- `nextcloud_mcp_server/server/` - MCP tool/resource definitions
+- `nextcloud_mcp_server/auth/` - OAuth/OIDC authentication
 
-# Build Docker image
-docker build -t nextcloud-mcp-server .
-```
+**Supported Apps**: Notes, Calendar (CalDAV + VTODO tasks), Contacts (CardDAV), Tables, WebDAV, Deck, Cookbook
 
-**Important: Two 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.
+**Key Patterns**:
+1. `NextcloudClient` orchestrates all app-specific clients
+2. `BaseNextcloudClient` provides common HTTP functionality + retry logic
+3. MCP tools use context pattern: `get_client(ctx)` → `NextcloudClient`
+4. All operations are async using httpx
 
-### Environment Setup
-```bash
-# Install dependencies
-uv sync
+### Progressive Consent Architecture (ADR-004)
 
-# Install development dependencies
-uv sync --group dev
-```
+**Important**: Progressive consent is a *mechanism* for granting access, not a feature flag. The architecture is always present in OAuth mode. Whether provisioning tools are available is controlled by `ENABLE_OFFLINE_ACCESS`.
 
-## Architecture Overview
+**What is Progressive Consent?**
+- Dual OAuth flow architecture that separates client authentication (Flow 1) from resource provisioning (Flow 2)
+- Flow 1: MCP client authenticates directly to IdP with resource scopes (notes:*, calendar:*, etc.)
+  - Token audience: "mcp-server"
+  - Client receives resource-scoped token for MCP session
+- Flow 2: Server explicitly provisions Nextcloud access via separate login (only when `ENABLE_OFFLINE_ACCESS=true`)
+  - Server requests: openid, profile, email, offline_access
+  - Token audience: "nextcloud"
+  - Server receives refresh token for offline access
+  - Client never sees this token
+- Provides clear separation between session tokens and offline access tokens
 
-This is a Python MCP (Model Context Protocol) server that provides LLM integration with Nextcloud. The architecture follows a layered pattern:
+**Modes:**
+- **Pass-through mode** (`ENABLE_OFFLINE_ACCESS=false`, default):
+  - No Flow 2 provisioning
+  - Server uses client's token to access Nextcloud (pass-through)
+  - No provisioning tools available
+  - Suitable for stateless, client-driven operations
+- **Offline access mode** (`ENABLE_OFFLINE_ACCESS=true`):
+  - Flow 2 provisioning available
+  - Server stores refresh tokens for background operations
+  - Provisioning tools available: `provision_nextcloud_access`, `check_logged_in`
+  - Suitable for background jobs and server-initiated operations
 
-### Core Components
+**When to use OAuth mode:**
+- Multi-user deployments
+- Background jobs requiring offline access (with `ENABLE_OFFLINE_ACCESS=true`)
+- Enhanced security with separate authorization contexts
+- Explicit user control over resource access
 
-- **`nextcloud_mcp_server/app.py`** - Main MCP server entry point using FastMCP framework
-- **`nextcloud_mcp_server/client/`** - HTTP client implementations for different Nextcloud APIs
-- **`nextcloud_mcp_server/server/`** - MCP tool/resource definitions that expose client functionality
-- **`nextcloud_mcp_server/controllers/`** - Business logic controllers (e.g., notes search)
+**When to use BasicAuth instead:**
+- Simple single-user deployments
+- Local development and testing
 
-### Client Architecture
+**Key features:**
+- No scope escalation - client gets exactly what it requests
+- User explicitly authorizes via `provision_nextcloud_access` tool
+- Clear security boundaries between MCP session and Nextcloud access
 
-- **`NextcloudClient`** - Main orchestrating client that manages all app-specific clients
-- **`BaseNextcloudClient`** - Abstract base class providing common HTTP functionality and retry logic
-- **App-specific clients**: `NotesClient`, `CalendarClient`, `ContactsClient`, `TablesClient`, `WebDAVClient`
+## MCP Response Patterns (CRITICAL)
 
-### Server Integration
+**Never return raw `List[Dict]` from MCP tools** - FastMCP mangles them into dicts with numeric string keys.
 
-Each Nextcloud app has a corresponding server module that:
-1. Defines MCP tools using `@mcp.tool()` decorators
-2. Defines MCP resources using `@mcp.resource()` decorators
-3. Uses the context pattern to access the `NextcloudClient` instance
-
-### Supported Nextcloud Apps
-
-- **Notes** - Full CRUD operations and search
-- **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
-
-### Key Patterns
-
-1. **Environment-based configuration** - Uses `NextcloudClient.from_env()` to load credentials from environment variables
-2. **Async/await throughout** - All operations are async using httpx
-3. **Retry logic** - `@retry_on_429` decorator handles rate limiting
-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:**
+**Correct 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`
+**Reference implementations**:
+- `nextcloud_mcp_server/models/notes.py:80` - `SearchNotesResponse`
+- `nextcloud_mcp_server/models/webdav.py:113` - `SearchFilesResponse`
+- `nextcloud_mcp_server/server/{notes,webdav}.py` - Tool examples
 
-**Testing:** Extract `data["results"]` from MCP responses, not `data` directly.
+**Testing**: Extract `data["results"]` from MCP responses, not `data` directly.
 
-### Testing Structure
+## MCP Sampling for RAG (ADR-008)
 
-- **Integration tests** in `tests/client/` and `tests/server/` - Test real Nextcloud API interactions
-- **Fixtures** in `tests/conftest.py` - Shared test setup and utilities
-- Tests are marked with `@pytest.mark.integration` for selective running
-- **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`
+**What is MCP Sampling?**
+MCP sampling allows servers to request LLM completions from their clients. This enables Retrieval-Augmented Generation (RAG) patterns where the server retrieves context and the client's LLM generates answers.
 
-#### Testing Best Practices
-- **MANDATORY: Always run tests after implementing features or fixing bugs**
-  - Run tests to completion before considering any task complete
-  - If tests require modifications to pass, ask for permission before proceeding
-  - **Rebuild the correct container** after code changes:
-    - For basic auth tests (most common): `docker-compose up --build -d mcp`
-    - For OAuth tests: `docker-compose up --build -d mcp-oauth`
-- **Use existing fixtures** from `tests/conftest.py` to avoid duplicate setup work:
-  - `nc_mcp_client` - MCP client session for tool/resource testing (uses `mcp` container)
-  - `nc_mcp_oauth_client` - MCP client session for OAuth testing (uses `mcp-oauth` container)
-  - `nc_client` - Direct NextcloudClient for setup/cleanup operations
-  - `temporary_note` - Creates and cleans up test notes automatically
-  - `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/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
+**When to use sampling:**
+- Generating natural language answers from retrieved documents
+- Synthesizing information from multiple sources
+- Creating summaries with citations
 
-#### OAuth/OIDC Testing
-OAuth integration tests use **automated Playwright browser automation** to complete the OAuth flow programmatically.
+**Implementation Pattern** (see ADR-008 for details):
 
-**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
-  - Each user gets their own unique access token
-  - Implementation: `shared_oauth_client_credentials` fixture in `tests/conftest.py`
-- **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
-- Uses `pytest-playwright-asyncio` for async Playwright fixtures
-- **Playwright configuration**: Use pytest CLI args like `--browser firefox --headed` to customize
-- **Install browsers**: `uv run playwright install firefox` (or `chromium`, `webkit`)
+```python
+from mcp.types import ModelHint, ModelPreferences, SamplingMessage, TextContent
 
-**Example Commands:**
-```bash
-# Run all OAuth tests with Playwright automation using Firefox
-uv run pytest tests/server/test_oauth*.py --browser firefox -v
+@mcp.tool()
+@require_scopes("notes:read")
+async def nc_notes_semantic_search_answer(
+    query: str, ctx: Context, limit: int = 5, max_answer_tokens: int = 500
+) -> SamplingSearchResponse:
+    # 1. Retrieve documents
+    search_response = await nc_notes_semantic_search(query, ctx, limit)
 
-# Run specific tests with visible browser for debugging
-uv run pytest tests/server/test_mcp_oauth.py --browser firefox --headed -v
+    # 2. Check for no results (don't waste sampling call)
+    if not search_response.results:
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer="No relevant documents found.",
+            sources=[], total_found=0, success=True
+        )
 
-# Run with Chromium (default)
-uv run pytest tests/server/test_oauth*.py -v
+    # 3. Construct prompt with retrieved context
+    prompt = f"{query}\n\nDocuments:\n{format_sources(search_response.results)}\n\nProvide answer with citations."
+
+    # 4. Request LLM completion via sampling
+    try:
+        result = await ctx.session.create_message(
+            messages=[SamplingMessage(role="user", content=TextContent(type="text", text=prompt))],
+            max_tokens=max_answer_tokens,
+            temperature=0.7,
+            model_preferences=ModelPreferences(
+                hints=[ModelHint(name="claude-3-5-sonnet")],
+                intelligencePriority=0.8,
+                speedPriority=0.5,
+            ),
+            include_context="thisServer",
+        )
+
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=result.content.text,
+            sources=search_response.results,
+            model_used=result.model,
+            stop_reason=result.stopReason,
+            success=True
+        )
+    except Exception as e:
+        # Fallback: Return documents without generated answer
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=f"[Sampling unavailable: {e}]\n\nFound {len(search_response.results)} documents.",
+            sources=search_response.results,
+            search_method="semantic_sampling_fallback",
+            success=True
+        )
 ```
 
-**Test Environment:**
-- **Two MCP server containers are available:**
-  - `mcp` (port 8000): Uses basic auth with admin credentials - for most testing
-  - `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`
+**Key Points**:
+- **No server-side LLM**: Server has no API keys, client controls which model is used
+- **Graceful degradation**: Tool always returns useful results even if sampling fails
+- **User control**: MCP clients SHOULD prompt users to approve sampling requests
+- **No results optimization**: Skip sampling call when no documents found
+- **Fixed prompts**: Prompts are not user-configurable to avoid injection risks
 
-**CI/CD Notes:**
-- Playwright tests run in CI/CD environments
-- Use Firefox browser in CI: `--browser firefox` (Chromium may have issues with localhost redirects)
+**Reference**: See `nc_notes_semantic_search_answer` in `nextcloud_mcp_server/server/notes.py:517` and ADR-008 for complete implementation.
 
-### Configuration Files
+## Testing Best Practices (MANDATORY)
 
-- **`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
+### Always Run Tests
+- **Run tests to completion** before considering any task complete
+- **Rebuild the correct container** after code changes (see Development Commands above)
+- **If tests require modifications**, ask for permission before proceeding
+
+### Use Existing Fixtures
+See `tests/conftest.py` for 2888 lines of test infrastructure:
+- `nc_mcp_client` - MCP client for tool/resource testing (uses `mcp` container)
+- `nc_mcp_oauth_client` - MCP client for OAuth testing (uses `mcp-oauth` container)
+- `nc_client` - Direct NextcloudClient for setup/cleanup
+- `temporary_note`, `temporary_addressbook`, `temporary_contact` - Auto-cleanup
+
+### Writing Mocked Unit Tests
+For client-layer response parsing tests, use mocked HTTP responses:
+
+```python
+async def test_notes_api_get_note(mocker):
+    """Test that get_note correctly parses the API response."""
+    mock_response = create_mock_note_response(
+        note_id=123, title="Test Note", content="Test content",
+        category="Test", etag="abc123"
+    )
+
+    mock_make_request = mocker.patch.object(
+        NotesClient, "_make_request", return_value=mock_response
+    )
+
+    client = NotesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
+    note = await client.get_note(note_id=123)
+
+    assert note["id"] == 123
+    mock_make_request.assert_called_once_with("GET", "/apps/notes/api/v1/notes/123")
+```
+
+**Mock helpers in `tests/conftest.py`**: `create_mock_response()`, `create_mock_note_response()`, `create_mock_error_response()`
+
+**When to use**: Response parsing, error handling, request parameter building
+**When NOT to use**: CalDAV/CardDAV/WebDAV protocols, OAuth flows, end-to-end MCP testing
+
+### OAuth Testing
+OAuth tests use **Playwright browser automation** to complete flows programmatically.
+
+**Test Environment**:
+- Three MCP containers: `mcp` (single-user), `mcp-oauth` (Nextcloud OIDC), `mcp-keycloak` (external IdP)
+- OAuth tests require `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD` environment variables
+- Playwright configuration: `--browser firefox --headed` for debugging
+- Install browsers: `uv run playwright install firefox`
+
+**OAuth fixtures**: `nc_oauth_client`, `nc_mcp_oauth_client`, `alice_oauth_token`, `bob_oauth_token`, etc.
+
+**Shared OAuth Client**: All test users authenticate using a single OAuth client (created via DCR, deleted at session end via RFC 7592). Matches production behavior.
+
+**Run OAuth tests**:
+```bash
+uv run pytest -m oauth -v                        # All OAuth tests
+uv run pytest tests/server/oauth/ --browser firefox -v
+uv run pytest tests/server/oauth/test_oauth_core.py --browser firefox --headed -v
+```
+
+### Keycloak OAuth Testing
+**Validates ADR-002 architecture** for external identity providers and offline access patterns.
+
+**Architecture**: `MCP Client → Keycloak (OAuth) → MCP Server → Nextcloud user_oidc (validates token) → APIs`
+
+**Setup**:
+```bash
+docker-compose up -d keycloak app mcp-keycloak
+curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
+docker compose exec app php occ user_oidc:provider keycloak
+```
+
+**Credentials**: admin/admin (Keycloak realm: `nextcloud-mcp`)
+
+**For detailed Keycloak setup, see**:
+- `docs/oauth-setup.md` - OAuth configuration
+- `docs/ADR-002-vector-sync-authentication.md` - Offline access architecture
+- `docs/audience-validation-setup.md` - Token audience validation
+- `docs/keycloak-multi-client-validation.md` - Realm-level validation
+
+## Integration Testing with Docker
+
+**Nextcloud**: `docker compose exec app php occ ...` for occ commands
+**MariaDB**: `docker compose exec db mariadb -u [user] -p [password] [database]` for queries
+
+**For detailed setup, see**:
+- `docs/installation.md` - Installation guide
+- `docs/configuration.md` - Configuration options
+- `docs/authentication.md` - Authentication modes
+- `docs/running.md` - Running the server
+
+**For additional information regarding MCP during development, see**:
+- `../../Software/modelcontextprotocol/` - MCP spec
+- `../../Software/python-sdk/` - Python MCP SDK

Dockerfile

@@ -1,14 +1,17 @@
-FROM ghcr.io/astral-sh/uv:0.9.4-python3.11-alpine@sha256:1a51c7710eaf839fa3365329ad993b48d17ddd9ab0f0672efaa9b09f407ebf44
+FROM ghcr.io/astral-sh/uv:0.9.9-python3.11-alpine@sha256:0faa7934fac1db7f5056f159c1224d144bab864fd2677a4066d25a686ae32edd
 
-# Install git (required for caldav dependency from git)
-RUN apk add --no-cache git
+# Install dependencies
+# 1. git (required for caldav dependency from git)
+# 2. sqlite for development with token db
+RUN apk add --no-cache git sqlite
 
 WORKDIR /app
 
 COPY . .
 
-RUN uv sync --locked --no-dev
+RUN uv sync --locked --no-dev --no-editable
 
 ENV PYTHONUNBUFFERED=1
+ENV VIRTUAL_ENV=/app/.venv
 
 ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "--host", "0.0.0.0"]

README.md

@@ -2,189 +2,134 @@
 
 [![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)
 
-**Enable AI assistants to interact with your Nextcloud instance.**
+**A production-ready MCP server that connects AI assistants to your Nextcloud instance.**
 
-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.
+Enable 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 conversations.
+
+This is a **dedicated standalone MCP server** designed for external MCP clients like Claude Code and IDEs. It runs independently of Nextcloud (Docker, VM, Kubernetes, or local) and provides deep CRUD operations across Nextcloud apps.
 
 > [!NOTE]
-> **Nextcloud has two ways to enable AI access:** Nextcloud provides [Context Agent](https://github.com/nextcloud/context_agent), an AI agent backend that powers the [Assistant](https://github.com/nextcloud/assistant) app and allows AI to interact with Nextcloud apps like Calendar, Talk, and Contacts. Context Agent runs as an ExApp inside Nextcloud and also exposes an MCP server endpoint for external LLMs. This project (Nextcloud MCP Server) is a **dedicated standalone MCP server** designed specifically for external MCP clients like Claude Code and IDEs, with deep CRUD operations and OAuth support. See our [detailed comparison](docs/comparison-context-agent.md) to understand which approach fits your use case.
-
-## Features
-
-### Supported Nextcloud Apps
-
-| 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.
+> **Looking for AI features inside Nextcloud?** Nextcloud also provides [Context Agent](https://github.com/nextcloud/context_agent), which powers the Assistant app and runs as an ExApp inside Nextcloud. See [docs/comparison-context-agent.md](docs/comparison-context-agent.md) for a detailed comparison of use cases.
 
 ## Quick Start
 
-### 1. Install
+Get up and running in 60 seconds using Docker:
 
 ```bash
-# Clone the repository
-git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
-cd nextcloud-mcp-server
-
-# Install with uv (recommended)
-uv sync
-
-# Or using Docker
-docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
-```
-
-See [Installation Guide](docs/installation.md) for detailed instructions.
-
-### 2. Configure
-
-Create a `.env` file:
-
-```bash
-# Copy the sample
-cp env.sample .env
-```
-
-**For Basic Auth (recommended for most users):**
-```dotenv
+# 1. Create a minimal configuration
+cat > .env << EOF
 NEXTCLOUD_HOST=https://your.nextcloud.instance.com
 NEXTCLOUD_USERNAME=your_username
 NEXTCLOUD_PASSWORD=your_app_password
-```
+EOF
 
-**For OAuth (experimental - requires patches):**
-```dotenv
-NEXTCLOUD_HOST=https://your.nextcloud.instance.com
-```
-
-See [Configuration Guide](docs/configuration.md) for all options.
-
-### 3. Set Up Authentication
-
-**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
-
-**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
-
-See [OAuth Quick Start](docs/quickstart-oauth.md) for 5-minute setup or [OAuth Setup Guide](docs/oauth-setup.md) for detailed instructions.
-
-### 4. Run the Server
-
-```bash
-# Load environment variables
-export $(grep -v '^#' .env | xargs)
-
-# Start with Basic Auth (default)
-uv run nextcloud-mcp-server
-
-# Or start with OAuth (experimental - requires patches)
-uv run nextcloud-mcp-server --oauth
-
-# Or with Docker
+# 2. Start the server
 docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
   ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+
+# 3. Test the connection
+curl http://127.0.0.1:8000/health/ready
 ```
 
-The server starts on `http://127.0.0.1:8000` by default.
+**Next Steps:**
+- Create an app password in Nextcloud: Settings → Security → Devices & sessions
+- Connect your MCP client (Claude Desktop, IDEs, `mcp dev`, etc.)
+- See [docs/installation.md](docs/installation.md) for other deployment options (local, Kubernetes)
 
-See [Running the Server](docs/running.md) for more options.
+## Key Features
 
-### 5. Connect an MCP Client
+- **90+ MCP Tools** - Comprehensive API coverage across 8 Nextcloud apps
+- **MCP Resources** - Structured data URIs for browsing Nextcloud data
+- **Semantic Search (Experimental)** - Optional vector-powered search for Notes (requires Qdrant + Ollama)
+- **Document Processing** - OCR and text extraction from PDFs, DOCX, images with progress notifications
+- **Flexible Deployment** - Docker, Kubernetes (Helm), VM, or local installation
+- **Production-Ready Auth** - Basic Auth with app passwords (recommended) or OAuth2/OIDC (experimental)
+- **Multiple Transports** - SSE, HTTP, and streamable-http support
 
-Test with MCP Inspector:
+## Supported Apps
 
-```bash
-uv run mcp dev
-```
+| App | Tools | Capabilities |
+|-----|-------|--------------|
+| **Notes** | 7 | Full CRUD, keyword search, semantic search |
+| **Calendar** | 20+ | Events, todos (tasks), recurring events, attendees, availability |
+| **Contacts** | 8 | Full CardDAV support, address books |
+| **Files (WebDAV)** | 12 | Filesystem access, OCR/document processing |
+| **Deck** | 15 | Boards, stacks, cards, labels, assignments |
+| **Cookbook** | 13 | Recipe management, URL import (schema.org) |
+| **Tables** | 5 | Row operations on Nextcloud Tables |
+| **Sharing** | 10+ | Create and manage shares |
+| **Semantic Search** | 2+ | Vector search for Notes (experimental, opt-in, requires infrastructure) |
 
-Or connect from:
-- Claude Desktop
-- Any MCP-compatible client
+Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request!
+
+## Authentication
+
+> [!IMPORTANT]
+> **OAuth2/OIDC is experimental** and requires a manual patch to the `user_oidc` app:
+> - **Required patch**: Bearer token support ([issue #1221](https://github.com/nextcloud/user_oidc/issues/1221))
+> - **Impact**: Without the patch, most app-specific APIs fail with 401 errors
+> - **Recommendation**: Use Basic Auth for production until upstream patches are merged
+>
+> See [docs/oauth-upstream-status.md](docs/oauth-upstream-status.md) for patch status and workarounds.
+
+**Recommended:** Basic Auth with app-specific passwords provides secure, production-ready authentication. See [docs/authentication.md](docs/authentication.md) for setup details and OAuth configuration.
+
+### Authentication Modes
+
+The server supports two authentication modes:
+
+**Single-User Mode (BasicAuth):**
+- One set of credentials shared by all MCP clients
+- Simple setup: username + app password in environment variables
+- All clients access Nextcloud as the same user
+- Best for: Personal use, development, single-user deployments
+
+**Multi-User Mode (OAuth):**
+- Each MCP client authenticates separately with their own Nextcloud account
+- Per-user scopes and permissions (clients only see tools they're authorized for)
+- More secure: tokens expire, credentials never shared with server
+- Best for: Teams, multi-user deployments, production environments with multiple users
+
+See [docs/authentication.md](docs/authentication.md) for detailed setup instructions.
+
+## Semantic Search
+
+The server provides an experimental RAG pipeline to enable _Semantic Search_ that enables MCP clients to find information in Nextcloud based on **meaning** rather than just keywords. Instead of matching "machine learning" only when those exact words appear, it understands that "neural networks," "AI models," and "deep learning" are semantically related concepts.
+
+**Example:**
+- **Keyword search**: Query "car" only finds notes containing "car"
+- **Semantic search**: Query "car" also finds notes about "automobile," "vehicle," "sedan," "transportation"
+
+This enables natural language queries and helps discover related content across your Nextcloud notes.
+
+> [!NOTE]
+> **Semantic Search is experimental and opt-in:**
+> - Disabled by default (`VECTOR_SYNC_ENABLED=false`)
+> - Currently supports Notes app only (multi-app support planned)
+> - Requires additional infrastructure: vector database + embedding service
+> - Answer generation (`nc_semantic_search_answer`) requires MCP client sampling support
+>
+> See [docs/semantic-search-architecture.md](docs/semantic-search-architecture.md) for architecture details and [docs/configuration.md](docs/configuration.md) for setup instructions.
 
 ## Documentation
 
 ### 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
+- **[Installation](docs/installation.md)** - Docker, Kubernetes, local, or VM deployment
+- **[Configuration](docs/configuration.md)** - Environment variables and advanced options
+- **[Authentication](docs/authentication.md)** - Basic Auth vs OAuth2/OIDC setup
+- **[Running the Server](docs/running.md)** - Start, manage, and troubleshoot
 
-### Architecture
-- **[Comparison with Context Agent](docs/comparison-context-agent.md)** - How this MCP server differs from Nextcloud's Context Agent
+### Features
+- **[App Documentation](docs/)** - Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables
+- **[Document Processing](docs/configuration.md#document-processing)** - OCR and text extraction setup
+- **[Semantic Search Architecture](docs/semantic-search-architecture.md)** - Experimental vector search (Notes only, opt-in)
 
-### 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** ⚠️
-
-### Reference
+### Advanced Topics
+- **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works (experimental)
+- **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute OAuth setup
+- **[OAuth Setup Guide](docs/oauth-setup.md)** - Detailed OAuth configuration
 - **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
-
-### 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)
-
-## MCP Tools & Resources
-
-The server exposes Nextcloud functionality through MCP tools (for actions) and resources (for data browsing).
-
-### 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...
-
-### 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...
-
-Run `uv run nextcloud-mcp-server --help` to see all available options.
+- **[Comparison with Context Agent](docs/comparison-context-agent.md)** - When to use each approach
 
 ## Examples
 
@@ -194,45 +139,31 @@ AI: "Create a note called 'Meeting Notes' with today's agenda"
 → Uses nc_notes_create_note tool
 ```
 
-### Manage Recipes
+### Import 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
+AI: "Import the recipe from https://www.example.com/recipe/chocolate-cake"
+→ Uses nc_cookbook_import_recipe tool with schema.org metadata extraction
 ```
 
-### Manage Calendar
+### Schedule Meetings
 ```
 AI: "Schedule a team meeting for next Tuesday at 2pm"
 → Uses nc_calendar_create_event tool
 ```
 
-### Organize Files
+### Manage Files
 ```
 AI: "Create a folder called 'Project X' and move all PDFs there"
-→ Uses WebDAV tools (nc_webdav_create_directory, nc_webdav_move)
+→ Uses nc_webdav_create_directory and nc_webdav_move tools
 ```
 
-### Project Management
+### Semantic Search (Experimental, Opt-in)
 ```
-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
+AI: "Find notes related to machine learning concepts"
+→ Uses nc_semantic_search to find semantically similar notes (requires Qdrant + Ollama setup)
 ```
 
-## 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
-
-```bash
-# Use streamable-http (recommended)
-uv run nextcloud-mcp-server --transport streamable-http
-```
-
-> [!WARNING]
-> SSE transport is deprecated and will be removed in a future MCP specification version. Please migrate to `streamable-http`.
+**Note:** For AI-generated answers with citations, use `nc_semantic_search_answer` (requires MCP client with sampling support).
 
 ## Contributing
 
@@ -240,17 +171,17 @@ Contributions are welcome!
 
 - 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
+- Development guidelines: [CLAUDE.md](CLAUDE.md)
 
 ## Security
 
 [![MseeP.ai Security Assessment](https://mseep.net/pr/cbcoutinho-nextcloud-mcp-server-badge.png)](https://mseep.ai/app/cbcoutinho-nextcloud-mcp-server)
 
 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
+- Production-ready Basic Auth with app-specific passwords
+- OAuth2/OIDC support (experimental, requires upstream patches)
 - Per-user access tokens
+- No credential storage in OAuth mode
 - Regular security assessments
 
 Found a security issue? Please report it privately to the maintainers.

app-hooks/patches/cors-bearer-token.patch

@@ -0,0 +1,18 @@
+diff --git a/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php b/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php
+index 4453f5a7d4b..f1ca9b48d21 100644
+--- a/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php
++++ b/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php
+@@ -73,6 +73,13 @@ class CORSMiddleware extends Middleware {
+ 			$user = array_key_exists('PHP_AUTH_USER', $this->request->server) ? $this->request->server['PHP_AUTH_USER'] : null;
+ 			$pass = array_key_exists('PHP_AUTH_PW', $this->request->server) ? $this->request->server['PHP_AUTH_PW'] : null;
+ 
++			// Allow Bearer token authentication for CORS requests
++			// Bearer tokens are stateless and don't require CSRF protection
++			$authorizationHeader = $this->request->getHeader('Authorization');
++			if (!empty($authorizationHeader) && str_starts_with($authorizationHeader, 'Bearer ')) {
++				return;
++			}
++
+ 			// Allow to use the current session if a CSRF token is provided
+ 			if ($this->request->passesCSRFCheck()) {
+ 				return;

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/0001-feat-Advertise-PKCE-support-in-discovery-document.patch

@@ -1,63 +0,0 @@
-From 9036daecdc8bcdf8114715dcf17e5c06967b25fb Mon Sep 17 00:00:00 2001
-From: Chris Coutinho <chris@coutinho.io>
-Date: Mon, 13 Oct 2025 23:24:53 +0200
-Subject: [PATCH 1/2] feat: Advertise PKCE support in discovery document
-
-Add code_challenge_methods_supported to OpenID Connect discovery
-document when PKCE is enabled via proof_key_for_code_exchange config.
-
-Rationale:
-According to RFC 8414 Section 2, the code_challenge_methods_supported
-field in OAuth 2.0 Authorization Server Metadata has specific semantics:
-"If omitted, the authorization server does not support PKCE."
-
-This means that clients following RFC 8414 strictly will interpret the
-absence of this field as explicit non-support for PKCE, even if the
-authorization server technically supports it.
-
-Impact:
-- Standards-compliant OAuth clients (e.g., MCP clients) require explicit
-  advertisement of PKCE support before proceeding with authorization
-- The MCP (Model Context Protocol) specification mandates that clients
-  MUST refuse to proceed if code_challenge_methods_supported is absent
-- Other security-focused OAuth implementations may have similar checks
-
-Implementation:
-- Only advertises S256 (SHA-256) challenge method, which is the most
-  secure and widely supported method
-- Conditional on the existing proof_key_for_code_exchange app config
-- Maintains backward compatibility: only added when PKCE is enabled
-
-This change ensures the discovery document accurately reflects server
-capabilities per RFC 8414 semantics, enabling compatibility with
-strict standards-compliant OAuth clients.
-
-References:
-- RFC 8414: OAuth 2.0 Authorization Server Metadata
-- RFC 7636: Proof Key for Code Exchange by OAuth Public Clients
-- MCP Authorization Specification
-
-Signed-off-by: Chris Coutinho <chris@coutinho.io>
----
- lib/Util/DiscoveryGenerator.php | 5 +++++
- 1 file changed, 5 insertions(+)
-
-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);
--- 
-2.51.1
-

app-hooks/post-installation/0002-Initial-implementation-of-PKCE.patch

@@ -1,320 +0,0 @@
-From cb2c931fe1f73e5bbfdf459928b5b21e2d96e0f1 Mon Sep 17 00:00:00 2001
-From: Chris Coutinho <chris@coutinho.io>
-Date: Sun, 19 Oct 2025 21:04:46 +0200
-Subject: [PATCH 2/2] Initial implementation of PKCE
-
-Signed-off-by: Chris Coutinho <chris@coutinho.io>
----
- lib/Controller/LoginRedirectorController.php  | 44 +++++++++++-
- lib/Controller/OIDCApiController.php          | 68 ++++++++++++++++++-
- lib/Db/AccessToken.php                        | 10 +++
- .../Version0014Date20251019100100.php         | 63 +++++++++++++++++
- lib/Util/DiscoveryGenerator.php               |  2 +-
- 5 files changed, 184 insertions(+), 3 deletions(-)
- create mode 100644 lib/Migration/Version0014Date20251019100100.php
-
-diff --git a/lib/Controller/LoginRedirectorController.php b/lib/Controller/LoginRedirectorController.php
-index 1b9bdde..5f2d327 100644
---- a/lib/Controller/LoginRedirectorController.php
-+++ b/lib/Controller/LoginRedirectorController.php
-@@ -142,6 +142,8 @@ class LoginRedirectorController extends ApiController
-      * @param string $scope
-      * @param string $nonce
-      * @param string $resource
-+     * @param string $code_challenge
-+     * @param string $code_challenge_method
-      * @return Response
-      */
-     #[BruteForceProtection(action: 'oidc_login')]
-@@ -155,7 +157,9 @@ class LoginRedirectorController extends ApiController
-                     $redirect_uri,
-                     $scope,
-                     $nonce,
--                    $resource
-+                    $resource,
-+                    $code_challenge = null,
-+                    $code_challenge_method = null
-                     ): Response
-         {
-         if (!$this->userSession->isLoggedIn()) {
-@@ -168,6 +172,8 @@ class LoginRedirectorController extends ApiController
-             $this->session->set('oidc_scope', $scope);
-             $this->session->set('oidc_nonce', $nonce);
-             $this->session->set('oidc_resource', $resource);
-+            $this->session->set('oidc_code_challenge', $code_challenge);
-+            $this->session->set('oidc_code_challenge_method', $code_challenge_method);
- 
-             $afterLoginRedirectUrl = $this->urlGenerator->linkToRoute('oidc.Page.index', []);
- 
-@@ -204,6 +210,12 @@ class LoginRedirectorController extends ApiController
-         if (empty($resource)) {
-             $resource = $this->session->get('oidc_resource');
-         }
-+        if (empty($code_challenge)) {
-+            $code_challenge = $this->session->get('oidc_code_challenge');
-+        }
-+        if (empty($code_challenge_method)) {
-+            $code_challenge_method = $this->session->get('oidc_code_challenge_method');
-+        }
- 
-         // Set default scope if scope is not set at all
-         if (!isset($scope)) {
-@@ -327,6 +339,30 @@ class LoginRedirectorController extends ApiController
- 
-         $uid = $this->userSession->getUser()->getUID();
- 
-+        // PKCE validation (RFC 7636)
-+        if (!empty($code_challenge)) {
-+            // Validate code_challenge format: 43-128 characters, unreserved chars only
-+            if (!preg_match('/^[A-Za-z0-9._~-]{43,128}$/', $code_challenge)) {
-+                $this->logger->notice('Invalid code_challenge format for client ' . $client_id . '.');
-+                $url = $redirect_uri . '?error=invalid_request&error_description=Invalid%20code_challenge%20format&state=' . urlencode($state);
-+                return new RedirectResponse($url);
-+            }
-+
-+            // Default to S256 if method not specified
-+            if (empty($code_challenge_method)) {
-+                $code_challenge_method = 'S256';
-+            }
-+
-+            // Validate code_challenge_method: only S256 and plain are allowed
-+            if (!in_array($code_challenge_method, ['S256', 'plain'])) {
-+                $this->logger->notice('Unsupported code_challenge_method for client ' . $client_id . ': ' . $code_challenge_method);
-+                $url = $redirect_uri . '?error=invalid_request&error_description=Unsupported%20code_challenge_method&state=' . urlencode($state);
-+                return new RedirectResponse($url);
-+            }
-+
-+            $this->logger->debug('PKCE challenge received for client ' . $client_id . ' using method ' . $code_challenge_method);
-+        }
-+
-         $code = $this->random->generate(128, ISecureRandom::CHAR_UPPER.ISecureRandom::CHAR_LOWER.ISecureRandom::CHAR_DIGITS);
-         $accessToken = new AccessToken();
-         $accessToken->setClientId($client->getId());
-@@ -343,6 +379,12 @@ class LoginRedirectorController extends ApiController
-         }
-         $accessToken->setNonce($nonce);
- 
-+        // Store PKCE challenge if provided
-+        if (!empty($code_challenge)) {
-+            $accessToken->setCodeChallenge(substr($code_challenge, 0, 128));
-+            $accessToken->setCodeChallengeMethod(substr($code_challenge_method, 0, 16));
-+        }
-+
-         try {
-             $accessToken->setAccessToken($this->jwtGenerator->generateAccessToken($accessToken, $client, $this->request->getServerProtocol(), $this->request->getServerHost()));
-             $this->accessTokenMapper->insert($accessToken);
-diff --git a/lib/Controller/OIDCApiController.php b/lib/Controller/OIDCApiController.php
-index 6fd6eb0..059396c 100644
---- a/lib/Controller/OIDCApiController.php
-+++ b/lib/Controller/OIDCApiController.php
-@@ -125,12 +125,13 @@ class OIDCApiController extends ApiController {
-      * @param string $refresh_token
-      * @param string $client_id
-      * @param string $client_secret
-+     * @param string $code_verifier
-      * @return JSONResponse
-      */
-     #[BruteForceProtection(action: 'oidc_token')]
-     #[PublicPage]
-     #[NoCSRFRequired]
--    public function getToken($grant_type, $code, $refresh_token, $client_id, $client_secret): JSONResponse
-+    public function getToken($grant_type, $code, $refresh_token, $client_id, $client_secret, $code_verifier = null): JSONResponse
-     {
-         $expireTime = (int)$this->appConfig->getAppValueString(Application::APP_CONFIG_DEFAULT_EXPIRE_TIME, '0');
-         $refreshExpireTime = (int)$this->appConfig->getAppValueString(Application::APP_CONFIG_DEFAULT_REFRESH_EXPIRE_TIME, Application::DEFAULT_REFRESH_EXPIRE_TIME);
-@@ -212,6 +213,32 @@ class OIDCApiController extends ApiController {
-                     'error_description' => 'Access token already expired.',
-                 ], Http::STATUS_BAD_REQUEST);
-             }
-+
-+            // PKCE verification (RFC 7636 Section 4.6)
-+            $storedCodeChallenge = $accessToken->getCodeChallenge();
-+            if (!empty($storedCodeChallenge)) {
-+                // PKCE was used in authorization request, code_verifier is required
-+                if (empty($code_verifier)) {
-+                    $this->accessTokenMapper->delete($accessToken);
-+                    $this->logger->notice('Missing code_verifier for PKCE-protected token. Client id: ' . $client_id);
-+                    return new JSONResponse([
-+                        'error' => 'invalid_grant',
-+                        'error_description' => 'code_verifier required for PKCE flow.',
-+                    ], Http::STATUS_BAD_REQUEST);
-+                }
-+
-+                $storedCodeChallengeMethod = $accessToken->getCodeChallengeMethod() ?: 'S256';
-+                if (!$this->verifyPkce($code_verifier, $storedCodeChallenge, $storedCodeChallengeMethod)) {
-+                    $this->accessTokenMapper->delete($accessToken);
-+                    $this->logger->notice('PKCE verification failed. Client id: ' . $client_id);
-+                    return new JSONResponse([
-+                        'error' => 'invalid_grant',
-+                        'error_description' => 'Invalid code_verifier.',
-+                    ], Http::STATUS_BAD_REQUEST);
-+                }
-+
-+                $this->logger->debug('PKCE verification successful for client ' . $client_id);
-+            }
-         } elseif ($refreshExpireTime !== 'never') {
-             // The refresh token must not be expired
-             $refreshExpireTime = (int)$refreshExpireTime;
-@@ -286,4 +313,43 @@ class OIDCApiController extends ApiController {
- 
-         return $response;
-     }
-+
-+    /**
-+     * Base64URL encode (RFC 7636 Section 4.2)
-+     *
-+     * @param string $data
-+     * @return string
-+     */
-+    private function base64UrlEncode(string $data): string
-+    {
-+        return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
-+    }
-+
-+    /**
-+     * Verify PKCE code_verifier against code_challenge (RFC 7636 Section 4.6)
-+     *
-+     * @param string $codeVerifier
-+     * @param string $codeChallenge
-+     * @param string $codeChallengeMethod
-+     * @return bool
-+     */
-+    private function verifyPkce(string $codeVerifier, string $codeChallenge, string $codeChallengeMethod): bool
-+    {
-+        // Validate code_verifier format: 43-128 characters, unreserved chars only
-+        if (!preg_match('/^[A-Za-z0-9._~-]{43,128}$/', $codeVerifier)) {
-+            return false;
-+        }
-+
-+        // Compute the challenge based on the method
-+        if ($codeChallengeMethod === 'S256') {
-+            $computedChallenge = $this->base64UrlEncode(hash('sha256', $codeVerifier, true));
-+        } elseif ($codeChallengeMethod === 'plain') {
-+            $computedChallenge = $codeVerifier;
-+        } else {
-+            return false;
-+        }
-+
-+        // Constant-time comparison to prevent timing attacks
-+        return hash_equals($codeChallenge, $computedChallenge);
-+    }
- }
-diff --git a/lib/Db/AccessToken.php b/lib/Db/AccessToken.php
-index a0419c0..593c5c8 100644
---- a/lib/Db/AccessToken.php
-+++ b/lib/Db/AccessToken.php
-@@ -27,6 +27,10 @@ use OCP\AppFramework\Db\Entity;
-  * @method void setNonce(string $nonce)
-  * @method string getResource()
-  * @method void setResource(string $resource)
-+ * @method string getCodeChallenge()
-+ * @method void setCodeChallenge(string $codeChallenge)
-+ * @method string getCodeChallengeMethod()
-+ * @method void setCodeChallengeMethod(string $codeChallengeMethod)
-  */
- class AccessToken extends Entity
- {
-@@ -50,6 +54,10 @@ class AccessToken extends Entity
-     protected $nonce;
-     /** @var string */
-     protected $resource;
-+    /** @var string */
-+    protected $codeChallenge;
-+    /** @var string */
-+    protected $codeChallengeMethod;
- 
-     public function __construct() {
-         $this->addType('id', 'int');
-@@ -62,5 +70,7 @@ class AccessToken extends Entity
-         $this->addType('refreshed', 'int');
-         $this->addType('nonce', 'string');
-         $this->addType('resource', 'string');
-+        $this->addType('codeChallenge', 'string');
-+        $this->addType('codeChallengeMethod', 'string');
-     }
- }
-diff --git a/lib/Migration/Version0014Date20251019100100.php b/lib/Migration/Version0014Date20251019100100.php
-new file mode 100644
-index 0000000..bf705b3
---- /dev/null
-+++ b/lib/Migration/Version0014Date20251019100100.php
-@@ -0,0 +1,63 @@
-+<?php
-+
-+declare(strict_types=1);
-+
-+/**
-+ * SPDX-FileCopyrightText: 2022-2025 Thorsten Jagel <dev@jagel.net>
-+ * SPDX-License-Identifier: AGPL-3.0-or-later
-+ */
-+namespace OCA\OIDCIdentityProvider\Migration;
-+
-+use Closure;
-+use OCP\DB\ISchemaWrapper;
-+use OCP\Migration\IOutput;
-+use OCP\Migration\SimpleMigrationStep;
-+use Psr\Log\LoggerInterface;
-+use OCP\IDBConnection;
-+use OCP\DB\Types;
-+
-+class Version0014Date20251019100100 extends SimpleMigrationStep {
-+    private LoggerInterface $logger;
-+    private IDBConnection $db;
-+
-+    public function __construct(
-+                    IDBConnection $db,
-+                    LoggerInterface $logger
-+                    )
-+    {
-+        $this->db = $db;
-+        $this->logger = $logger;
-+    }
-+
-+    /**
-+     * @param IOutput $output
-+     * @param Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`
-+     * @param array $options
-+     * @return null|ISchemaWrapper
-+     */
-+    public function changeSchema(IOutput $output, Closure $schemaClosure, array $options) {
-+        /** @var ISchemaWrapper $schema */
-+        $schema = $schemaClosure();
-+
-+        $table = $schema->getTable('oidc_access_tokens');
-+
-+        if(!$table->hasColumn('code_challenge')) {
-+            $table->addColumn('code_challenge', Types::STRING, [
-+                'notnull' => false,
-+                'default' => null,
-+                'length' => 128,
-+            ]);
-+        }
-+
-+        if(!$table->hasColumn('code_challenge_method')) {
-+            $table->addColumn('code_challenge_method', Types::STRING, [
-+                'notnull' => false,
-+                'default' => null,
-+                'length' => 16,
-+            ]);
-+        }
-+
-+        return $schema;
-+    }
-+
-+}
-diff --git a/lib/Util/DiscoveryGenerator.php b/lib/Util/DiscoveryGenerator.php
-index 6429f94..d96a18c 100644
---- a/lib/Util/DiscoveryGenerator.php
-+++ b/lib/Util/DiscoveryGenerator.php
-@@ -173,7 +173,7 @@ class DiscoveryGenerator
- 
-         // Add PKCE support if enabled
-         if ($this->appConfig->getAppValueBool('proof_key_for_code_exchange', false)) {
--            $discoveryPayload['code_challenge_methods_supported'] = ['S256'];
-+            $discoveryPayload['code_challenge_methods_supported'] = ['S256', 'plain'];
-         }
- 
-         $this->logger->info('Request to Discovery Endpoint.');
--- 
-2.51.1
-

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

@@ -6,7 +6,7 @@ echo "Installing and configuring Calendar app..."
 
 # Enable calendar app
 php /var/www/html/occ app:enable calendar
-php /var/www/html/occ app:enable --force tasks # Not currently supported on 32
+php /var/www/html/occ app:enable tasks
 
 # Wait for calendar app to be fully initialized
 echo "Waiting for calendar app to initialize..."

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

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

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

@@ -0,0 +1,40 @@
+#!/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' # NOTE: String
+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 allow_user_settings --value='enabled'
+php /var/www/html/occ config:app:set oidc default_token_type --value='jwt'
+php /var/www/html/occ config:app:set oidc default_resource_identifier --value='http://localhost:8080'
+
+echo "OIDC app installed and configured successfully"

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

@@ -0,0 +1,21 @@
+#!/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
+php /var/www/html/occ config:system:set user_oidc httpclient.allowselfsigned --value=true --type=boolean
+
+# Allow Nextcloud to connect to local/internal servers (required for external IdP mode)
+# This enables user_oidc to fetch JWKS from internal Keycloak container
+php /var/www/html/occ config:system:set allow_local_remote_servers --value=true --type=boolean
+
+# Note: The user_oidc app_api session flag patch is NOT required when using the
+# CORSMiddleware Bearer token patch (20-apply-cors-bearer-token-patch.sh).
+# The CORSMiddleware patch fixes the root cause by allowing Bearer tokens to bypass
+# CORS/CSRF checks at the framework level.

app-hooks/post-installation/15-setup-keycloak-provider.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+#
+# Configure user_oidc to accept bearer tokens from Keycloak
+#
+# This script sets up Keycloak as an external OIDC provider for Nextcloud.
+# It enables bearer token validation, allowing the MCP server to use Keycloak
+# tokens to access Nextcloud APIs without admin credentials.
+#
+
+set -e
+
+echo "===================================================================="
+echo "Configuring user_oidc provider for Keycloak..."
+echo "===================================================================="
+
+# Wait for Keycloak to be ready and realm to be available
+echo "Waiting for Keycloak realm to be available..."
+MAX_RETRIES=30
+RETRY_COUNT=0
+
+while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
+    if curl -sf http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration > /dev/null 2>&1; then
+        echo "✓ Keycloak realm is ready"
+        break
+    fi
+    echo "  Waiting for Keycloak... (attempt $((RETRY_COUNT + 1))/$MAX_RETRIES)"
+    sleep 5
+    RETRY_COUNT=$((RETRY_COUNT + 1))
+done
+
+if [ $RETRY_COUNT -eq $MAX_RETRIES ]; then
+    echo "⚠ Warning: Keycloak not available after $MAX_RETRIES attempts"
+    echo "  Keycloak provider will not be configured"
+    echo "  You can configure it manually using:"
+    echo "  docker compose exec app php occ user_oidc:provider keycloak \\"
+    echo "    --clientid='nextcloud' \\"
+    echo "    --clientsecret='nextcloud-secret-change-in-production' \\"
+    echo "    --discoveryuri='http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration' \\"
+    echo "    --check-bearer=1 \\"
+    echo "    --bearer-provisioning=1 \\"
+    echo "    --unique-uid=1"
+    exit 0
+fi
+
+# Check if provider already exists
+if php /var/www/html/occ user_oidc:provider keycloak 2>/dev/null | grep -q "Identifier"; then
+    echo "  Keycloak provider already exists, updating configuration..."
+
+    # Update existing provider
+    php /var/www/html/occ user_oidc:provider keycloak \
+        --clientid="nextcloud" \
+        --clientsecret="nextcloud-secret-change-in-production" \
+        --discoveryuri="http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration" \
+        --check-bearer=1 \
+        --bearer-provisioning=1 \
+        --unique-uid=1 \
+        --mapping-uid="sub" \
+        --mapping-display-name="name" \
+        --mapping-email="email" \
+        --scope="openid profile email offline_access"
+
+    echo "✓ Updated Keycloak provider configuration"
+else
+    echo "  Creating new Keycloak provider..."
+
+    # Create new provider
+    php /var/www/html/occ user_oidc:provider keycloak \
+        --clientid="nextcloud" \
+        --clientsecret="nextcloud-secret-change-in-production" \
+        --discoveryuri="http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration" \
+        --check-bearer=1 \
+        --bearer-provisioning=1 \
+        --unique-uid=1 \
+        --mapping-uid="sub" \
+        --mapping-display-name="name" \
+        --mapping-email="email" \
+        --scope="openid profile email offline_access"
+
+    echo "✓ Created Keycloak provider"
+fi
+
+# Display provider details
+echo ""
+echo "Keycloak provider configuration:"
+php /var/www/html/occ user_oidc:provider keycloak
+
+echo ""
+echo "===================================================================="
+echo "✓ Keycloak provider configured successfully"
+echo "===================================================================="
+echo ""
+echo "Key features enabled:"
+echo "  • Bearer token validation (--check-bearer=1)"
+echo "  • Automatic user provisioning (--bearer-provisioning=1)"
+echo "  • Unique user IDs (--unique-uid=1)"
+echo "  • Offline access scope (for refresh tokens)"
+echo ""
+echo "MCP server can now use Keycloak tokens to access Nextcloud APIs"
+echo "without admin credentials (ADR-002 architecture)."
+echo ""

app-hooks/post-installation/20-apply-cors-bearer-token-patch.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+#
+# Apply upstream CORSMiddleware Bearer token authentication patch
+#
+# This patch allows Bearer tokens to bypass CORS/CSRF checks, fixing
+# authentication issues with app-specific APIs (Notes, Calendar, etc.)
+# when using OAuth/OIDC Bearer tokens.
+#
+# Upstream PR: https://github.com/nextcloud/server/pull/55878
+# Commit: 8fb5e77db82 (fix(cors): Allow Bearer token authentication)
+#
+
+set -e
+
+PATCH_FILE="/docker-entrypoint-hooks.d/patches/cors-bearer-token.patch"
+TARGET_FILE="/var/www/html/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php"
+
+echo "===================================================================="
+echo "Applying CORSMiddleware Bearer token authentication patch..."
+echo "===================================================================="
+
+# Check if patch file exists
+if [ ! -f "$PATCH_FILE" ]; then
+    echo "⚠ Warning: Patch file not found: $PATCH_FILE"
+    echo "  Skipping CORS Bearer token patch"
+    exit 0
+fi
+
+# Check if target file exists
+if [ ! -f "$TARGET_FILE" ]; then
+    echo "⚠ Warning: Target file not found: $TARGET_FILE"
+    echo "  Skipping CORS Bearer token patch"
+    exit 0
+fi
+
+# Check if already patched
+if grep -q "Allow Bearer token authentication for CORS requests" "$TARGET_FILE"; then
+    echo "✓ CORSMiddleware already patched for Bearer token support"
+    exit 0
+fi
+
+echo "Applying patch to CORSMiddleware.php..."
+
+# Apply the patch
+cd /var/www/html
+if patch -p1 --dry-run < "$PATCH_FILE" > /dev/null 2>&1; then
+    patch -p1 < "$PATCH_FILE"
+    echo "✓ Patch applied successfully"
+else
+    echo "⚠ Warning: Patch failed to apply (may already be applied or file changed)"
+    echo "  This is expected if using a Nextcloud version that already includes the fix"
+    exit 0
+fi
+
+echo ""
+echo "===================================================================="
+echo "✓ CORSMiddleware Bearer token patch applied"
+echo "===================================================================="
+echo ""
+echo "Benefits:"
+echo "  • Bearer tokens now work with app-specific APIs (Notes, Calendar, etc.)"
+echo "  • OAuth/OIDC authentication works without CORS errors"
+echo "  • Stateless API authentication is properly supported"
+echo ""

app-hooks/post-installation/30-disable-welcome-wizard.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+php /var/www/html/occ config:app:set --value false firstrunwizard wizard_enabled

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

@@ -1,5 +0,0 @@
-#!/bin/bash
-
-set -euox pipefail
-
-php /var/www/html/occ app:enable notes

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

@@ -1,24 +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 -d /var/www/html/custom_apps/oidc -p1 < /docker-entrypoint-hooks.d/post-installation/0001-feat-Advertise-PKCE-support-in-discovery-document.patch
-patch -d /var/www/html/custom_apps/oidc -p1 < /docker-entrypoint-hooks.d/post-installation/0002-Initial-implementation-of-PKCE.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/.gitignore

@@ -0,0 +1 @@
+charts/

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.lock

@@ -0,0 +1,9 @@
+dependencies:
+- name: qdrant
+  repository: https://qdrant.github.io/qdrant-helm
+  version: 1.15.5
+- name: ollama
+  repository: https://otwld.github.io/ollama-helm
+  version: 1.34.0
+digest: sha256:d51c97d05be2614b751c0dd7267ef7dc959eff5ebef859c5f895c5c554b7a874
+generated: "2025-11-09T17:08:02.86648061Z"

charts/nextcloud-mcp-server/Chart.yaml

@@ -0,0 +1,36 @@
+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.36.0
+appVersion: "0.36.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
+annotations:
+  # Grafana dashboard support
+  grafana_dashboard: "true"
+  grafana_dashboard_folder: "Nextcloud MCP"
+dependencies:
+  - name: qdrant
+    version: "1.15.5"
+    repository: https://qdrant.github.io/qdrant-helm
+    condition: qdrant.networkMode.deploySubchart
+  - name: ollama
+    version: "1.34.0"
+    repository: https://otwld.github.io/ollama-helm
+    condition: ollama.enabled

charts/nextcloud-mcp-server/README.md

@@ -0,0 +1,721 @@
+# 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 issuer URL for OAuth (OAuth only, optional) | Smart default** |
+
+**Smart Defaults:**
+- `*mcpServerUrl`: If not set, automatically uses ingress host (if enabled) or `http://localhost:8000` (for port-forward setups)
+- `**publicIssuerUrl`: If not set, automatically defaults to `nextcloud.host` (which works when both clients and MCP server access Nextcloud at the same URL)
+
+#### Authentication
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `auth.mode` | Authentication mode: `basic` or `oauth` | `basic` |
+| `auth.basic.username` | Nextcloud username (basic auth) | `""` |
+| `auth.basic.password` | Nextcloud password (basic auth) | `""` |
+| `auth.basic.existingSecret` | Use existing secret for credentials | `""` |
+| `auth.oauth.clientId` | OAuth client ID (OAuth mode, optional) | `""` |
+| `auth.oauth.clientSecret` | OAuth client secret (OAuth mode, optional) | `""` |
+| `auth.oauth.persistence.enabled` | Enable persistent storage for OAuth | `true` |
+| `auth.oauth.persistence.size` | Size of OAuth storage PVC | `100Mi` |
+
+#### 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 by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
+
+**Vector Sync Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `vectorSync.enabled` | Enable background vector synchronization | `false` |
+| `vectorSync.scanInterval` | Scan interval in seconds | `3600` |
+| `vectorSync.processorWorkers` | Number of concurrent processor workers | `3` |
+| `vectorSync.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
+
+auth:
+  mode: oauth
+  oauth:
+    existingSecret: nextcloud-oauth-creds
+    clientIdKey: clientId
+    clientSecretKey: clientSecret
+    persistence:
+      enabled: true
+
+ingress:
+  enabled: true
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: mcp-tls
+      hosts:
+        - mcp.example.com
+```
+
+### Example 3: OAuth with Document Processing and Dynamic Client Registration
+
+This example shows OAuth without pre-registered credentials (using DCR) and optional URL values:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+  # mcpServerUrl will automatically use ingress host (https://mcp.example.com)
+  # publicIssuerUrl will automatically default to nextcloud.host
+
+auth:
+  mode: oauth
+  oauth:
+    # No clientId/clientSecret - will use Dynamic Client Registration!
+    persistence:
+      enabled: true
+      storageClass: fast-ssd
+      size: 200Mi
+
+documentProcessing:
+  enabled: true
+  defaultProcessor: unstructured
+  unstructured:
+    enabled: true
+    apiUrl: http://unstructured-api:8000
+    strategy: hi_res
+    languages: eng,deu,fra
+
+ingress:
+  enabled: true
+  className: nginx
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+```
+
+### Example 4: High Availability with Autoscaling
+
+```yaml
+replicaCount: 2
+
+autoscaling:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 20
+  targetCPUUtilizationPercentage: 70
+  targetMemoryUtilizationPercentage: 80
+
+resources:
+  limits:
+    cpu: 2000m
+    memory: 1Gi
+  requests:
+    cpu: 500m
+    memory: 512Mi
+
+affinity:
+  podAntiAffinity:
+    preferredDuringSchedulingIgnoredDuringExecution:
+      - weight: 100
+        podAffinityTerm:
+          labelSelector:
+            matchExpressions:
+              - key: app.kubernetes.io/name
+                operator: In
+                values:
+                  - nextcloud-mcp-server
+          topologyKey: kubernetes.io/hostname
+```
+
+### 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 vector sync
+vectorSync:
+  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
+vectorSync:
+  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
+vectorSync:
+  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
+   - Check network policies and firewall rules
+
+2. **Authentication failures**
+   - For basic auth: verify username/password are correct
+   - For OAuth: check that OIDC app is properly configured
+
+3. **OAuth persistence issues**
+   - Verify PVC is bound: `kubectl get pvc`
+   - Check storage class exists: `kubectl get storageclass`
+
+4. **Resource constraints**
+   - Increase memory limits if seeing OOM errors
+   - Adjust CPU requests based on load
+
+## Security Considerations
+
+1. **Secrets Management**: Consider using external secret management (e.g., Sealed Secrets, External Secrets Operator)
+2. **TLS**: Always use TLS/HTTPS for production deployments
+3. **Network Policies**: Restrict network access to necessary services only
+4. **RBAC**: Review and customize ServiceAccount permissions as needed
+5. **App Passwords**: For basic auth, use Nextcloud app passwords instead of main account passwords
+
+## Support
+
+- GitHub Issues: https://github.com/cbcoutinho/nextcloud-mcp-server/issues
+- Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme
+
+## License
+
+This chart is licensed under AGPL-3.0, consistent with the Nextcloud MCP Server project.

charts/nextcloud-mcp-server/dashboards/README.md

@@ -0,0 +1,161 @@
+# Grafana Dashboards
+
+This directory contains example Grafana dashboards for monitoring the Nextcloud MCP Server.
+
+## Dashboards
+
+### nextcloud-mcp-server.json
+
+All-in-one Operations Dashboard with comprehensive monitoring across all system components.
+
+#### Overview Row
+High-level metrics for quick health assessment:
+- **Request Rate** (stat): Total requests per second
+- **Error Rate** (stat): Percentage of 5xx errors with color thresholds
+- **P95 Latency** (stat): 95th percentile request latency
+- **Active Requests** (stat): Current in-flight requests
+
+#### HTTP Metrics (RED Pattern)
+Core request/error/duration metrics:
+- **Request Rate by Endpoint** (timeseries): RPS breakdown by endpoint
+- **Error Rate by Status Code** (timeseries): Error rates for 4xx/5xx codes
+- **Latency Percentiles** (timeseries): P50, P95, P99 latency trends
+- **Status Code Distribution** (piechart): Percentage breakdown of all status codes
+
+#### MCP Tools Row
+MCP-specific tool performance:
+- **Top Tools by Call Volume** (bargauge): Top 10 most-called tools
+- **Tool Error Rate** (timeseries): Error rates per tool
+- **Tool Execution Duration** (timeseries): P95 latency by tool
+
+#### Nextcloud API Row
+Backend API performance metrics:
+- **API Calls by App** (timeseries): Request rate per Nextcloud app (notes, calendar, contacts, etc.)
+- **API Latency by App** (timeseries): P95 latency per app
+- **API Retries by Reason** (timeseries): Retry patterns (429, timeout, connection errors)
+- **API Error Rate** (stat): Overall API error percentage
+
+#### OAuth & Authentication Row
+OAuth token operations and caching:
+- **Token Validations** (timeseries): Success/failure rates for token validation
+- **Token Exchange Operations** (timeseries): RFC 8693 token exchange operations
+- **Token Cache Hit Rate** (stat): Percentage of cache hits (color-coded: red<50%, yellow<80%, green≥80%)
+- **Refresh Token Operations** (timeseries): Refresh token storage operations by type
+
+#### Dependencies & Health Row
+External dependency status monitoring:
+- **Nextcloud Health** (stat): UP/DOWN status with color coding
+- **Qdrant Health** (stat): Vector database health status
+- **Keycloak Health** (stat): Identity provider health status
+- **Unstructured API Health** (stat): Document processing API status
+- **Health Check Duration** (timeseries): Health check latency by dependency
+- **Database Operation Latency** (timeseries): P95 latency for DB operations (SQLite, Qdrant)
+
+#### Vector Sync Row (when enabled)
+Document processing pipeline metrics:
+- **Documents Processed Rate** (timeseries): Processing throughput by status (success/failure)
+- **Processing Queue Depth** (gauge): Current queue size with thresholds (yellow>50, red>100)
+- **Qdrant Operations** (timeseries): Vector database operations by type
+- **Document Processing Duration** (timeseries): P95 processing latency
+
+## Importing to Grafana
+
+### Manual Import
+
+1. Open Grafana UI
+2. Navigate to Dashboards → Import
+3. Upload `nextcloud-mcp-server.json`
+4. Select your Prometheus data source
+5. Click "Import"
+
+### Automated Import (Helm Chart)
+
+The Helm chart now supports automatic dashboard provisioning via Grafana sidecar pattern.
+
+#### Option 1: Using Helm Chart (Recommended)
+
+Enable dashboard provisioning in your Helm values:
+
+```yaml
+# values.yaml for nextcloud-mcp-server chart
+dashboards:
+  enabled: true
+  grafanaFolder: "Nextcloud MCP"  # Folder name in Grafana
+  labels: {}  # Additional labels if needed
+```
+
+Then deploy or upgrade:
+
+```bash
+helm upgrade --install nextcloud-mcp nextcloud-mcp-server \
+  --set dashboards.enabled=true
+```
+
+The dashboard will be automatically imported by Grafana if the sidecar is configured
+to watch for ConfigMaps with label `grafana_dashboard: "1"`.
+
+#### Option 2: Using kube-prometheus-stack
+
+If using kube-prometheus-stack with Grafana sidecar enabled, the dashboard will be
+automatically discovered and imported. Ensure your Grafana deployment has:
+
+```yaml
+# kube-prometheus-stack values
+grafana:
+  sidecar:
+    dashboards:
+      enabled: true
+      label: grafana_dashboard
+      folder: /tmp/dashboards
+      provider:
+        foldersFromFilesStructure: true
+```
+
+#### Option 3: Manual ConfigMap Creation
+
+For other Grafana setups, create a ConfigMap manually:
+
+```bash
+kubectl create configmap nextcloud-mcp-dashboard \
+  --from-file=nextcloud-mcp-server.json \
+  -n monitoring
+
+# Add sidecar discovery label
+kubectl label configmap nextcloud-mcp-dashboard \
+  grafana_dashboard=1 \
+  -n monitoring
+
+# Add folder annotation (annotations support spaces, unlike labels)
+kubectl annotate configmap nextcloud-mcp-dashboard \
+  grafana_folder="Nextcloud MCP" \
+  -n monitoring
+```
+
+## Dashboard Variables
+
+The dashboard includes four template variables for dynamic filtering:
+
+- **datasource**: Select your Prometheus data source
+- **namespace**: Filter metrics by Kubernetes namespace (supports "All")
+- **pod**: Filter by specific pod(s) - multi-select enabled (supports "All")
+- **interval**: Query interval for rate calculations (1m, 5m, 10m, 30m, 1h - default: 5m)
+
+## Customization
+
+You can customize the dashboard by:
+
+1. Adjusting refresh rate (default: 30s)
+2. Modifying time range (default: last 6 hours)
+3. Adding new panels for specific metrics
+4. Adjusting thresholds in existing panels
+
+## Metrics Reference
+
+All metrics are documented in `/docs/observability.md`. Key metric prefixes:
+
+- `mcp_http_*` - HTTP server metrics
+- `mcp_tool_*` - MCP tool invocation metrics
+- `mcp_nextcloud_api_*` - Nextcloud API call metrics
+- `mcp_oauth_*` - OAuth token validation metrics
+- `mcp_vector_sync_*` - Vector database sync metrics
+- `mcp_db_*` - Database operation metrics

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

@@ -0,0 +1,131 @@
+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 }}
+
+{{- if .Values.vectorSync.enabled }}
+
+5. Vector Search & Semantic Capabilities:
+   - Vector Sync: Enabled
+   - Scan Interval: {{ .Values.vectorSync.scanInterval }}s
+   - Processor Workers: {{ .Values.vectorSync.processorWorkers }}
+   {{- if .Values.qdrant.enabled }}
+   - Qdrant: Deployed as subchart ({{ .Release.Name }}-qdrant:6333)
+   {{- else }}
+   - Qdrant: Not deployed (configure external instance)
+   {{- end }}
+   {{- if .Values.ollama.enabled }}
+   - Ollama: Deployed as subchart ({{ .Release.Name }}-ollama:11434)
+   - Embedding Model: {{ .Values.ollama.embeddingModel }}
+   {{- else if .Values.ollama.url }}
+   - Ollama: Using external instance at {{ .Values.ollama.url }}
+   - Embedding Model: {{ .Values.ollama.embeddingModel }}
+   {{- else if .Values.openai.enabled }}
+   - OpenAI: Enabled for embeddings
+   {{- else }}
+   - WARNING: No embedding provider configured (Ollama or OpenAI required)
+   {{- end }}
+
+   Check vector sync status:
+   kubectl --namespace {{ .Release.Namespace }} exec -it deploy/{{ include "nextcloud-mcp-server.fullname" . }} -- curl -s http://localhost:{{ include "nextcloud-mcp-server.port" . }}/user/page | grep "Vector Sync"
+{{- end }}
+
+{{- if .Values.dashboards.enabled }}
+
+6. Grafana Dashboards:
+   - Dashboard provisioning: Enabled
+   - ConfigMap: {{ include "nextcloud-mcp-server.fullname" . }}-dashboard
+   - Grafana Folder: {{ .Values.dashboards.grafanaFolder }}
+
+   The dashboard will be automatically imported by Grafana if the sidecar is configured
+   to watch for ConfigMaps with label "grafana_dashboard: 1".
+
+   To manually import the dashboard:
+   kubectl --namespace {{ .Release.Namespace }} get configmap {{ include "nextcloud-mcp-server.fullname" . }}-dashboard -o jsonpath='{.data.nextcloud-mcp-server\.json}' | jq . > dashboard.json
+
+   Then import dashboard.json via Grafana UI (Dashboards → Import).
+{{- else }}
+
+6. Grafana Dashboards:
+   - Dashboard provisioning: Disabled
+   - To enable automatic dashboard provisioning, set: dashboards.enabled=true
+
+   Manual import option:
+   The dashboard JSON is available in the chart at charts/nextcloud-mcp-server/dashboards/nextcloud-mcp-server.json
+{{- 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,153 @@
+{{/*
+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 }}
+
+{{/*
+Create the name of the PVC to use for Qdrant local persistent storage
+*/}}
+{{- define "nextcloud-mcp-server.qdrantPvcName" -}}
+{{- if .Values.qdrant.localPersistence.existingClaim }}
+{{- .Values.qdrant.localPersistence.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-qdrant-data
+{{- end }}
+{{- end }}
+
+{{/*
+Return the MCP server port
+*/}}
+{{- define "nextcloud-mcp-server.port" -}}
+{{- .Values.mcp.port }}
+{{- end }}
+
+{{/*
+Return the image tag (always uses chart appVersion)
+*/}}
+{{- define "nextcloud-mcp-server.imageTag" -}}
+{{- .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/dashboard-configmap.yaml

@@ -0,0 +1,25 @@
+{{- if .Values.dashboards.enabled }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-dashboard
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+    {{- with .Values.dashboards.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+    # Grafana sidecar discovery label
+    grafana_dashboard: "1"
+  annotations:
+    {{- with .Values.dashboards.annotations }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+    # Grafana folder name (annotations support spaces, unlike labels)
+    {{- if .Values.dashboards.grafanaFolder }}
+    grafana_folder: {{ .Values.dashboards.grafanaFolder | quote }}
+    {{- end }}
+data:
+  nextcloud-mcp-server.json: |-
+{{ .Files.Get "dashboards/nextcloud-mcp-server.json" | indent 4 }}
+{{- end }}

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

@@ -0,0 +1,288 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  strategy:
+    type: Recreate
+  {{- 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"
+            - "--oauth-token-type"
+            - "{{ .Values.auth.oauth.tokenType }}"
+            {{- end }}
+            {{- with .Values.mcp.extraArgs }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+          ports:
+            - name: http
+              containerPort: {{ include "nextcloud-mcp-server.port" . }}
+              protocol: TCP
+            {{- if .Values.observability.metrics.enabled }}
+            - name: metrics
+              containerPort: {{ .Values.observability.metrics.port }}
+              protocol: TCP
+            {{- end }}
+          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_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 }}
+            # Vector Sync
+            - name: VECTOR_SYNC_ENABLED
+              value: {{ .Values.vectorSync.enabled | quote }}
+            {{- if .Values.vectorSync.enabled }}
+            - name: VECTOR_SYNC_SCAN_INTERVAL
+              value: {{ .Values.vectorSync.scanInterval | quote }}
+            - name: VECTOR_SYNC_PROCESSOR_WORKERS
+              value: {{ .Values.vectorSync.processorWorkers | quote }}
+            - name: VECTOR_SYNC_QUEUE_MAX_SIZE
+              value: {{ .Values.vectorSync.queueMaxSize | quote }}
+            {{- end }}
+            # Document Chunking (always set, used by vector sync processor)
+            - name: DOCUMENT_CHUNK_SIZE
+              value: {{ .Values.documentChunking.chunkSize | quote }}
+            - name: DOCUMENT_CHUNK_OVERLAP
+              value: {{ .Values.documentChunking.chunkOverlap | quote }}
+            # Qdrant Vector Database
+            {{- if eq .Values.qdrant.mode "network" }}
+            # Network mode: Use dedicated Qdrant service
+            {{- if .Values.qdrant.networkMode.deploySubchart }}
+            - name: QDRANT_URL
+              value: "http://{{ .Release.Name }}-qdrant:6333"
+            {{- else if .Values.qdrant.networkMode.externalUrl }}
+            - name: QDRANT_URL
+              value: {{ .Values.qdrant.networkMode.externalUrl | quote }}
+            {{- end }}
+            {{- if or .Values.qdrant.networkMode.apiKey .Values.qdrant.networkMode.existingSecret }}
+            - name: QDRANT_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.qdrant.networkMode.existingSecret | default (printf "%s-qdrant" .Release.Name) }}
+                  key: {{ .Values.qdrant.networkMode.secretKey }}
+            {{- end }}
+            {{- else if eq .Values.qdrant.mode "persistent" }}
+            # Persistent local mode: File-based storage
+            - name: QDRANT_LOCATION
+              value: {{ .Values.qdrant.localPersistence.dataPath | quote }}
+            {{- else }}
+            # In-memory mode (default): Ephemeral storage
+            - name: QDRANT_LOCATION
+              value: ":memory:"
+            {{- end }}
+            - name: QDRANT_COLLECTION
+              value: {{ .Values.qdrant.collection | quote }}
+            # Ollama Embedding Service
+            {{- if or .Values.ollama.enabled .Values.ollama.url }}
+            - name: OLLAMA_BASE_URL
+              value: {{ .Values.ollama.url | default (printf "http://%s-ollama:11434" .Release.Name) | quote }}
+            - name: OLLAMA_EMBEDDING_MODEL
+              value: {{ .Values.ollama.embeddingModel | quote }}
+            - name: OLLAMA_VERIFY_SSL
+              value: {{ .Values.ollama.verifySsl | quote }}
+            {{- end }}
+            # OpenAI Embedding Provider (alternative to Ollama)
+            {{- if .Values.openai.enabled }}
+            - name: OPENAI_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.openai.existingSecret | default (printf "%s-openai" (include "nextcloud-mcp-server.fullname" .)) }}
+                  key: {{ .Values.openai.secretKey }}
+            {{- if .Values.openai.baseUrl }}
+            - name: OPENAI_BASE_URL
+              value: {{ .Values.openai.baseUrl | quote }}
+            {{- end }}
+            {{- end }}
+            # Observability
+            - name: METRICS_ENABLED
+              value: {{ .Values.observability.metrics.enabled | quote }}
+            - name: METRICS_PORT
+              value: {{ .Values.observability.metrics.port | quote }}
+            {{- if .Values.observability.tracing.enabled }}
+            - name: OTEL_EXPORTER_OTLP_ENDPOINT
+              value: {{ .Values.observability.tracing.endpoint | quote }}
+            - name: OTEL_SERVICE_NAME
+              value: {{ .Values.observability.tracing.serviceName | quote }}
+            - name: OTEL_TRACES_SAMPLER_ARG
+              value: {{ .Values.observability.tracing.samplingRate | quote }}
+            {{- end }}
+            - name: LOG_FORMAT
+              value: {{ .Values.observability.logging.format | quote }}
+            - name: LOG_LEVEL
+              value: {{ .Values.observability.logging.level | quote }}
+            - name: LOG_INCLUDE_TRACE_CONTEXT
+              value: {{ .Values.observability.logging.includeTraceContext | quote }}
+            {{- 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 }}
+            {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
+            - name: qdrant-data
+              mountPath: /app/data
+            {{- 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 }}
+        {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
+        - name: qdrant-data
+          persistentVolumeClaim:
+            claimName: {{ include "nextcloud-mcp-server.qdrantPvcName" . }}
+        {{- 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/openai-secret.yaml

@@ -0,0 +1,11 @@
+{{- if and .Values.openai.enabled (not .Values.openai.existingSecret) }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-openai
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.openai.secretKey }}: {{ .Values.openai.apiKey | b64enc | quote }}
+{{- end }}

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

@@ -0,0 +1,92 @@
+{{- if and .Values.observability.metrics.enabled .Values.prometheusRule.enabled }}
+apiVersion: monitoring.coreos.com/v1
+kind: PrometheusRule
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+    {{- with .Values.prometheusRule.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  groups:
+    - name: nextcloud-mcp-server.critical
+      interval: 30s
+      rules:
+        - alert: NextcloudMCPServerDown
+          expr: up{job="{{ include "nextcloud-mcp-server.fullname" . }}"} == 0
+          for: 5m
+          labels:
+            severity: critical
+          annotations:
+            summary: "Nextcloud MCP Server is down"
+            description: "{{ `{{` }} $labels.pod {{ `}}` }} has been down for more than 5 minutes."
+
+        - alert: NextcloudMCPHighErrorRate
+          expr: |
+            sum(rate(mcp_http_requests_total{status_code=~"5..", job="{{ include "nextcloud-mcp-server.fullname" . }}"}[5m]))
+            / sum(rate(mcp_http_requests_total{job="{{ include "nextcloud-mcp-server.fullname" . }}"}[5m])) > 0.05
+          for: 5m
+          labels:
+            severity: critical
+          annotations:
+            summary: "High error rate on Nextcloud MCP Server"
+            description: "Error rate is {{ `{{` }} printf \"%.2f%%\" (mul $value 100) {{ `}}` }} (threshold: 5%)"
+
+        - alert: NextcloudMCPHighLatency
+          expr: |
+            histogram_quantile(0.95,
+              sum(rate(mcp_http_request_duration_seconds_bucket{job="{{ include "nextcloud-mcp-server.fullname" . }}"}[5m])) by (le, endpoint)
+            ) > 1
+          for: 5m
+          labels:
+            severity: critical
+          annotations:
+            summary: "High latency on Nextcloud MCP Server"
+            description: "P95 latency is {{ `{{` }} printf \"%.2fs\" $value {{ `}}` }} on {{ `{{` }} $labels.endpoint {{ `}}` }} (threshold: 1s)"
+
+        - alert: NextcloudMCPDependencyDown
+          expr: mcp_dependency_health{job="{{ include "nextcloud-mcp-server.fullname" . }}"} == 0
+          for: 2m
+          labels:
+            severity: critical
+          annotations:
+            summary: "Nextcloud MCP dependency is down"
+            description: "Dependency {{ `{{` }} $labels.dependency {{ `}}` }} has been down for more than 2 minutes."
+
+    - name: nextcloud-mcp-server.warning
+      interval: 30s
+      rules:
+        - alert: NextcloudMCPTokenValidationErrors
+          expr: |
+            sum(rate(mcp_oauth_token_validations_total{result="error", job="{{ include "nextcloud-mcp-server.fullname" . }}"}[10m]))
+            / sum(rate(mcp_oauth_token_validations_total{job="{{ include "nextcloud-mcp-server.fullname" . }}"}[10m])) > 0.01
+          for: 10m
+          labels:
+            severity: warning
+          annotations:
+            summary: "High token validation error rate"
+            description: "Token validation error rate is {{ `{{` }} printf \"%.2f%%\" (mul $value 100) {{ `}}` }} (threshold: 1%)"
+
+        - alert: NextcloudMCPVectorSyncQueueHigh
+          expr: mcp_vector_sync_queue_size{job="{{ include "nextcloud-mcp-server.fullname" . }}"} > 100
+          for: 15m
+          labels:
+            severity: warning
+          annotations:
+            summary: "Vector sync queue is high"
+            description: "Vector sync queue size is {{ `{{` }} $value {{ `}}` }} (threshold: 100)"
+
+        - alert: NextcloudMCPQdrantSlowQueries
+          expr: |
+            histogram_quantile(0.95,
+              sum(rate(mcp_db_operation_duration_seconds_bucket{db="qdrant", job="{{ include "nextcloud-mcp-server.fullname" . }}"}[10m])) by (le)
+            ) > 0.5
+          for: 10m
+          labels:
+            severity: warning
+          annotations:
+            summary: "Qdrant queries are slow"
+            description: "P95 Qdrant query latency is {{ `{{` }} printf \"%.2fs\" $value {{ `}}` }} (threshold: 0.5s)"
+{{- end }}

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

@@ -0,0 +1,35 @@
+{{- 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 }}
+---
+{{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled (not .Values.qdrant.localPersistence.existingClaim) }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-qdrant-data
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - {{ .Values.qdrant.localPersistence.accessMode }}
+  {{- if .Values.qdrant.localPersistence.storageClass }}
+  storageClassName: {{ .Values.qdrant.localPersistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.qdrant.localPersistence.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,25 @@
+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
+    {{- if .Values.observability.metrics.enabled }}
+    - port: {{ .Values.observability.metrics.port }}
+      targetPort: metrics
+      protocol: TCP
+      name: metrics
+    {{- end }}
+  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/templates/servicemonitor.yaml

@@ -0,0 +1,32 @@
+{{- if and .Values.observability.metrics.enabled .Values.serviceMonitor.enabled }}
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+    {{- with .Values.serviceMonitor.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  selector:
+    matchLabels:
+      {{- include "nextcloud-mcp-server.selectorLabels" . | nindent 6 }}
+  endpoints:
+    - port: metrics
+      path: {{ .Values.observability.metrics.path }}
+      interval: {{ .Values.serviceMonitor.interval }}
+      scrapeTimeout: {{ .Values.serviceMonitor.scrapeTimeout }}
+      scheme: http
+      relabelings:
+        # Add namespace label
+        - sourceLabels: [__meta_kubernetes_namespace]
+          targetLabel: namespace
+        # Add pod label
+        - sourceLabels: [__meta_kubernetes_pod_name]
+          targetLabel: pod
+        # Add service label
+        - sourceLabels: [__meta_kubernetes_service_name]
+          targetLabel: service
+{{- end }}

charts/nextcloud-mcp-server/values.yaml

@@ -0,0 +1,465 @@
+# 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
+  # Image tag is automatically set to chart appVersion
+
+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:
+    # 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 MCP server (both basic auth and OAuth modes)
+  port: 8000
+  # Additional command-line arguments to pass to nextcloud-mcp-server
+  # Example: ["--log-level", "debug", "--enable-app", "notes"]
+  extraArgs: []
+
+# 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
+
+# Observability Configuration
+observability:
+  # Prometheus metrics
+  metrics:
+    enabled: true
+    port: 9090
+    path: /metrics
+
+  # OpenTelemetry tracing
+  tracing:
+    enabled: false
+    endpoint: ""  # e.g., "http://opentelemetry-collector:4317"
+    serviceName: "nextcloud-mcp-server"
+    samplingRate: 1.0
+
+  # Logging configuration
+  logging:
+    format: json  # "json" or "text"
+    level: INFO
+    includeTraceContext: true
+
+# Prometheus ServiceMonitor (requires Prometheus Operator)
+serviceMonitor:
+  enabled: false
+  interval: 30s
+  scrapeTimeout: 10s
+  labels: {}
+  # Additional labels for ServiceMonitor (e.g., for Prometheus selector)
+  # Example: { prometheus: kube-prometheus }
+
+# Prometheus alert rules (requires Prometheus Operator)
+prometheusRule:
+  enabled: false
+  labels: {}
+  # Additional labels for PrometheusRule (e.g., for Prometheus selector)
+  # Example: { prometheus: kube-prometheus }
+
+# Grafana dashboards (requires Grafana with sidecar enabled)
+dashboards:
+  # Enable automatic dashboard provisioning via ConfigMap
+  enabled: false
+  # Grafana folder name where dashboards will be imported
+  # The grafana-sidecar looks for ConfigMaps with label "grafana_dashboard: 1"
+  # and reads the folder name from annotation "grafana_folder" (supports spaces)
+  grafanaFolder: "Nextcloud MCP"
+  # Additional labels for dashboard ConfigMap
+  # These will be added alongside the required "grafana_dashboard: 1" label
+  labels: {}
+  # Additional annotations for dashboard ConfigMap
+  annotations: {}
+
+service:
+  type: ClusterIP
+  port: 8000
+  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
+
+# Vector Sync Configuration
+# Background synchronization of Nextcloud content into vector database for semantic search
+vectorSync:
+  # Enable background vector synchronization
+  enabled: false
+  # Scan interval in seconds (how often to check for changes)
+  scanInterval: 3600
+  # Number of concurrent processor workers
+  processorWorkers: 3
+  # Maximum queue size for documents pending indexing
+  queueMaxSize: 10000
+
+# Document Chunking Configuration
+# Controls how documents are split into chunks before embedding
+# Only relevant when vectorSync.enabled is true
+documentChunking:
+  # Number of words per chunk (default: 512)
+  # Smaller chunks (256-384): Better for precise searches, more chunks to store
+  # Medium chunks (512-768): Balanced approach (recommended for most use cases)
+  # Larger chunks (1024+): Better for context, less precise matching
+  chunkSize: 512
+  # Number of overlapping words between chunks (default: 50)
+  # Recommended: 10-20% of chunkSize for context preservation across boundaries
+  # Must be less than chunkSize
+  chunkOverlap: 50
+
+# Qdrant Vector Database Configuration
+# Three deployment modes available:
+# 1. Local In-Memory: Fast, ephemeral, zero-config (mode: "memory")
+# 2. Local Persistent: File-based, survives restarts (mode: "persistent")
+# 3. Network: Dedicated Qdrant service, production-ready (mode: "network")
+qdrant:
+  # Qdrant mode: "memory", "persistent", or "network"
+  # - memory: In-memory storage (:memory:) - default, zero config, data lost on restart
+  # - persistent: Local file storage - data persists across restarts, suitable for small/medium deployments
+  # - network: Dedicated Qdrant service (see networkMode below)
+  mode: "memory"
+
+  # Collection name for vector data
+  collection: "nextcloud_content"
+
+  # Local persistent mode configuration (only used when mode: "persistent")
+  localPersistence:
+    # Enable persistent volume for local Qdrant data
+    enabled: true
+    # Storage class (leave empty for default)
+    storageClass: ""
+    accessMode: ReadWriteOnce
+    # Size for local Qdrant storage
+    size: 1Gi
+    # Path where Qdrant data is stored (relative to /app/data)
+    # Default: /app/data/qdrant
+    dataPath: "/app/data/qdrant"
+    # Use existing PVC
+    existingClaim: ""
+
+  # Network mode configuration (only used when mode: "network")
+  networkMode:
+    # Deploy Qdrant as a subchart (if true) or use external Qdrant (if false)
+    deploySubchart: false
+    # External Qdrant URL (used when deploySubchart: false)
+    # Example: "http://qdrant.default.svc.cluster.local:6333"
+    externalUrl: ""
+    # Optional API key for Qdrant authentication
+    apiKey: ""
+    # Use existing secret for API key
+    existingSecret: ""
+    secretKey: "api-key"
+
+  # Qdrant subchart configuration (only used when mode: "network" and networkMode.deploySubchart: true)
+  # All values are passed through to the qdrant/qdrant chart.
+  # See https://github.com/qdrant/qdrant-helm for full configuration options.
+  subchart:
+    # Number of Qdrant replicas
+    replicaCount: 1
+    image:
+      # Qdrant version
+      tag: v1.12.5
+    config:
+      cluster:
+        # Enable distributed cluster mode
+        enabled: false
+    # Persistent storage for vector data
+    persistence:
+      size: 10Gi
+      storageClass: ""
+      accessModes:
+        - ReadWriteOnce
+    # Resource limits and requests
+    resources:
+      requests:
+        cpu: 200m
+        memory: 512Mi
+      limits:
+        cpu: 1000m
+        memory: 2Gi
+
+# Ollama Embedding Service
+# Deployed as a subchart when enabled. All values are passed through to the ollama/ollama chart.
+# See https://github.com/otwld/ollama-helm for full configuration options.
+ollama:
+  # Enable Ollama subchart deployment
+  # Set to true to deploy Ollama as a subchart, or false to use an external Ollama instance
+  enabled: false
+  # External Ollama URL (use this if you have Ollama deployed elsewhere)
+  # When set, use enabled: false to prevent deploying the subchart
+  # Example: "http://ollama.default.svc.cluster.local:11434"
+  url: ""
+  # Embedding model to use
+  embeddingModel: "nomic-embed-text"
+  # Verify SSL certificates when connecting to Ollama
+  verifySsl: true
+  # Number of Ollama replicas (only used when subchart is deployed)
+  replicaCount: 1
+  # Ollama configuration (only used when subchart is deployed)
+  ollama:
+    # Models to automatically pull on startup
+    models:
+      pull:
+        - nomic-embed-text
+  # Persistent storage for models (only used when subchart is deployed)
+  persistentVolume:
+    enabled: true
+    size: 20Gi
+    storageClass: ""
+  # Resource limits and requests (only used when subchart is deployed)
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+    limits:
+      cpu: 2000m
+      memory: 4Gi
+
+# OpenAI-compatible Embedding Provider
+# Alternative to Ollama for embedding generation. Can be used with OpenAI or any compatible API.
+openai:
+  # Enable OpenAI embedding provider
+  enabled: false
+  # OpenAI API key (only used if existingSecret is not set)
+  apiKey: ""
+  # Name of existing secret containing the API key
+  existingSecret: ""
+  # Key in the secret that contains the API key
+  secretKey: "api-key"
+  # Optional custom API endpoint (e.g., for Azure OpenAI or local compatible services)
+  baseUrl: ""

docker-compose.yml

@@ -3,7 +3,7 @@ services:
   # https://hub.docker.com/_/mariadb
   db:
     # Note: Check the recommend version here: https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html#server
-    image: docker.io/library/mariadb:lts@sha256:ae6119716edac6998ae85508431b3d2e666530ddf4e94c61a10710caec9b0f71
+    image: docker.io/library/mariadb:lts@sha256:6b848cb24fbbd87429917f6c4422ac53c343e85692eb0fef86553e99e4f422f3
     restart: always
     command: --transaction-isolation=READ-COMMITTED
     volumes:
@@ -17,20 +17,24 @@ services:
   # Note: Redis is an external service. You can find more information about the configuration here:
   # https://hub.docker.com/_/redis
   redis:
-    image: docker.io/library/redis:alpine@sha256:59b6e694653476de2c992937ebe1c64182af4728e54bb49e9b7a6c26614d8933
+    image: docker.io/library/redis:alpine@sha256:28c9c4d7596949a24b183eaaab6455f8e5d55ecbf72d02ff5e2c17fe72671d31
     restart: always
 
   app:
-    image: docker.io/library/nextcloud:32.0.0@sha256:3e70e4dfe882ef44738fdc30d9896fb07c12febb27c4a1177e3d63dc0004a0b4
+    image: docker.io/library/nextcloud:32.0.1@sha256:5b043f7ea2f609d5ff5635f475c30d303bec17775a5c3f7fa435e3818e669120
     restart: always
     ports:
       - 0.0.0.0:8080:80
     depends_on:
       - redis
       - db
+      - keycloak
     volumes:
       - nextcloud:/var/www/html
-      - ./app-hooks/post-installation:/docker-entrypoint-hooks.d/post-installation:ro
+      - ./app-hooks:/docker-entrypoint-hooks.d: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:/opt/apps:ro
     environment:
       - NEXTCLOUD_TRUSTED_DOMAINS=app
       - NEXTCLOUD_ADMIN_USER=admin
@@ -40,44 +44,220 @@ services:
       - MYSQL_USER=nextcloud
       - MYSQL_HOST=db
       - REDIS_HOST=redis
+    healthcheck:
+      test: ["CMD-SHELL", "curl -Ss http://localhost/status.php | grep '\"installed\":true' || exit 1"]
+      interval: 10s
+      timeout: 30s
+      retries: 30
 
   recipes:
-    image: docker.io/library/nginx:alpine@sha256:61e01287e546aac28a3f56839c136b31f590273f3b41187a36f46f6a03bbfe22
+    image: docker.io/library/nginx:alpine@sha256:b3c656d55d7ad751196f21b7fd2e8d4da9cb430e32f646adcf92441b72f82b14
     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:54282d3a25f33fd6cf69bc45b3d37770f213593f58b6dfe5e85fe546376b2807
+    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"]
     restart: always
     depends_on:
-      - app
+      app:
+        condition: service_healthy
     ports:
       - 127.0.0.1:8000:8000
+    volumes:
+      - mcp-data:/app/data
     environment:
       - NEXTCLOUD_HOST=http://app:80
       - NEXTCLOUD_USERNAME=admin
       - NEXTCLOUD_PASSWORD=admin
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+
+      # Vector sync configuration (ADR-007)
+      - VECTOR_SYNC_ENABLED=true
+      - VECTOR_SYNC_SCAN_INTERVAL=10
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+
+      #- LOG_FORMAT=json
+
+      # Qdrant configuration (three modes):
+      # 1. Network mode: Set QDRANT_URL=http://qdrant:6333 (requires qdrant service)
+      # 2. In-memory mode: Set QDRANT_LOCATION=:memory: (default if nothing set)
+      # 3. Persistent local: Set QDRANT_LOCATION=/app/data/qdrant (stored in mcp-data volume)
+      #- QDRANT_LOCATION=/app/data/qdrant  # In-memory mode used if not set
+      #- QDRANT_URL=http://qdrant:6333  # Uncomment for network mode
+      #- QDRANT_API_KEY=${QDRANT_API_KEY:-my_secret_api_key}  # Only for network mode
+
+      # Observability
+      #- OTEL_SERVICE_NAME=nextcloud-mcp-docker-compose
+      #- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+
+      # Collection naming: Auto-generated as {deployment-id}-{model-name}
+      # - Deployment ID: OTEL_SERVICE_NAME (if set) or hostname (fallback)
+      # - Model name: OLLAMA_EMBEDDING_MODEL
+      # - Example: "nextcloud-mcp-server-nomic-embed-text"
+      # - Changing models creates new collection (requires re-embedding)
+      # - Set QDRANT_COLLECTION to override auto-generation:
+      #- QDRANT_COLLECTION=nextcloud_content
+
+      # Ollama configuration (optional - uses SimpleEmbeddingProvider if not set)
+      # - OLLAMA_BASE_URL=http://ollama:11434
+      # - OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Changing this creates new collection
+      # - OLLAMA_VERIFY_SSL=false
+
+      # Document chunking configuration (for vector embeddings)
+      # Tune these based on your embedding model and content type
+      # - DOCUMENT_CHUNK_SIZE=512      # Words per chunk (default: 512)
+      # - DOCUMENT_CHUNK_OVERLAP=50    # Overlapping words (default: 50, recommended: 10-20% of chunk size)
 
   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
+      app:
+        condition: service_healthy
     ports:
       - 127.0.0.1:8001:8001
     environment:
+      # Generic OIDC configuration (integrated mode - Nextcloud OIDC app)
+      # OIDC_DISCOVERY_URL not set - defaults to NEXTCLOUD_HOST/.well-known/openid-configuration
+      # OIDC_CLIENT_ID not set - uses Dynamic Client Registration (DCR)
       - 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_RESOURCE_URI=http://localhost:8080  # ADR-005: Nextcloud resource identifier for audience validation
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+      - 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
+
+      # Refresh token storage (ADR-002 Tier 1)
+      - ENABLE_OFFLINE_ACCESS=true
+      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      # ADR-005: Multi-audience mode (default - ENABLE_TOKEN_EXCHANGE=false)
+      # Tokens must contain BOTH MCP and Nextcloud audiences
+      # No token exchange needed - tokens work for both MCP auth and Nextcloud APIs
+
+      # NO admin credentials - using OAuth with Dynamic Client Registration (DCR)
+      # Client credentials registered via RFC 7591 and stored in volume
+      # JWT token type is used for testing (faster validation, scopes embedded in token)
     volumes:
       - oauth-client-storage:/app/.oauth
+      - oauth-tokens:/app/data
+
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.4.5@sha256:653852bfdea2be6e958b9e90a976eff1c6de34edd55f2f679bdc48ef16bc528e
+    command:
+      - "start-dev"
+      - "--import-realm"
+      - "--hostname=http://localhost:8888"
+      - "--hostname-strict=false"
+      - "--hostname-backchannel-dynamic=true"
+      - "--features=preview"  # Enable Legacy V1 token exchange (supports both Standard V2 and Legacy V1)
+    ports:
+      - 127.0.0.1:8888:8080
+    environment:
+      - KC_BOOTSTRAP_ADMIN_USERNAME=admin
+      - KC_BOOTSTRAP_ADMIN_PASSWORD=admin
+    volumes:
+      - ./keycloak/realm-export.json:/opt/keycloak/data/import/realm.json:ro
+    healthcheck:
+      test: ["CMD-SHELL", "exec 3<>/dev/tcp/localhost/8080 && echo -e 'GET /realms/nextcloud-mcp HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q 'HTTP/1.1 200'"]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+
+  mcp-keycloak:
+    build: .
+    command: ["--transport", "streamable-http", "--oauth", "--port", "8002"]
+    restart: always
+    depends_on:
+      keycloak:
+        condition: service_healthy
+      app:
+        condition: service_started
+    ports:
+      - 127.0.0.1:8002:8002
+    environment:
+      # Generic OIDC configuration (external IdP mode - Keycloak)
+      # Provider auto-detected from OIDC_DISCOVERY_URL issuer
+      # Using internal Docker hostname for discovery to get consistent issuer
+      - OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+      - OIDC_CLIENT_ID=nextcloud-mcp-server
+      - OIDC_CLIENT_SECRET=mcp-secret-change-in-production
+      - OIDC_JWKS_URI=http://keycloak:8080/realms/nextcloud-mcp/protocol/openid-connect/certs
+
+      # Nextcloud API endpoint (for accessing APIs with validated token)
+      - NEXTCLOUD_HOST=http://app:80
+      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002
+      - NEXTCLOUD_RESOURCE_URI=nextcloud  # ADR-005: Keycloak uses client IDs as audiences, not URLs
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888/realms/nextcloud-mcp
+
+      # Refresh token storage (ADR-002 Tier 1 & 2)
+      - ENABLE_OFFLINE_ACCESS=true
+      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      # ADR-005: Token exchange mode (RFC 8693)
+      # Exchange MCP tokens (aud: nextcloud-mcp-server) for Nextcloud tokens (aud: http://localhost:8080)
+      # Provides strict audience separation between MCP session and Nextcloud API access
+      - ENABLE_TOKEN_EXCHANGE=true
+      - TOKEN_EXCHANGE_CACHE_TTL=300  # Cache exchanged tokens for 5 minutes (default)
+
+      # OAuth scopes (optional - uses defaults if not specified)
+      - NEXTCLOUD_OIDC_SCOPES=openid profile email offline_access 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 admin credentials - using external IdP OAuth only!
+    volumes:
+      - keycloak-tokens:/app/data
+      - keycloak-oauth-storage:/app/.oauth
+
+  qdrant:
+    image: qdrant/qdrant:v1.15.5@sha256:0fb8897412abc81d1c0430a899b9a81eb8328aa634e7242d1bc804c1fe8fe863
+    restart: always
+    ports:
+      - 127.0.0.1:6333:6333  # REST API
+      - 127.0.0.1:6334:6334  # gRPC (optional)
+    volumes:
+      - qdrant-data:/qdrant/storage
+    environment:
+      - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY:-my_secret_api_key}
+    healthcheck:
+      test: ["CMD-SHELL", "test -f /qdrant/.qdrant-initialized"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    profiles:
+      - qdrant
+
+  open-webui:
+    image: ghcr.io/open-webui/open-webui:main
+    environment:
+      - OLLAMA_BASE_URL=https://ollama.internal.coutinho.io
+    ports:
+      - 127.0.0.1:3000:8080
+    volumes:
+      - open-webui:/app/backend/data
+    profiles:
+      - open-webui
 
 volumes:
   nextcloud:
   db:
   oauth-client-storage:
+  oauth-tokens:
+  keycloak-tokens:
+  keycloak-oauth-storage:
+  qdrant-data:
+  mcp-data:
+  open-webui:

docs/ADR-002-vector-sync-authentication.md

@@ -0,0 +1,964 @@
+# ADR-002: Vector Database Background Sync Authentication
+
+> **⚠️ DEPRECATED**: This ADR has been superseded by [ADR-004: MCP Server as OAuth Client for Offline Access](./ADR-004-mcp-application-oauth.md).
+>
+> **Reason for Deprecation**: This ADR fundamentally misunderstood the MCP protocol's authentication architecture. The MCP server receives tokens from clients but cannot initiate OAuth flows or store refresh tokens, making the proposed solutions ineffective for true offline access. ADR-004 provides the correct architectural pattern where the MCP server acts as its own OAuth client.
+
+## Status
+~~Accepted - Tier 2 (Token Exchange with Delegation) Implemented~~
+**Superseded by ADR-004** - The token exchange implementation exists but doesn't solve the offline access problem.
+
+**Important**: Service account tokens (old Tier 1) have been rejected as they violate OAuth "act on-behalf-of" principles by creating Nextcloud user accounts for the MCP server.
+
+## Context
+
+To enable semantic search capabilities, the MCP server needs to index user content (notes, files, calendar events) into a vector database. This requires a background sync worker that:
+
+1. **Runs independently** of user requests (periodic or continuous operation)
+2. **Accesses multiple users' content** to build a comprehensive search index
+3. **Respects user permissions** - only index content users have access to
+4. **Operates in OAuth mode** - where the MCP server doesn't have traditional admin credentials
+
+### Current OAuth Architecture
+
+The MCP server currently operates in two authentication modes:
+
+1. **BasicAuth Mode**: Uses username/password credentials (typically admin account)
+2. **OAuth Mode**: Single OAuth client, multiple user tokens
+   - Users authenticate via OAuth flow
+   - Each request includes user's access token
+   - Server creates per-request `NextcloudClient` with user's bearer token
+   - No tokens are stored server-side
+
+### The Challenge
+
+Background workers need long-lived authentication to:
+- Index content continuously/periodically
+- Process multiple users' data in batch operations
+- Operate when users are not actively making requests
+
+However, in OAuth mode:
+- User access tokens are ephemeral (exist only during request)
+- MCP server doesn't store user credentials
+- Admin credentials defeat the purpose of OAuth
+
+We need an OAuth-native solution that maintains security while enabling background operations.
+
+## Decision
+
+We will implement a **tiered OAuth authentication strategy** for background operations in OAuth mode. When OAuth authentication is not configured or available, the background sync feature is not available.
+
+**Note**: This ADR applies only to **OAuth mode**. In BasicAuth mode (single-user deployments), credentials are already available via environment variables, and background operations work without additional configuration.
+
+### OAuth "Act On-Behalf-Of" Principle
+
+**Core Requirement**: The MCP server must NEVER create its own user identity in Nextcloud when operating in OAuth mode.
+
+**Valid Patterns**:
+- ✅ **Foreground operations**: Use user's access token from MCP request (currently implemented)
+- ✅ **Background operations**: Token exchange to impersonate/delegate as user (requires provider support)
+- ❌ **Service account**: Creates independent identity in Nextcloud (violates OAuth principles)
+
+**Why This Matters**:
+1. **Audit Trail**: All operations must be attributable to the actual user, not a service account
+2. **Stateless Server**: MCP server should not have persistent identity/state in Nextcloud
+3. **Security Model**: Avoid creating "admin by another name" with broad cross-user permissions
+4. **OAuth Design**: OAuth tokens represent user authorization, not server authorization
+
+**If Token Exchange Not Available**:
+- Background operations simply cannot happen in OAuth mode
+- This is correct behavior - not a limitation to work around
+- Don't create service accounts as "workaround" - this defeats OAuth's purpose
+- Use BasicAuth mode if background operations are critical to your deployment
+
+### Tier 1: Token Exchange with Impersonation (RFC 8693) ⚠️ **NOT IMPLEMENTED**
+
+**Better Security** - Requires provider support for user impersonation
+
+- Service account exchanges token to impersonate specific users
+- Each background operation runs as the target user
+- Uses `requested_subject` parameter in token exchange
+- Per-user permission enforcement at API level
+
+**Requirements**:
+- OIDC provider supports RFC 8693 token exchange
+- Provider supports user impersonation (rare - requires Legacy Keycloak V1 with preview features)
+- Service account has impersonation permissions
+
+**Status**: ⚠️ Not implemented - Keycloak Standard V2 doesn't support impersonation
+**Reference**: See `docs/oauth-impersonation-findings.md` for investigation details
+
+### Tier 2: Token Exchange with Delegation (RFC 8693) ✅ **IMPLEMENTED**
+
+**Best Security** - Requires provider support for delegation with `act` claim
+
+- Service account exchanges token on behalf of users (delegation, not impersonation)
+- Token includes `act` claim showing service account as actor
+- API sees both the user (`sub`) and actor (`act`) in token
+- Full audit trail of delegated operations
+- **Implementation**: `KeycloakOAuthClient.exchange_token_for_user()` (keycloak_oauth.py:397-495)
+- **Testing**: Manual test in `tests/manual/test_token_exchange.py`
+- **Limitation**: Keycloak doesn't support `act` claim yet - [Issue #38279](https://github.com/keycloak/keycloak/issues/38279)
+
+**Requirements**:
+- OIDC provider supports RFC 8693 token exchange
+- Provider supports delegation with `act` claim (very rare)
+- Proper token exchange permissions configured
+
+**Current Implementation**: Internal-to-internal token exchange with audience modification (without `act` claim)
+
+### ❌ Will Not Implement
+
+**1. Service Account with Independent Identity (client_credentials)**
+- **Status**: Previously proposed as Tier 1, now rejected
+- **Why Invalid**: Creates Nextcloud user account for MCP server (e.g., `service-account-nextcloud-mcp-server`)
+- **Problems**:
+  - **Violates OAuth "act on-behalf-of" principle**: Actions attributed to service account instead of real user
+  - **Breaks audit trail**: Can't determine which user initiated the action
+  - **Creates stateful server identity**: MCP server has persistent identity/data in Nextcloud
+  - **Security risk**: Service account becomes "admin by another name" with broad cross-user permissions
+  - **User provisioning side effect**: Nextcloud's `user_oidc` app auto-provisions service account as real user
+- **Code Status**: Implementation exists (`KeycloakOAuthClient.get_service_account_token()`) but marked with warnings
+- **Alternative**: If service account pattern truly needed, use BasicAuth mode instead of OAuth mode
+- **Reference**: See commit c12df98 for detailed analysis of why this approach was rejected
+
+**2. Offline Access with Refresh Tokens**
+- **MCP Protocol Architecture**: FastMCP SDK manages OAuth where MCP Client handles refresh tokens
+- **Security Model**: Refresh tokens must never be shared between client and server (OAuth best practice)
+- **Technical Impossibility**: MCP Server has no access to refresh tokens from the OAuth callback
+- **Alternative**: Token exchange provides similar benefits without violating OAuth security model
+
+**3. Admin Credentials Fallback**
+- **Out of Scope**: This ADR focuses on OAuth mode only
+- **Not Appropriate**: Admin credentials bypass OAuth security model
+- **BasicAuth Mode**: For single-user deployments needing background operations, use BasicAuth mode instead
+
+### Key Architectural Principles
+
+1. **Capability Detection**: Automatically detect which OAuth methods are supported
+2. **Dual-Phase Authorization**:
+   - Sync worker indexes with service credentials
+   - User requests verify access with user's OAuth token
+3. **Defense in Depth**: Vector database is search accelerator, not security boundary
+4. **Separation of Concerns**: Sync credentials ≠ Request credentials
+
+## Implementation Details
+
+### 1. Token Exchange with Impersonation (Tier 1) ✅ IMPLEMENTED (Legacy V1 only)
+
+**Status**: Implemented and working with Keycloak Legacy V1 (`--features=preview`). Requires additional permission configuration. Recommended for advanced use cases only.
+
+**When to Use**: When you need the exchanged token to have the exact same identity as the target user (sub claim changes). This provides the cleanest separation but requires preview features.
+
+#### 1.1 Impersonation Flow
+
+```python
+async def exchange_token_for_user(
+    subject_token: str,
+    target_user_id: str,
+    audience: str | None = None,
+    scopes: list[str] | None = None,
+) -> dict:
+    """Exchange service token to impersonate specific user.
+
+    Requires Keycloak Legacy V1 (--features=preview) and impersonation permissions.
+    The returned token will have the target_user_id as the 'sub' claim.
+    """
+    data = {
+        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+        "subject_token": subject_token,
+        "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
+        "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
+        "requested_subject": target_user_id,  # ← KEY: Impersonate this user
+    }
+
+    if audience:
+        data["audience"] = audience
+    if scopes:
+        data["scope"] = " ".join(scopes)
+
+    response = await self._http_client.post(
+        self.token_endpoint,
+        data=data,
+        auth=(self.client_id, self.client_secret),
+    )
+    response.raise_for_status()
+    return response.json()
+```
+
+**Implementation Requirements**:
+- ✅ Keycloak Legacy V1 with `--features=preview` flag
+- ✅ Impersonation role granted to service account (see configuration below)
+- ❌ NOT supported in Keycloak Standard V2 (rejects `requested_subject` parameter)
+- ⚠️ Very few OIDC providers support user impersonation via token exchange
+
+**Empirical Testing (2025-11-02)**:
+
+Tested impersonation with `requested_subject` parameter against Keycloak 26.4.2:
+
+**Test Command**: `uv run python tests/manual/test_impersonation.py`
+
+**Keycloak Standard V2 Result**:
+```
+HTTP/1.1 400 Bad Request
+{
+  "error": "invalid_request",
+  "error_description": "Parameter 'requested_subject' is not supported for standard token exchange"
+}
+```
+
+**Confirmation**: Keycloak explicitly rejects `requested_subject` in Standard V2, confirming this feature is unsupported. The error message is unambiguous - this parameter is not available in the current production token exchange implementation.
+
+**Keycloak Legacy V1 Result - Initial Test** (with `--features=preview`):
+```
+HTTP/1.1 403 Forbidden
+{
+  "error": "access_denied",
+  "error_description": "Client not allowed to exchange"
+}
+
+Keycloak logs:
+reason="subject not allowed to impersonate"
+impersonator="service-account-nextcloud-mcp-server"
+requested_subject="admin"
+```
+
+**Analysis**: Legacy V1 **accepts** the `requested_subject` parameter (error changed from "not supported" to "not allowed"), indicating the feature is present but requires permission configuration.
+
+**Configuration Steps to Enable Impersonation**:
+
+1. **Enable Keycloak preview features** (in docker-compose.yml):
+   ```yaml
+   command:
+     - "start-dev"
+     - "--features=preview"  # Required for Legacy V1 token exchange
+   ```
+
+2. **Grant impersonation role to service account** (using Keycloak CLI):
+   ```bash
+   docker compose exec keycloak /opt/keycloak/bin/kcadm.sh config credentials \
+     --server http://localhost:8080 \
+     --realm master \
+     --user admin \
+     --password admin
+
+   docker compose exec keycloak /opt/keycloak/bin/kcadm.sh add-roles \
+     -r nextcloud-mcp \
+     --uusername service-account-nextcloud-mcp-server \
+     --cclientid realm-management \
+     --rolename impersonation
+   ```
+
+**Keycloak Legacy V1 Result - After Permission Grant**:
+```
+✅ Token exchange with impersonation SUCCEEDED!
+
+📊 Response details:
+  Issued token type: urn:ietf:params:oauth:token-type:access_token
+  Token type: Bearer
+  Expires in: 300s
+
+📋 Token claims analysis:
+  Subject (sub): 47c3ba5a-9104-45e0-b84e-0e39ab942c9c  (admin user)
+  Preferred username: admin
+  Client ID (azp): nextcloud-mcp-server
+
+✅ IMPERSONATION VERIFIED:
+   Original sub: service-account-nextcloud-mcp-server
+   New sub:      47c3ba5a-9104-45e0-b84e-0e39ab942c9c
+   ➡️  The subject claim CHANGED - impersonation worked!
+```
+
+**Nextcloud API Validation**:
+The impersonated token successfully authenticated with Nextcloud APIs, confirming the token is valid and properly represents the target user.
+
+**Implementation Status**: Impersonation **IS IMPLEMENTED** and working with Keycloak Legacy V1. The implementation has been tested and verified to work correctly when properly configured.
+
+**Production Considerations**:
+- ⚠️ Requires preview features (`--features=preview`) - not production-ready
+- ⚠️ Requires Legacy V1 token exchange (may be deprecated in future Keycloak versions)
+- ⚠️ Requires manual CLI configuration for each service account
+- ⚠️ More complex permission model compared to delegation
+
+**When to Use Tier 1 (Impersonation)**:
+- ✅ You need the exchanged token to have the exact same identity as the target user
+- ✅ You want the cleanest separation (sub claim changes completely)
+- ✅ Your environment can support preview features
+- ✅ You have operational processes to manage impersonation permissions
+
+**Recommendation**: For most use cases, use Tier 2 (Delegation) instead. It provides equivalent "act on-behalf-of" capability using production-ready Standard V2 token exchange. Use Tier 1 only when you specifically need identity impersonation.
+
+**Test Scripts**:
+- `tests/manual/test_impersonation.py` - Complete impersonation test with validation
+- `tests/manual/configure_impersonation.py` - Automated permission configuration helper
+- **See**: `docs/oauth-impersonation-findings.md` for detailed investigation
+
+### 2. Token Exchange with Delegation (Tier 2) ✅ IMPLEMENTED (Standard V2)
+
+**Status**: Implemented and working with Keycloak Standard V2 (production-ready). This is the **recommended** approach for most use cases.
+
+**When to Use**: When you need "act on-behalf-of" functionality with production-ready features. The service account maintains its identity (sub claim unchanged) but acts on behalf of the user. Fully supported in Keycloak Standard V2 without preview features.
+
+#### 2.1 Capability Detection
+```python
+async def check_token_exchange_support(discovery_url: str) -> bool:
+    """Check if OIDC provider supports RFC 8693 token exchange"""
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(discovery_url)
+        discovery = response.json()
+
+        # Check for token exchange grant type
+        grant_types = discovery.get("grant_types_supported", [])
+        return "urn:ietf:params:oauth:grant-type:token-exchange" in grant_types
+```
+
+#### 2.2 Delegation Token Exchange
+```python
+async def exchange_for_user_token(
+    service_token: str,
+    target_user_id: str,
+    audience: str,
+    scopes: list[str]
+) -> str:
+    """Exchange service token for user-scoped token via RFC 8693"""
+
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            token_endpoint,
+            data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+                "subject_token": service_token,
+                "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
+                "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
+                "audience": audience,  # Target resource server (e.g., "nextcloud")
+                "scope": " ".join(scopes)
+            },
+            auth=(client_id, client_secret)
+        )
+
+        if response.status_code != 200:
+            logger.warning(f"Token exchange failed: {response.status_code}")
+            raise TokenExchangeNotSupportedError()
+
+        return response.json()["access_token"]
+```
+
+**Implementation**: `KeycloakOAuthClient.exchange_token_for_user()` (keycloak_oauth.py:397-495)
+
+**Note**: Full delegation with `act` claim requires provider support that is currently very rare. Keycloak tracking: [Issue #38279](https://github.com/keycloak/keycloak/issues/38279)
+
+### 3. Comparison: When to Use Each Tier
+
+| Feature | Tier 1: Impersonation | Tier 2: Delegation (Recommended) |
+|---------|----------------------|-----------------------------------|
+| **Status** | ✅ Implemented (Legacy V1) | ✅ Implemented (Standard V2) |
+| **Token Identity** | Target user (`sub` changes) | Service account (`sub` unchanged) |
+| **Keycloak Version** | Legacy V1 (`--features=preview`) | Standard V2 (production-ready) |
+| **Setup Complexity** | High (manual permissions) | Low (automatic) |
+| **Production Ready** | ⚠️ Preview features required | ✅ Fully production-ready |
+| **Permission Grant** | Manual CLI per service account | Automatic via token exchange |
+| **Audit Trail** | Shows as target user | Shows as service account acting for user |
+| **Token Claims** | `sub: user-id` | `sub: service-account-id` |
+| **Provider Support** | Rare (Keycloak Legacy V1 only) | Common (Keycloak, Auth0, Okta) |
+| **Use Case** | Need exact user identity | Standard OAuth workflows |
+| **Recommendation** | Advanced use only | **Default choice** |
+
+**Decision Guide**:
+- ✅ **Use Tier 2 (Delegation)** for:
+  - Production deployments
+  - Standard OAuth workflows
+  - Clear audit trails (service account visible)
+  - Maximum provider compatibility
+
+- ⚠️ **Use Tier 1 (Impersonation)** only if:
+  - You specifically need exact user identity (sub claim must match)
+  - You can accept preview/experimental features
+  - You have operational processes for permission management
+  - Your IdP supports `requested_subject` parameter
+
+### 4. Sync Worker with Tiered Authentication
+
+```python
+# nextcloud_mcp_server/sync_worker.py
+class VectorSyncWorker:
+    """Background worker for indexing content into vector database"""
+
+    def __init__(self):
+        self.auth_method = None
+        self.oauth_client = None  # KeycloakOAuthClient or similar
+        self.vector_service = None
+
+    async def initialize(self):
+        """Detect and configure authentication method"""
+
+        from nextcloud_mcp_server.auth.keycloak_oauth import KeycloakOAuthClient
+
+        try:
+            self.oauth_client = KeycloakOAuthClient.from_env()
+            await self.oauth_client.discover()
+
+            # Verify service account access (Tier 1)
+            service_token = await self.oauth_client.get_service_account_token()
+            logger.info("✓ Service account token acquired")
+
+            # Check if token exchange is supported (Tier 2/3)
+            if await check_token_exchange_support(self.oauth_client.discovery_url):
+                self.auth_method = "token_exchange_delegation"
+                logger.info(
+                    "✓ Token exchange supported (RFC 8693) - will use delegation for user-scoped operations"
+                )
+            else:
+                self.auth_method = "service_account"
+                logger.info(
+                    "ℹ Token exchange not supported - using service account token for all operations"
+                )
+
+        except Exception as e:
+            logger.error(f"Failed to initialize OAuth authentication: {e}")
+            raise RuntimeError(
+                "OAuth authentication is required for background sync. "
+                "Either configure OIDC_CLIENT_ID/OIDC_CLIENT_SECRET with service account enabled, "
+                "or use BasicAuth mode for single-user deployments."
+            ) from e
+
+    async def get_user_client(self, user_id: str) -> NextcloudClient:
+        """Get authenticated client for user based on auth method"""
+
+        if self.auth_method == "token_exchange_delegation":
+            # Tier 2/3: Get service token and exchange for user-scoped token
+            service_token_data = await self.oauth_client.get_service_account_token()
+
+            user_token_data = await self.oauth_client.exchange_token_for_user(
+                subject_token=service_token_data["access_token"],
+                target_user_id=user_id,
+                audience="nextcloud",
+                scopes=["notes:read", "files:read", "calendar:read"]
+            )
+
+            return NextcloudClient.from_token(
+                base_url=nextcloud_host,
+                token=user_token_data["access_token"],
+                username=user_id
+            )
+
+        elif self.auth_method == "service_account":
+            # Tier 1: Use service account token directly (no user scoping)
+            service_token_data = await self.oauth_client.get_service_account_token()
+
+            return NextcloudClient.from_token(
+                base_url=nextcloud_host,
+                token=service_token_data["access_token"],
+                username="service-account"
+            )
+
+        raise RuntimeError(f"Unknown auth method: {self.auth_method}")
+
+    async def sync_user_content(self, user_id: str):
+        """Index a user's content into vector database"""
+
+        try:
+            # Get authenticated client for this user
+            client = await self.get_user_client(user_id)
+
+            # Sync notes
+            notes = await client.notes.list_notes()
+            for note in notes:
+                embedding = await self.vector_service.embed(note.content)
+                await self.vector_service.upsert(
+                    collection="nextcloud_content",
+                    id=f"note_{note.id}",
+                    vector=embedding,
+                    metadata={
+                        "user_id": user_id,
+                        "content_type": "note",
+                        "note_id": note.id,
+                        "title": note.title,
+                        "category": note.category
+                    }
+                )
+
+            logger.info(f"Synced {len(notes)} notes for user: {user_id}")
+
+        except Exception as e:
+            logger.error(f"Failed to sync user {user_id}: {e}")
+
+    async def run(self):
+        """Main sync loop"""
+
+        await self.initialize()
+
+        while True:
+            try:
+                # Get list of users to sync
+                # Implementation depends on how you track authenticated users
+                # Options:
+                # - Audit logs of MCP authentication events
+                # - MCP session history
+                # - Configured user list
+                # - If using service account with broad permissions: list all users
+                user_ids = await self.get_active_users()
+
+                logger.info(f"Syncing content for {len(user_ids)} users")
+
+                for user_id in user_ids:
+                    await self.sync_user_content(user_id)
+
+                logger.info("Sync complete, sleeping...")
+                await asyncio.sleep(300)  # 5 minutes
+
+            except Exception as e:
+                logger.error(f"Sync failed: {e}")
+                await asyncio.sleep(60)  # Retry after 1 minute
+```
+
+### 4. User Request Verification (Dual-Phase Authorization)
+
+```python
+@mcp.tool()
+@require_scopes("notes:read")
+async def nc_notes_semantic_search(
+    query: str,
+    ctx: Context,
+    limit: int = 10
+) -> SemanticSearchResponse:
+    """Semantic search with permission verification"""
+
+    # Get user's OAuth client (uses their access token from request)
+    user_client = get_client(ctx)
+    username = user_client.username
+
+    # Phase 1: Vector search (fast, may include false positives)
+    embedding = await vector_service.embed(query)
+    candidate_results = await qdrant.search(
+        collection_name="nextcloud_content",
+        query_vector=embedding,
+        query_filter={
+            "must": [
+                {
+                    "should": [
+                        {"key": "user_id", "match": {"value": username}},
+                        {"key": "shared_with", "match": {"any": [username]}}
+                    ]
+                },
+                {"key": "content_type", "match": {"value": "note"}}
+            ]
+        },
+        limit=limit * 2  # Get extra candidates
+    )
+
+    # Phase 2: Verify access via Nextcloud API (authoritative)
+    verified_results = []
+    for candidate in candidate_results:
+        note_id = candidate.payload["note_id"]
+        try:
+            # This uses user's OAuth token - will fail if no access
+            note = await user_client.notes.get_note(note_id)
+            verified_results.append({
+                "note": note,
+                "score": candidate.score
+            })
+            if len(verified_results) >= limit:
+                break
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                # User doesn't have access - skip silently
+                logger.debug(f"Filtered out note {note_id} for {username}")
+                continue
+            raise
+
+    return SemanticSearchResponse(results=verified_results)
+```
+
+### 5. Security Implementation
+
+#### 5.1 Service Account Credentials Protection
+```python
+# Store OAuth client credentials securely
+# NEVER commit to source control
+
+# Option 1: Environment variables (for development)
+export OIDC_CLIENT_ID="nextcloud-mcp-server"
+export OIDC_CLIENT_SECRET="<secure-secret>"
+
+# Option 2: Secrets manager (for production)
+import boto3
+secrets = boto3.client('secretsmanager')
+secret = secrets.get_secret_value(SecretId='nextcloud-mcp-oauth')
+client_secret = json.loads(secret['SecretString'])['client_secret']
+
+# Option 3: Encrypted storage (for self-hosted)
+from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+
+storage = RefreshTokenStorage.from_env()
+await storage.initialize()
+
+# Client credentials are encrypted at rest using Fernet
+client_data = await storage.get_oauth_client()
+```
+
+#### 5.2 Token Lifecycle Management
+```python
+async def manage_service_token_lifecycle():
+    """Cache and refresh service account tokens"""
+
+    # Cache service token (avoid repeated requests)
+    cached_token = None
+    token_expires_at = 0
+
+    async def get_fresh_service_token() -> str:
+        nonlocal cached_token, token_expires_at
+
+        now = time.time()
+
+        # Return cached token if still valid (with 5-minute buffer)
+        if cached_token and now < (token_expires_at - 300):
+            return cached_token
+
+        # Request new token
+        token_data = await oauth_client.get_service_account_token()
+
+        cached_token = token_data["access_token"]
+        token_expires_at = now + token_data.get("expires_in", 3600)
+
+        logger.info("Service account token refreshed")
+        return cached_token
+
+    return get_fresh_service_token
+```
+
+#### 5.3 Audit Logging
+```python
+async def audit_log(
+    event: str,
+    user_id: str,
+    resource_type: str,
+    resource_id: str,
+    auth_method: str
+):
+    """Log sync operations for audit trail"""
+
+    await audit_db.execute(
+        "INSERT INTO audit_logs VALUES (?, ?, ?, ?, ?, ?, ?)",
+        (
+            int(time.time()),
+            event,  # "index_note", "index_file"
+            user_id,
+            resource_type,
+            resource_id,
+            auth_method,
+            socket.gethostname()
+        )
+    )
+```
+
+### 6. Configuration
+
+#### 6.1 Environment Variables
+```bash
+# OAuth Configuration (Required for Background Sync in OAuth Mode)
+# Requires external OIDC provider with client_credentials support
+OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+OIDC_CLIENT_ID=nextcloud-mcp-server
+OIDC_CLIENT_SECRET=<secure-secret>
+NEXTCLOUD_HOST=http://app:80
+
+# Tier selection is automatic:
+# - Tier 1 (service_account): Always available if client has service account enabled
+# - Tier 2/3 (token_exchange): Used if provider supports RFC 8693 token exchange
+
+# Vector Database
+QDRANT_URL=http://qdrant:6333
+QDRANT_API_KEY=<api-key>
+
+# Sync Configuration
+SYNC_INTERVAL_SECONDS=300
+SYNC_BATCH_SIZE=100
+
+# Note: For BasicAuth mode (single-user), background sync uses NEXTCLOUD_USERNAME/NEXTCLOUD_PASSWORD
+# This ADR focuses on OAuth mode only
+```
+
+#### 6.2 Keycloak Configuration (for Token Exchange)
+
+**Client Settings** (`nextcloud-mcp-server`):
+```json
+{
+  "clientId": "nextcloud-mcp-server",
+  "serviceAccountsEnabled": true,
+  "authorizationServicesEnabled": false,
+  "attributes": {
+    "token.exchange.grant.enabled": "true",
+    "client.token.exchange.standard.enabled": "true"
+  }
+}
+```
+
+**Service Account Roles**:
+- Assign appropriate Nextcloud roles/scopes to the service account
+- Configure token exchange permissions
+
+#### 6.3 Docker Compose
+```yaml
+services:
+  mcp-sync:
+    build: .
+    command: ["python", "-m", "nextcloud_mcp_server.sync_worker"]
+    environment:
+      - NEXTCLOUD_HOST=http://app:80
+
+      # External OIDC provider (Keycloak)
+      - OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+      - OIDC_CLIENT_ID=nextcloud-mcp-server
+      - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
+
+      # Vector database
+      - QDRANT_URL=http://qdrant:6333
+      - QDRANT_API_KEY=${QDRANT_API_KEY}
+    volumes:
+      - sync-data:/app/data  # For OAuth client credential storage
+    depends_on:
+      - app
+      - keycloak
+      - qdrant
+
+volumes:
+  sync-data:  # Persistent storage for encrypted OAuth client credentials
+```
+
+## Consequences
+
+### Benefits
+
+1. **OAuth-Native Authentication**
+   - Leverages standard OAuth flows (offline_access, token exchange)
+   - No reliance on admin passwords in production
+   - Compatible with enterprise OIDC providers
+
+2. **User-Level Permissions**
+   - Each user's content indexed with their own credentials
+   - Respects sharing, permissions, and access controls
+   - Full audit trail of which user's token was used
+
+3. **Security**
+   - Tokens encrypted at rest
+   - Short-lived access tokens (refreshed as needed)
+   - Token rotation support
+   - Defense in depth with dual-phase authorization
+
+4. **Flexibility**
+   - Automatic capability detection
+   - Graceful degradation through authentication tiers
+   - Works with varying OIDC provider capabilities
+
+5. **Operational**
+   - Background sync independent of user activity
+   - Efficient batch processing
+   - Clear separation of sync vs request credentials
+
+### Limitations
+
+1. **Complexity**
+   - Multiple authentication paths to maintain
+   - Token storage and encryption infrastructure
+   - More moving parts than simple admin auth
+
+2. **User Experience**
+   - `offline_access` scope may require additional consent
+   - Users must authenticate at least once for indexing
+   - New users not automatically indexed
+
+3. **OIDC Provider Dependency**
+   - Token exchange requires RFC 8693 support (rare)
+   - Refresh token rotation varies by provider
+   - Some providers may not support offline_access
+
+4. **Operational Overhead**
+   - Token database maintenance
+   - Monitoring token expiration
+   - Handling revoked tokens gracefully
+
+### Security Considerations
+
+#### Threat Model
+
+**Threat 1: Token Storage Breach**
+- **Mitigation**: Encryption at rest using Fernet
+- **Mitigation**: Secure key management (secrets manager)
+- **Mitigation**: Minimal token lifetime
+- **Detection**: Audit logs for unusual access patterns
+
+**Threat 2: Token Replay**
+- **Mitigation**: Short-lived access tokens (refreshed frequently)
+- **Mitigation**: Token rotation on each refresh
+- **Mitigation**: Revocation support
+
+**Threat 3: Privilege Escalation**
+- **Mitigation**: Dual-phase authorization (vector DB + Nextcloud API)
+- **Mitigation**: Sync worker uses same scopes as user requests
+- **Mitigation**: Per-user token isolation
+
+**Threat 4: Vector Database Poisoning**
+- **Mitigation**: User requests always verify via Nextcloud API
+- **Mitigation**: Vector DB is cache/accelerator, not source of truth
+- **Mitigation**: Sync operations audited per user
+
+#### Security Best Practices
+
+1. **OAuth Client Secret Management**
+   ```bash
+   # Store in secrets manager (Vault, AWS Secrets Manager, etc.)
+   # Or use environment variable with restricted permissions
+
+   # For self-hosted: Use encrypted storage
+   # OAuth client credentials stored in SQLite with Fernet encryption
+   # Encryption key: TOKEN_ENCRYPTION_KEY environment variable
+
+   # Generate encryption key:
+   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+   ```
+
+2. **Service Account Token Lifecycle**
+   - Cache service tokens to minimize requests (with expiry buffer)
+   - Automatically refresh expired tokens
+   - Use short-lived tokens (provider default, typically 1 hour)
+   - Monitor token request rates and failures
+
+3. **Database Permissions (for Client Credential Storage)**
+   ```bash
+   # Restrict database file permissions
+   chmod 600 /app/data/tokens.db
+   chown mcp-server:mcp-server /app/data/tokens.db
+   ```
+
+4. **Monitoring and Alerting**
+   - Alert on token exchange failures
+   - Monitor for unusual access patterns
+   - Track service account token usage
+   - Audit sync operations per user (if delegation supported)
+
+### Future Enhancements
+
+1. **Token Revocation Handling**
+   - Webhook endpoint for token revocation events
+   - Periodic validation of stored tokens
+   - Graceful handling of revoked tokens
+
+2. **Selective Sync**
+   - Allow users to opt-in/opt-out of indexing
+   - Per-content-type sync preferences
+   - Privacy controls for sensitive content
+
+3. **Multi-Tenant Token Storage**
+   - Separate token databases per tenant
+   - Key rotation per tenant
+   - Tenant isolation
+
+4. **Token Lifecycle Management**
+   - Automatic cleanup of expired tokens
+   - Token usage analytics
+   - Token health dashboard
+
+5. **Alternative OAuth Flows**
+   - Device flow for headless sync
+   - Resource owner password credentials (ROPC) as fallback
+   - SAML assertion grants
+
+## Alternatives Considered
+
+### Alternative 1: Admin BasicAuth Only
+
+**Approach**: Background worker always uses admin credentials
+
+**Pros**:
+- Simple implementation
+- No token storage complexity
+- Works with any authentication backend
+
+**Cons**:
+- Violates principle of least privilege
+- Single powerful credential
+- No per-user audit trail
+- Bypasses OAuth entirely
+
+**Decision**: Rejected for production use; kept as fallback only
+
+### Alternative 2: Client Credentials Grant Only
+
+**Approach**: Service account with broad read permissions
+
+**Pros**:
+- OAuth-native pattern
+- No user token storage
+- Standard OAuth flow
+
+**Cons**:
+- Requires client_credentials support (may not be available)
+- Still needs broad cross-user permissions
+- Not well-suited for multi-user indexing
+
+**Decision**: Rejected; token exchange is better fit for multi-user scenario
+
+### Alternative 3: Per-User Access Token Storage
+
+**Approach**: Store user access tokens (not refresh tokens)
+
+**Pros**:
+- Simpler than refresh token flow
+- No token refresh logic needed
+
+**Cons**:
+- Access tokens are short-lived (1-24 hours)
+- Requires frequent re-authentication
+- Poor user experience
+- Sync gaps when tokens expire
+
+**Decision**: Rejected; refresh tokens provide better UX
+
+### Alternative 4: On-Demand Indexing Only
+
+**Approach**: Index content when user searches (no background worker)
+
+**Pros**:
+- Uses user's request token
+- No background auth needed
+- Simpler architecture
+
+**Cons**:
+- Very slow first search
+- Poor user experience
+- Incomplete index
+- Can't pre-compute embeddings
+
+**Decision**: Rejected; background indexing is essential for semantic search
+
+### Alternative 5: Nextcloud App Tokens
+
+**Approach**: Generate app-specific passwords for each user
+
+**Pros**:
+- Nextcloud-native feature
+- User-controlled revocation
+- Scoped per-application
+
+**Cons**:
+- Requires user interaction to create
+- May not support programmatic creation
+- Still requires secure storage
+- Not standard OAuth
+
+**Decision**: Rejected; not automatable for background worker
+
+## Related Decisions
+
+- ADR-001: Enhanced Note Search (establishes need for vector search)
+- [Future] ADR-003: Vector Database Selection
+- [Future] ADR-004: Embedding Model Strategy
+
+## References
+
+- [RFC 8693: OAuth 2.0 Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693)
+- [RFC 6749: OAuth 2.0 - Refresh Tokens](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5)
+- [OpenID Connect Core - Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)
+- [OWASP: OAuth Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/OAuth2_Cheat_Sheet.html)
+- [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)

docs/ADR-004-Code-Review.md

@@ -0,0 +1,65 @@
+Excellent and incredibly thorough work on ADR-004. It outlines a robust, secure, and modern approach to federated authentication that aligns with industry best practices. The Progressive Consent architecture with dual OAuth flows is the right direction for a system with these requirements.
+
+Here is a review of the current implementation in light of the architecture proposed in the ADR.
+
+### High-Level Assessment
+
+The project is in a good state, with a clear vision for its authentication architecture. The current implementation provides a backward-compatible "Hybrid Flow" while also containing the scaffolding for the target "Progressive Consent" flow. The hybrid flow is well-tested, which is a great foundation.
+
+The following points are intended to help bridge the gap between the current implementation and the final vision outlined in ADR-004.
+
+### Critical Security Review
+
+#### 1. Missing Token Audience (`aud`) Validation
+
+This is the most critical issue. The `require_scopes` decorator currently checks for scopes but does not validate the `audience` (`aud` claim) of the incoming JWT.
+
+*   **Risk:** This creates a "confused deputy" vulnerability. An access token issued for a different application could be used to access the MCP server, as long as the scope names happen to match.
+*   **ADR Reference:** The ADR correctly identifies this and proposes an `MCPTokenVerifier` that validates `aud: "mcp-server"`.
+*   **Recommendation:** Implement the audience validation as a central part of your token verification middleware. An incoming token should be rejected immediately if its audience is not `mcp-server`. This check should happen before any tool-specific scope checks.
+
+### Architecture and Implementation Review
+
+#### 2. Progressive Consent Flow is Untested
+
+The code for the Progressive Consent flow (behind the `ENABLE_PROGRESSIVE_CONSENT` flag) exists in `oauth_routes.py` and `oauth_tools.py`. However, there are no integration tests to validate it.
+
+*   **Risk:** Given the complexity of OAuth flows, it's likely there are bugs in the untested implementation.
+*   **Recommendation:** Create a new test file, `test_adr004_progressive_flow.py`, that uses Playwright to test the dual-flow architecture end-to-end:
+    1.  **Flow 1:** A test MCP client authenticates directly with the IdP to get an `mcp-server` token.
+    2.  **Provisioning Check:** The test verifies that calling a Nextcloud tool fails with a `ProvisioningRequiredError`.
+    3.  **Flow 2:** The test calls the `provision_nextcloud_access` tool and automates the second OAuth flow to grant the server offline access.
+    4.  **Tool Execution:** The test verifies that Nextcloud tools can now be successfully called.
+
+#### 3. Inconsistent Authorization URL Generation
+
+There is duplicated and inconsistent logic for generating the IdP authorization URL.
+
+*   **Location 1:** `oauth_tools.py` in `generate_oauth_url_for_flow2` hardcodes the authorization endpoint path.
+*   **Location 2:** `oauth_routes.py` in `oauth_authorize_nextcloud` correctly uses the OIDC discovery document to find the `authorization_endpoint`.
+*   **Risk:** The hardcoded path is brittle and will break with IdPs that use different endpoint paths (like Keycloak).
+*   **Recommendation:** Consolidate this logic. The `provision_nextcloud_access` tool should not build the URL itself. Instead, it should return a URL pointing to the MCP server's own `/oauth/authorize-nextcloud` endpoint. This endpoint (which you've already created as `oauth_authorize_nextcloud` in `oauth_routes.py`) can then be the single source of truth for generating the IdP redirect.
+
+#### 4. Poor User Experience due to Missing Token Refresh
+
+The `/oauth/token` endpoint does not implement the `refresh_token` grant type. This means that when the client's `mcp-server` access token expires (e.g., after one hour), the user must go through the entire browser-based login flow again.
+
+*   **Risk:** This creates a frustrating user experience, especially for long-lived desktop clients.
+*   **ADR Reference:** A proper Flow 1 should result in the MCP client receiving both an access token and a refresh token from the IdP.
+*   **Recommendation:**
+    1.  Ensure the IdP is configured to issue refresh tokens to the MCP client for Flow 1.
+    2.  The MCP client should securely store this refresh token.
+    3.  The client should use the refresh token to get new `mcp-server` access tokens directly from the IdP, without involving the MCP server or the user. The MCP server should not be involved in the client's session management with the IdP.
+
+### Summary
+
+The project is on the right track. The ADR is a solid plan, and the initial implementation is a good starting point.
+
+My recommendations in order of priority are:
+
+1.  **Implement Audience Validation** to close the security gap.
+2.  **Add Integration Tests** for the Progressive Consent flow.
+3.  **Refactor the client-side token refresh** to improve user experience.
+4.  **Consolidate the URL generation** logic to fix the inconsistency.
+
+Addressing these points will align the implementation with the excellent vision in ADR-004 and result in a secure, robust, and user-friendly system.

docs/ADR-006-progressive-consent-elicitation.md

@@ -0,0 +1,865 @@
+# ADR-006: Progressive Consent via URL Elicitation (SEP-1036)
+
+**Status**: Partially Implemented (Interim Workaround)
+**Date**: 2025-01-05 (Updated: 2025-01-07)
+**Related**: [SEP-1036](https://github.com/modelcontextprotocol/specification/pull/887), ADR-004
+**Depends On**: ADR-005 (token validation)
+
+## Context
+
+### What is Progressive Consent?
+
+**Progressive consent is a mechanism, not a feature**. It describes HOW users grant the MCP server access to Nextcloud resources through OAuth elicitation. The server can operate in two modes:
+
+1. **Pass-through mode (ENABLE_OFFLINE_ACCESS=false)**:
+   - No refresh tokens requested or stored
+   - Server passes through client's access token to Nextcloud
+   - No provisioning tools available
+   - Suitable for stateless, client-driven operations
+
+2. **Offline access mode (ENABLE_OFFLINE_ACCESS=true)**:
+   - Server requests `offline_access` scope and stores refresh tokens
+   - Enables background operations and server-initiated API calls
+   - Provisioning tools available (`provision_nextcloud_access`, `check_logged_in`)
+   - Requires explicit user consent via OAuth Flow 2
+
+**Single-user mode (BasicAuth)** doesn't use progressive consent at all - credentials are directly available.
+
+### Current User Experience Issues
+
+The current offline access provisioning flow (ADR-004) requires users to manually visit OAuth URLs returned by MCP tools. This creates a poor user experience:
+
+1. User calls `provision_nextcloud_access` tool
+2. Tool returns a URL as text in the response
+3. User must manually copy URL and open in browser
+4. No indication when provisioning is complete
+5. User must retry the original operation manually
+
+### SEP-1036: URL Mode Elicitation
+
+The MCP specification now supports **URL mode elicitation** ([SEP-1036](https://github.com/modelcontextprotocol/specification/pull/887)), which enables servers to:
+
+- Request out-of-band user interactions via secure URLs
+- Handle sensitive operations like OAuth flows without exposing credentials to the client
+- Provide progress tracking for async operations
+- Return errors that automatically trigger elicitation flows
+
+**Key benefits for progressive consent**:
+- **Automatic URL Opening**: Client opens URL in browser automatically (with user consent)
+- **Progress Tracking**: Server can notify client when provisioning is complete
+- **Error-Triggered Flows**: Server can return `ElicitationRequired` error to trigger provisioning
+- **Better UX**: User doesn't manually copy/paste URLs
+
+### Current Implementation Limitations
+
+The current progressive consent flow in `nextcloud_mcp_server/server/oauth_tools.py`:
+
+```python
+@mcp.tool(name="provision_nextcloud_access")
+async def tool_provision_access(ctx: Context) -> ProvisioningResult:
+    """Returns OAuth URL as text - user must manually open it."""
+    return ProvisioningResult(
+        success=True,
+        authorization_url=auth_url,  # User must copy this
+        message="Please visit the authorization URL..."
+    )
+```
+
+**Problems**:
+1. Manual URL handling (copy/paste)
+2. No progress tracking
+3. No automatic retry after provisioning
+4. Tool call required just to get URL
+5. No client integration (URL just displayed as text)
+
+## Decision
+
+We will **migrate progressive consent from manual tools to URL mode elicitation**, leveraging SEP-1036 for better user experience and OAuth security.
+
+### New Architecture: Elicitation-Driven Consent
+
+Instead of explicit tools, use **automatic elicitation** triggered by authorization errors:
+
+```
+User → Calls Nextcloud Tool → Server Checks Provisioning
+                                     ↓ Not Provisioned
+                                Error: ElicitationRequired
+                                     ↓
+                          Client Shows Consent UI
+                                     ↓ User Accepts
+                          Client Opens OAuth URL
+                                     ↓
+                          User Completes OAuth
+                                     ↓
+                          Server Sends Progress Update
+                                     ↓
+                      Original Tool Call Auto-Retries
+```
+
+### Mode 1: Elicitation-Required Error (Primary)
+
+When a tool requires provisioning, return an **ElicitationRequired error** (-32000):
+
+```python
+# In any Nextcloud tool decorated with @require_provisioning
+@mcp.tool()
+@require_provisioning  # New decorator
+async def nc_notes_list_notes(ctx: Context):
+    """List notes - auto-triggers provisioning if needed."""
+    # If not provisioned, decorator returns ElicitationRequired error
+    # If provisioned, continues normally
+    client = await get_client(ctx)
+    return await client.notes.list_notes()
+```
+
+**Error response structure**:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32000,
+    "message": "Nextcloud access provisioning required",
+    "data": {
+      "elicitations": [
+        {
+          "mode": "url",
+          "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
+          "url": "https://mcp.example.com/oauth/provision?id=550e8400...",
+          "message": "Grant the MCP server access to your Nextcloud account to continue."
+        }
+      ]
+    }
+  }
+}
+```
+
+**Client behavior**:
+1. Receives error with elicitation
+2. Shows consent UI: "App wants to access Nextcloud. Open authorization page?"
+3. On user acceptance, opens URL in browser
+4. Optionally tracks progress via `elicitation/track`
+5. Auto-retries original tool call when complete
+
+### Mode 2: Explicit Elicitation Request (Fallback)
+
+For clients that don't support error-triggered elicitation, provide explicit tool:
+
+```python
+@mcp.tool(name="request_nextcloud_access")
+async def request_access(ctx: Context) -> ElicitationResponse:
+    """Explicitly request provisioning via elicitation."""
+    # Send elicitation/create request
+    return await create_elicitation(
+        mode="url",
+        url=generate_oauth_url(),
+        message="Grant access to Nextcloud",
+        elicitation_id=generate_id()
+    )
+```
+
+**Note**: This is a fallback for compatibility. Primary flow uses error-triggered elicitation.
+
+## Implementation
+
+### 1. New Decorator: `@require_provisioning`
+
+Replace explicit provisioning checks with a decorator that returns `ElicitationRequired`:
+
+```python
+# nextcloud_mcp_server/auth/provisioning_decorator.py
+
+def require_provisioning(func):
+    """
+    Decorator that ensures user has provisioned Nextcloud access.
+
+    If not provisioned, returns ElicitationRequired error with OAuth URL.
+    Otherwise, proceeds with normal tool execution.
+    """
+    @functools.wraps(func)
+    async def wrapper(ctx: Context, *args, **kwargs):
+        # Extract user ID from token
+        user_id = get_user_id_from_context(ctx)
+
+        # Check if provisioned
+        storage = RefreshTokenStorage.from_env()
+        await storage.initialize()
+
+        if not await storage.has_refresh_token(user_id):
+            # Not provisioned - return ElicitationRequired error
+            elicitation_id = str(uuid.uuid4())
+            oauth_url = await generate_oauth_url_for_provisioning(
+                user_id=user_id,
+                elicitation_id=elicitation_id,
+                ctx=ctx
+            )
+
+            # Store elicitation for tracking
+            await storage.store_elicitation(
+                elicitation_id=elicitation_id,
+                user_id=user_id,
+                status="pending",
+                created_at=datetime.now(timezone.utc)
+            )
+
+            raise McpError(
+                code=ErrorCode.ELICITATION_REQUIRED,  # -32000
+                message="Nextcloud access provisioning required",
+                data={
+                    "elicitations": [
+                        {
+                            "mode": "url",
+                            "elicitationId": elicitation_id,
+                            "url": oauth_url,
+                            "message": (
+                                "Grant the MCP server access to your Nextcloud "
+                                "account to continue. This is a one-time setup."
+                            )
+                        }
+                    ]
+                }
+            )
+
+        # Already provisioned - proceed normally
+        return await func(ctx, *args, **kwargs)
+
+    return wrapper
+```
+
+### 2. Elicitation Tracking Endpoint
+
+Implement `elicitation/track` to provide progress updates:
+
+```python
+# nextcloud_mcp_server/server/elicitation.py
+
+@mcp.request_handler("elicitation/track")
+async def track_elicitation(
+    elicitation_id: str,
+    _meta: dict = None
+) -> dict:
+    """
+    Track progress of an elicitation request.
+
+    Returns when elicitation is complete or times out.
+    """
+    progress_token = _meta.get("progressToken") if _meta else None
+
+    storage = RefreshTokenStorage.from_env()
+    await storage.initialize()
+
+    # Poll for completion (with timeout)
+    timeout = 300  # 5 minutes
+    start_time = datetime.now(timezone.utc)
+
+    while (datetime.now(timezone.utc) - start_time).seconds < timeout:
+        elicitation = await storage.get_elicitation(elicitation_id)
+
+        if not elicitation:
+            raise McpError(
+                code=-32602,  # Invalid params
+                message=f"Unknown elicitation ID: {elicitation_id}"
+            )
+
+        # Send progress notification if token provided
+        if progress_token and elicitation["status"] == "pending":
+            await send_progress_notification(
+                progress_token=progress_token,
+                progress=50,
+                message="Waiting for OAuth authorization..."
+            )
+
+        # Check if complete
+        if elicitation["status"] == "complete":
+            return {"status": "complete"}
+
+        # Check if failed
+        if elicitation["status"] == "failed":
+            return {
+                "status": "failed",
+                "error": elicitation.get("error_message")
+            }
+
+        # Wait before polling again
+        await asyncio.sleep(2)
+
+    # Timeout
+    raise McpError(
+        code=-32000,
+        message="Elicitation timed out - user did not complete authorization"
+    )
+```
+
+### 3. OAuth Callback Updates
+
+Update the OAuth callback to mark elicitations as complete:
+
+```python
+# nextcloud_mcp_server/auth/oauth_routes.py
+
+async def oauth_callback(request: Request) -> Response:
+    """Handle OAuth callback and mark elicitation complete."""
+    code = request.query_params.get("code")
+    state = request.query_params.get("state")
+
+    # Validate and exchange code for tokens
+    tokens = await exchange_authorization_code(code)
+
+    # Store refresh token
+    await storage.store_refresh_token(
+        user_id=user_id,
+        refresh_token=tokens["refresh_token"]
+    )
+
+    # Mark elicitation as complete
+    elicitation_id = request.query_params.get("elicitation_id")
+    if elicitation_id:
+        await storage.update_elicitation(
+            elicitation_id=elicitation_id,
+            status="complete",
+            completed_at=datetime.now(timezone.utc)
+        )
+
+    return Response(
+        content="<h1>Authorization Complete!</h1>"
+        "<p>You can close this window and return to the application.</p>",
+        media_type="text/html"
+    )
+```
+
+### 4. Update All Nextcloud Tools
+
+Add `@require_provisioning` decorator to all Nextcloud tools:
+
+```python
+# nextcloud_mcp_server/server/notes.py
+
+@mcp.tool()
+@require_scopes("notes:read")
+@require_provisioning  # NEW: Auto-triggers provisioning
+async def nc_notes_list_notes(
+    ctx: Context,
+    category: Optional[str] = None
+) -> NotesListResponse:
+    """List all notes - automatically handles provisioning."""
+    client = await get_client(ctx)
+    # Tool logic proceeds only if provisioned
+    notes = await client.notes.list_notes(category=category)
+    return NotesListResponse(results=notes)
+```
+
+### 5. Capability Declaration
+
+Declare URL elicitation support during initialization:
+
+```python
+# nextcloud_mcp_server/app.py
+
+capabilities = {
+    "elicitation": {
+        "url": {}  # Declare URL mode support
+        # Note: We don't support "form" mode (in-band data collection)
+    },
+    # ... other capabilities
+}
+```
+
+### 6. Environment Variables
+
+**Primary control**:
+```bash
+# ENABLE_OFFLINE_ACCESS: Controls whether server requests refresh tokens and enables provisioning tools
+# Default: false (pass-through mode)
+# Set to true to enable offline access mode with Flow 2 provisioning
+ENABLE_OFFLINE_ACCESS=true
+```
+
+**Future variables** (when URL elicitation is implemented):
+```bash
+# ELICITATION_CALLBACK_URL: Base URL for OAuth callbacks with elicitation tracking
+# Default: NEXTCLOUD_MCP_SERVER_URL + /oauth/callback
+ELICITATION_CALLBACK_URL=http://localhost:8000/oauth/callback
+
+# ELICITATION_TIMEOUT_SECONDS: How long to wait for user to complete OAuth
+# Default: 300 (5 minutes)
+ELICITATION_TIMEOUT_SECONDS=300
+```
+
+**Removed variables**:
+```bash
+# ENABLE_PROGRESSIVE_CONSENT - Removed. Progressive consent is a mechanism, not a feature toggle.
+#                               Use ENABLE_OFFLINE_ACCESS to control whether provisioning tools are available.
+# MCP_SERVER_CLIENT_ID - merged into OIDC_CLIENT_ID
+```
+
+## User Experience Comparison
+
+### Before (ADR-004 Manual Tools)
+
+```
+User: "List my notes"
+Assistant: *calls nc_notes_list_notes*
+Server: Error - not provisioned
+Assistant: "You need to provision access first. Let me do that."
+Assistant: *calls provision_nextcloud_access*
+Server: {authorization_url: "https://..."}
+Assistant: "Please visit this URL: https://..."
+User: *copies URL, opens browser, completes OAuth*
+User: "OK, I'm done"
+Assistant: *calls nc_notes_list_notes again*
+Server: Success! [notes...]
+```
+
+**Issues**: 4 interactions, manual URL handling, no automation
+
+### After (ADR-006 Elicitation)
+
+```
+User: "List my notes"
+Assistant: *calls nc_notes_list_notes*
+Server: ElicitationRequired error
+Client: Shows dialog: "Grant access to Nextcloud? [Yes] [No]"
+User: *clicks Yes*
+Client: Opens OAuth URL in browser automatically
+User: *completes OAuth*
+Server: Sends progress notification "Complete!"
+Client: Auto-retries nc_notes_list_notes
+Server: Success! [notes...]
+Assistant: "Here are your notes: ..."
+```
+
+**Benefits**: 1 interaction, automatic URL opening, seamless retry
+
+## Migration Path
+
+### Phase 1: Add Elicitation Support (v0.26.0)
+
+- Implement `@require_provisioning` decorator
+- Add `elicitation/track` endpoint
+- Keep existing tools (`provision_nextcloud_access`) for compatibility
+- Update OAuth callback to track elicitations
+- Add capability declaration
+
+**Breaking changes**: None (additive)
+
+### Phase 2: Update Documentation (v0.27.0)
+
+- Document elicitation-based flow as primary
+- Mark manual tools as deprecated
+- Update examples and guides
+
+**Breaking changes**: None (documentation only)
+
+### Phase 3: Remove Manual Tools (v0.28.0)
+
+- Remove `provision_nextcloud_access` tool
+- Remove `check_provisioning_status` tool (status in error message)
+- Remove `revoke_nextcloud_access` (or keep for explicit revocation?)
+
+**Breaking changes**: Yes (removed tools)
+
+### Phase 4: Optimize (v0.29.0+)
+
+- Add elicitation result caching
+- Implement retry strategies
+- Add metrics and monitoring
+
+## Testing
+
+### Test Cases
+
+1. **First-Time User Flow**
+   ```python
+   @pytest.mark.oauth
+   async def test_elicitation_first_time_user(nc_mcp_oauth_client):
+       """Test that first tool call triggers elicitation."""
+       # User has no provisioning
+       with pytest.raises(McpError) as exc:
+           await nc_mcp_oauth_client.call_tool("nc_notes_list_notes")
+
+       # Should get ElicitationRequired error
+       assert exc.value.code == -32000
+       assert "elicitations" in exc.value.data
+       assert exc.value.data["elicitations"][0]["mode"] == "url"
+
+       # Verify URL is valid OAuth URL
+       url = exc.value.data["elicitations"][0]["url"]
+       assert "oauth" in url
+       assert "elicitationId" in url
+   ```
+
+2. **Progress Tracking**
+   ```python
+   @pytest.mark.oauth
+   async def test_elicitation_progress_tracking(nc_mcp_oauth_client):
+       """Test progress tracking during OAuth flow."""
+       # Trigger elicitation
+       elicitation_id = trigger_elicitation()
+
+       # Start tracking
+       track_task = asyncio.create_task(
+           nc_mcp_oauth_client.track_elicitation(
+               elicitation_id=elicitation_id,
+               progress_token="test-token"
+           )
+       )
+
+       # Simulate OAuth completion
+       await asyncio.sleep(1)
+       await complete_oauth_flow(elicitation_id)
+
+       # Track should complete
+       result = await track_task
+       assert result["status"] == "complete"
+   ```
+
+3. **Auto-Retry After Provisioning**
+   ```python
+   @pytest.mark.oauth
+   async def test_auto_retry_after_provisioning(nc_mcp_oauth_client):
+       """Test that client auto-retries after elicitation."""
+       # Mock client that auto-retries on ElicitationRequired
+       client = AutoRetryMcpClient(nc_mcp_oauth_client)
+
+       # First call triggers elicitation, client handles it, retries
+       result = await client.call_tool_with_elicitation("nc_notes_list_notes")
+
+       # Should succeed after provisioning
+       assert result.success
+       assert "notes" in result.data
+   ```
+
+4. **Timeout Handling**
+   ```python
+   @pytest.mark.oauth
+   async def test_elicitation_timeout(nc_mcp_oauth_client):
+       """Test timeout if user doesn't complete OAuth."""
+       elicitation_id = trigger_elicitation()
+
+       # Track with short timeout
+       with pytest.raises(McpError, match="timed out"):
+           await nc_mcp_oauth_client.track_elicitation(
+               elicitation_id=elicitation_id,
+               timeout=5  # 5 seconds
+           )
+   ```
+
+## Security Considerations
+
+### Out-of-Band OAuth Flow
+
+**Benefit**: OAuth credentials never pass through MCP client
+- User enters credentials directly on IdP page
+- MCP server receives only authorization code
+- Client never sees passwords or refresh tokens
+
+**Threat mitigation**:
+- **Credential theft**: Client can't intercept credentials (out-of-band)
+- **Token exposure**: Client never receives Nextcloud refresh tokens
+- **CSRF**: State parameter validates OAuth callback
+- **URL tampering**: Elicitation ID ties OAuth flow to user session
+
+### Elicitation ID as Security Token
+
+The `elicitationId` serves as a capability token:
+- Cryptographically random (UUID v4)
+- Single-use (invalidated after completion)
+- Time-limited (expires after timeout)
+- User-scoped (tied to user session)
+
+**Validation**:
+```python
+async def validate_elicitation_id(elicitation_id: str, user_id: str) -> bool:
+    """Validate that elicitation belongs to user and is still valid."""
+    elicitation = await storage.get_elicitation(elicitation_id)
+
+    if not elicitation:
+        return False
+
+    # Check ownership
+    if elicitation["user_id"] != user_id:
+        logger.warning(f"Elicitation ID mismatch: {elicitation_id}")
+        return False
+
+    # Check expiry
+    if elicitation["expires_at"] < datetime.now(timezone.utc):
+        return False
+
+    # Check not already used
+    if elicitation["status"] != "pending":
+        return False
+
+    return True
+```
+
+### Progress Tracking Security
+
+**Risk**: Progress token reuse across users
+
+**Mitigation**:
+- Progress tokens tied to elicitation ID
+- Elicitation ID tied to user session
+- Server validates ownership before sending updates
+
+## Consequences
+
+### Positive
+
+1. **Better UX**: Automatic URL opening, no manual copy/paste
+2. **Seamless Flow**: Auto-retry after provisioning
+3. **Progress Feedback**: User knows when OAuth is complete
+4. **Spec Compliance**: Implements SEP-1036 correctly
+5. **Secure by Design**: Out-of-band OAuth prevents credential exposure
+6. **Simpler API**: No explicit provisioning tools needed
+
+### Negative
+
+1. **Client Dependency**: Requires client support for URL elicitation
+2. **Complexity**: More moving parts (elicitation tracking, callbacks)
+3. **Polling**: Progress tracking uses polling (not ideal)
+4. **Breaking Change**: Removes manual provisioning tools (in v0.28.0)
+
+### Neutral
+
+1. **Storage Requirements**: Need to store elicitation state
+2. **Timeout Management**: Must handle long-running OAuth flows
+3. **Fallback Support**: Still need compatibility for older clients
+
+## Alternatives Considered
+
+### 1. Keep Manual Tools Only (Rejected)
+
+**Pros**: Simple, no client changes needed
+**Cons**: Poor UX, doesn't leverage SEP-1036
+
+**Rejection reason**: SEP-1036 provides better UX and security
+
+### 2. Form Mode Elicitation (Rejected)
+
+**Pros**: No browser redirect needed
+**Cons**: Would expose OAuth credentials to client (security violation)
+
+**Rejection reason**: Form mode only for non-sensitive data per SEP-1036
+
+### 3. Hybrid: Both Tools and Elicitation (Considered)
+
+**Pros**: Maximum compatibility, gradual migration
+**Cons**: API duplication, maintenance burden, confusing for users
+
+**Decision**: Support during migration (v0.26-0.27), remove in v0.28
+
+### 4. WebSocket for Progress (Rejected)
+
+**Pros**: Real-time updates instead of polling
+**Cons**: MCP spec uses polling pattern, adds complexity
+
+**Rejection reason**: Follow spec pattern (polling via elicitation/track)
+
+## Interim Implementation: Inline Form Elicitation (Pre-SEP-1036)
+
+**Note**: SEP-1036 (URL mode elicitation) is not yet available in the stable MCP Python SDK. As a temporary workaround, we've implemented a simplified version using the current **inline form elicitation** API.
+
+### What Changed
+
+Instead of waiting for URL mode elicitation, we implemented a `check_logged_in` tool that:
+
+1. Checks if the user has completed Flow 2 (resource provisioning)
+2. If logged in, returns `"yes"`
+3. If not logged in, uses **inline form elicitation** to prompt the user
+
+### Implementation Details
+
+**New Tool**: `check_logged_in`
+
+```python
+# nextcloud_mcp_server/server/oauth_tools.py
+
+class LoginConfirmation(BaseModel):
+    """Schema for login confirmation elicitation."""
+    acknowledged: bool = Field(
+        default=False,
+        description="Check this box after completing login at the provided URL",
+    )
+
+@mcp.tool(name="check_logged_in")
+@require_scopes("openid")
+async def tool_check_logged_in(ctx: Context, user_id: Optional[str] = None) -> str:
+    """Check if user is logged in and elicit login if needed."""
+    # Check if already logged in
+    status = await get_provisioning_status(ctx, user_id)
+    if status.is_provisioned:
+        return "yes"
+
+    # Generate OAuth URL for Flow 2
+    auth_url = generate_oauth_url_for_flow2(...)
+
+    # Use inline form elicitation (current MCP API)
+    result = await ctx.elicit(
+        message=f"Please log in to Nextcloud at the following URL:\n\n{auth_url}\n\nAfter completing the login, check the box below and click OK.",
+        schema=LoginConfirmation,
+    )
+
+    if result.action == "accept":
+        # Verify login succeeded
+        status = await get_provisioning_status(ctx, user_id)
+        return "yes" if status.is_provisioned else "Login not detected"
+    elif result.action == "decline":
+        return "Login declined by user."
+    else:
+        return "Login cancelled by user."
+```
+
+**OAuth Routes** (added to `app.py`):
+
+```python
+# Flow 2 routes for resource provisioning
+routes.append(
+    Route("/oauth/authorize-nextcloud", oauth_authorize_nextcloud, methods=["GET"])
+)
+routes.append(
+    Route("/oauth/callback-nextcloud", oauth_callback_nextcloud, methods=["GET"])
+)
+```
+
+### User Experience
+
+```
+User: *calls check_logged_in tool*
+
+MCP Client: Displays form elicitation
+┌─────────────────────────────────────────────────────────┐
+│ Please log in to Nextcloud at the following URL:      │
+│                                                         │
+│ http://localhost:8000/oauth/authorize-nextcloud?...    │
+│                                                         │
+│ After completing the login, check the box below and    │
+│ click OK.                                               │
+│                                                         │
+│ ☐ Check this box after completing login                │
+│                                                         │
+│ [Accept] [Decline] [Cancel]                            │
+└─────────────────────────────────────────────────────────┘
+
+User: *copies URL, opens in browser, completes OAuth*
+User: *checks box and clicks Accept*
+
+MCP Server: Verifies login and returns "yes"
+```
+
+### Limitations of Interim Approach
+
+1. **Manual URL Handling**: User must manually copy and paste the URL (not clickable)
+2. **No Automatic Browser Opening**: Client doesn't automatically open the URL
+3. **No Progress Tracking**: Can't track OAuth completion status in real-time
+4. **URL in Message Text**: Login URL embedded in plain text message (not as structured field)
+5. **Client-Side Confirmation**: Relies on user clicking "OK" after OAuth (honor system)
+
+### Why Not Use URL Mode Now?
+
+The current stable MCP Python SDK (`main` branch) only supports **inline form elicitation**:
+
+```python
+# Current API (no 'mode' parameter)
+class ElicitRequestParams(RequestParams):
+    message: str
+    requestedSchema: ElicitRequestedSchema
+    # No 'mode', 'url', or 'elicitationId' fields
+```
+
+URL mode elicitation (`mode: "url"`) is only available in the SEP-1036 branch, which has not been merged to `main` yet.
+
+### Migration to URL Mode (When SEP-1036 Lands)
+
+Once SEP-1036 is merged and available in the stable SDK, we will migrate to URL mode elicitation:
+
+**Before (Current Workaround)**:
+```python
+result = await ctx.elicit(
+    message=f"Please log in at: {auth_url}\n\nClick OK after login.",
+    schema=LoginConfirmation,
+)
+```
+
+**After (URL Mode)**:
+```python
+result = await ctx.session.elicit_url(
+    message="Please log in to Nextcloud to authorize this MCP server.",
+    url=auth_url,
+    elicitation_id=elicitation_id,
+)
+```
+
+**Benefits of migration**:
+- Automatic URL opening (with user consent)
+- Clickable URLs in client UI
+- Progress tracking via `elicitation/track`
+- Better security (URL not in message text)
+- Auto-retry support
+
+### Testing
+
+Integration tests validate the current inline form elicitation:
+
+```python
+# tests/server/oauth/test_login_elicitation.py
+
+async def test_check_logged_in_already_authenticated(nc_mcp_oauth_client):
+    """Test immediate 'yes' for authenticated users."""
+    result = await nc_mcp_oauth_client.call_tool("check_logged_in", arguments={})
+    assert "yes" in result.content[0].text.lower()
+
+async def test_check_logged_in_url_format(nc_mcp_oauth_client):
+    """Test that login URL (when needed) contains correct OAuth parameters."""
+    result = await nc_mcp_oauth_client.call_tool("check_logged_in", arguments={})
+    response_text = result.content[0].text
+
+    # If URL present, validate OAuth parameters
+    if "http" in response_text:
+        assert "response_type=code" in response_text
+        assert "client_id=" in response_text
+        assert "redirect_uri=" in response_text
+        assert "openid" in response_text
+```
+
+### Future Work
+
+- **Monitor SEP-1036**: Watch for merge to MCP Python SDK `main` branch
+- **Implement URL Mode**: Once available, migrate `check_logged_in` to use `ctx.session.elicit_url()`
+- **Add Progress Tracking**: Implement `elicitation/track` endpoint for OAuth completion status
+- **Implement Error-Triggered Elicitation**: Use `@require_provisioning` decorator to return `ElicitationRequired` errors
+- **Remove Manual Workaround**: Deprecate inline form approach once URL mode is stable
+
+## References
+
+- [SEP-1036: URL Mode Elicitation](https://github.com/modelcontextprotocol/specification/pull/887)
+- [MCP Elicitation Specification](https://modelcontextprotocol.io/specification/draft/client/elicitation)
+- [ADR-004: Federated Authentication Architecture](./ADR-004-mcp-application-oauth.md)
+- [ADR-005: Token Audience Validation](./ADR-005-token-audience-validation.md)
+- [RFC 8252: OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252)
+
+## Implementation Checklist
+
+### Interim Implementation (Inline Form Elicitation)
+
+- [x] Create `check_logged_in` tool with inline form elicitation
+- [x] Register Flow 2 OAuth routes (`/oauth/authorize-nextcloud`, `/oauth/callback-nextcloud`)
+- [x] Write integration tests for login elicitation flow
+- [x] Update ADR-006 with interim implementation documentation
+- [x] Add `LoginConfirmation` schema for elicitation
+- [ ] Run tests to validate implementation
+
+### Future Work (URL Mode Elicitation - Post SEP-1036)
+
+- [ ] Implement `@require_provisioning` decorator with ElicitationRequired error
+- [ ] Add `elicitation/track` request handler
+- [ ] Update OAuth callback to mark elicitations complete
+- [ ] Add elicitation storage (ID, user, status, timestamps)
+- [ ] Update all Nextcloud tools with `@require_provisioning`
+- [ ] Add URL elicitation capability declaration
+- [ ] Write tests for progress tracking
+- [ ] Update documentation with URL mode examples
+- [ ] Add migration guide for manual tools → elicitation
+- [ ] Migrate `check_logged_in` from inline form to URL mode
+- [ ] Keep manual tools with deprecation warnings (v0.26-0.27)
+- [ ] Remove manual tools (v0.28.0)
+- [ ] Update CHANGELOG.md with migration timeline

docs/ADR-008-mcp-sampling-for-semantic-search.md

@@ -0,0 +1,647 @@
+# ADR-008: MCP Sampling for Multi-App Semantic Search with RAG
+
+**Status**: Proposed
+**Date**: 2025-01-11
+**Depends On**: ADR-007 (Background Vector Sync)
+
+## Context
+
+ADR-007 established a background synchronization architecture that maintains a vector database of Nextcloud content across multiple apps (notes, calendar, deck, files, contacts), enabling semantic search via the `nc_semantic_search` tool. This tool returns a list of relevant documents with excerpts, similarity scores, and metadata—providing the raw materials for answering user questions.
+
+However, users typically don't want a list of documents—they want answers to their questions. When a user asks "What are my project goals?" or "When is my next dentist appointment?", they expect a natural language response that synthesizes information from multiple sources and document types, not a ranked list of excerpts. This is the pattern of Retrieval-Augmented Generation (RAG): retrieve relevant context from all Nextcloud apps, then generate a cohesive answer.
+
+The challenge is: who should generate the answer, and how?
+
+**Option 1: Server-side LLM**
+The MCP server could maintain its own LLM connection (OpenAI API, Ollama, etc.), construct prompts from retrieved documents, and return generated answers directly. This approach has significant drawbacks:
+
+- **Duplicate infrastructure**: MCP clients (like Claude Desktop) already have LLM capabilities. The server would duplicate this with its own LLM integration, API keys, and configuration.
+- **Cost and billing**: The server operator bears LLM costs for all users, creating billing and quota management challenges.
+- **Limited model choice**: Users are locked into whatever LLM the server configures. They cannot choose their preferred model or provider.
+- **Privacy concerns**: User queries and document contents flow through a server-controlled LLM, creating a potential privacy boundary.
+- **Configuration complexity**: Server operators must configure embedding services (for search) AND generation models (for answers), each with different API keys, rate limits, and failure modes.
+
+**Option 2: Return documents, let client generate**
+The server could simply return retrieved documents and rely on the MCP client's existing LLM to generate answers. The user would call `nc_notes_semantic_search`, receive documents, and then the client would include those documents in its context when responding to the user's original question. This approach also has limitations:
+
+- **Context window waste**: The client must include all document content in its context window, even if only small excerpts are relevant. For 5-10 documents, this can consume significant context space.
+- **Inconsistent behavior**: Whether the client synthesizes an answer or just displays documents depends on the client's implementation and the user's conversational style. There's no guaranteed answer generation.
+- **Poor citations**: The client may generate an answer but fail to cite which specific documents were used, making it hard to verify claims.
+- **User confusion**: Users see a tool that returns "search results" rather than "answers", requiring them to explicitly ask for synthesis.
+
+**Option 3: MCP Sampling**
+The Model Context Protocol specification includes a **sampling** capability that allows MCP servers to request LLM completions from their clients. The server constructs a prompt with retrieved context, sends it to the client via `sampling/createMessage`, and the client's LLM generates a response that the server can return as a tool result.
+
+This approach combines the best of both options:
+
+- **No server-side LLM**: The server has no API keys, no LLM configuration, no billing concerns.
+- **User choice**: The MCP client controls which LLM is used (Claude, GPT-4, local Ollama) and who pays for it.
+- **User transparency**: MCP clients SHOULD present sampling requests to users for approval, making it clear when the server is requesting an LLM call.
+- **Consistent citations**: The server constructs a prompt that explicitly includes document references, ensuring generated answers cite sources.
+- **Single tool call**: Users call one tool (`nc_notes_semantic_search_answer`) and receive a complete answer with citations—no multi-turn conversation needed.
+
+The sampling approach shifts responsibility appropriately: the MCP server is responsible for information retrieval and context construction (its expertise), while the MCP client is responsible for LLM access and user preferences (its expertise). This follows the MCP design philosophy of separating concerns between servers (data access) and clients (user interaction).
+
+However, sampling introduces new considerations:
+
+**Client compatibility**: Not all MCP clients implement sampling. The server must gracefully degrade when sampling is unavailable, falling back to returning documents without generated answers.
+
+**Latency**: Sampling adds a full round-trip to the client and back, plus LLM generation time. A typical flow involves: (1) client calls tool, (2) server retrieves documents, (3) server requests sampling from client, (4) client generates answer, (5) server returns answer to client. This can take 2-5 seconds depending on LLM speed, compared to 100-500ms for document retrieval alone.
+
+**User approval**: MCP clients SHOULD prompt users to approve sampling requests, allowing users to review the prompt before sending it to their LLM. This is a privacy and security feature (prevents servers from making arbitrary LLM requests) but adds interaction friction.
+
+**Prompt engineering**: The server must construct effective prompts that guide the LLM to generate useful, well-cited answers. Unlike Option 1 where the server controls the LLM directly, the server has less control over how the prompt is interpreted.
+
+Despite these considerations, MCP sampling provides the most principled solution for RAG-enhanced semantic search. It respects the client-server boundary, avoids duplicate infrastructure, and delivers the user experience users expect from semantic search tools.
+
+This ADR proposes adding a new tool, `nc_semantic_search_answer`, that uses MCP sampling to generate natural language answers from retrieved Nextcloud content across all indexed apps (notes, calendar, deck, files, contacts).
+
+## Decision
+
+We will implement a new MCP tool `nc_semantic_search_answer` that retrieves relevant documents via vector similarity search across all indexed Nextcloud apps and uses MCP sampling to generate natural language answers. The tool will construct a prompt that includes the user's original query and excerpts from retrieved documents (notes, calendar events, deck cards, files, contacts), request an LLM completion via `ctx.session.create_message()`, and return the generated answer along with source citations.
+
+The existing `nc_semantic_search` tool will remain unchanged, providing users with a choice: call the original tool for raw document results, or call the new sampling-enhanced tool for generated answers. This dual-tool approach respects different use cases—some users want to browse documents, others want direct answers.
+
+### API Design
+
+**Tool Signature**:
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search_answer(
+    query: str,
+    ctx: Context,
+    limit: int = 5,
+    score_threshold: float = 0.7,
+    max_answer_tokens: int = 500,
+) -> SamplingSearchResponse
+```
+
+**Parameters**:
+- `query`: The user's natural language question
+- `ctx`: MCP context for session access
+- `limit`: Maximum documents to retrieve (default 5)
+- `score_threshold`: Minimum similarity score 0-1 (default 0.7)
+- `max_answer_tokens`: Maximum tokens for generated answer (default 500)
+
+**Response Model**:
+```python
+class SamplingSearchResponse(BaseResponse):
+    query: str                              # Original user query
+    generated_answer: str                   # LLM-generated answer
+    sources: list[SemanticSearchResult]     # Supporting documents
+    total_found: int                        # Total matching documents
+    search_method: str = "semantic_sampling"
+    model_used: str | None = None           # Model that generated answer
+    stop_reason: str | None = None          # Why generation stopped
+```
+
+The response includes both the generated answer (for direct user consumption) and the source documents (for verification and citation). The `model_used` field records which LLM generated the answer, allowing users to understand which model provided the response.
+
+### Sampling API Usage
+
+The tool uses the MCP Python SDK's `ServerSession.create_message()` API:
+
+```python
+from mcp.types import SamplingMessage, TextContent, ModelPreferences, ModelHint
+
+# Construct prompt with retrieved context
+prompt = (
+    f"{query}\n\n"
+    f"Here are relevant documents from Nextcloud (notes, calendar events, deck cards, files, contacts):\n\n"
+    f"{context}\n\n"
+    f"Based on the documents above, please provide a comprehensive answer. "
+    f"Cite the document numbers when referencing specific information."
+)
+
+# Request LLM completion via MCP sampling
+sampling_result = await ctx.session.create_message(
+    messages=[
+        SamplingMessage(
+            role="user",
+            content=TextContent(type="text", text=prompt),
+        )
+    ],
+    max_tokens=max_answer_tokens,
+    temperature=0.7,
+    model_preferences=ModelPreferences(
+        hints=[ModelHint(name="claude-3-5-sonnet")],
+        intelligencePriority=0.8,
+        speedPriority=0.5,
+    ),
+    include_context="thisServer",
+)
+
+# Extract answer from response
+if sampling_result.content.type == "text":
+    generated_answer = sampling_result.content.text
+```
+
+**Key parameters**:
+- `messages`: Chat-style messages with role ("user" or "assistant") and content
+- `max_tokens`: Limits response length to control costs and latency
+- `temperature`: 0.7 balances creativity with consistency for factual answers
+- `model_preferences`: Hints suggest Claude Sonnet for balanced intelligence/speed
+- `include_context`: "thisServer" includes MCP server context in client's LLM call
+
+The `include_context` parameter is particularly important. When set to "thisServer", the MCP client provides its LLM with context about the server's capabilities, tools, and resources. This allows the LLM to reference the Nextcloud MCP server when generating answers, creating more contextually appropriate responses. For example, the LLM might say "Based on your Nextcloud Notes..." rather than generic phrasing.
+
+### Prompt Construction
+
+The prompt construction follows a structured template:
+
+```
+[User's original query]
+
+Here are relevant documents from Nextcloud (notes, calendar events, deck cards, files, contacts):
+
+[Document 1]
+Type: note
+Title: Project Kickoff Notes
+Category: Work
+Excerpt: The primary goal for Q1 2025 is to improve semantic search...
+Relevance Score: 0.92
+
+[Document 2]
+Type: calendar_event
+Title: Team Planning Meeting
+Location: Conference Room A
+Excerpt: Scheduled for Jan 15 at 2pm. Agenda: Discuss Q1 objectives and timeline...
+Relevance Score: 0.88
+
+[Document 3]
+Type: deck_card
+Title: Implement semantic search
+Labels: feature, high-priority
+Excerpt: This card tracks the semantic search implementation. Due: Jan 30...
+Relevance Score: 0.85
+
+Based on the documents above, please provide a comprehensive answer.
+Cite the document numbers when referencing specific information.
+```
+
+This structure ensures:
+- The user's original query is preserved verbatim
+- Documents are clearly delineated and numbered for citation
+- Metadata (title, category, score) provides context
+- Explicit instruction to cite sources encourages proper attribution
+
+The prompt is intentionally simple and fixed (not configurable). Allowing users to customize the prompt would complicate the API and introduce prompt injection risks. The fixed structure ensures consistent, well-cited answers across all users.
+
+### Fallback Behavior
+
+Sampling may fail for several reasons:
+- Client doesn't support sampling (e.g., MCP Inspector without callbacks)
+- User declines the sampling request
+- Network errors during sampling round-trip
+- LLM generation errors
+
+The tool handles all failures gracefully by falling back to returning documents without a generated answer:
+
+```python
+try:
+    sampling_result = await ctx.session.create_message(...)
+    generated_answer = sampling_result.content.text
+except Exception as e:
+    logger.warning(f"Sampling failed: {e}, returning search results only")
+    generated_answer = (
+        f"[Sampling unavailable: {str(e)}]\n\n"
+        f"Found {total_found} relevant documents. Please review the sources below."
+    )
+```
+
+This ensures the tool always returns useful information—either a generated answer or the underlying documents—rather than failing completely. The user knows sampling was attempted (via the `[Sampling unavailable]` prefix) and can still access the retrieved context.
+
+### No Results Handling
+
+When semantic search finds no relevant documents (all below `score_threshold`), the tool returns a clear message without attempting sampling:
+
+```python
+if not search_response.results:
+    return SamplingSearchResponse(
+        query=query,
+        generated_answer="No relevant documents found in your Nextcloud content for this query.",
+        sources=[],
+        total_found=0,
+        search_method="semantic_sampling",
+        success=True,
+    )
+```
+
+This avoids wasting a sampling call (and user approval) when there's no content to base an answer on.
+
+### User Experience Flow
+
+**Typical successful flow**:
+1. User calls `nc_semantic_search_answer` with query "What are my Q1 2025 objectives?"
+2. Server retrieves 5 relevant documents via vector search (2 notes, 2 calendar events, 1 deck card)
+3. Server constructs prompt with document excerpts showing mixed content types
+4. Server sends `sampling/createMessage` request to client
+5. Client prompts user: "MCP server wants to generate an answer using these documents. Allow?"
+6. User approves (or client auto-approves based on configuration)
+7. Client sends prompt to LLM (Claude, GPT-4, etc.)
+8. LLM generates answer with citations: "Based on Document 1 (note: Project Kickoff), Document 2 (calendar: Team Planning Meeting), and Document 3 (deck card: Implement semantic search)..."
+9. Client returns answer to server
+10. Server returns `SamplingSearchResponse` with answer and sources
+11. User sees complete answer with citations across multiple Nextcloud apps
+
+**Fallback flow** (sampling unavailable):
+1-3. Same as above
+4. Server attempts `ctx.session.create_message()`
+5. Client raises exception: "Sampling not supported"
+6. Server catches exception, logs warning
+7. Server returns `SamplingSearchResponse` with documents and "[Sampling unavailable]" message
+8. User sees raw documents instead of generated answer
+
+**No results flow**:
+1-2. Same as above but no documents match threshold
+3. Server returns `SamplingSearchResponse` with "No relevant documents" message
+4. No sampling attempted (no prompt sent)
+5. User sees clear "not found" message
+
+This three-tier approach (answer → documents → error message) ensures users always receive useful feedback appropriate to the situation.
+
+## Implementation
+
+### Response Model
+
+Add to `nextcloud_mcp_server/models/semantic.py` (new file for semantic search models):
+
+```python
+from pydantic import Field
+
+class SamplingSearchResponse(BaseResponse):
+    """Response from semantic search with LLM-generated answer via MCP sampling.
+
+    This response includes both a generated natural language answer (created by
+    the MCP client's LLM via sampling) and the source documents used to generate
+    that answer. Users can read the answer for quick information and review
+    sources for verification and deeper exploration.
+
+    Attributes:
+        query: The original user query
+        generated_answer: Natural language answer generated by client's LLM
+        sources: List of semantic search results used as context
+        total_found: Total number of matching documents found
+        search_method: Always "semantic_sampling" for this response type
+        model_used: Name of model that generated the answer (e.g., "claude-3-5-sonnet")
+        stop_reason: Why generation stopped ("endTurn", "maxTokens", etc.)
+    """
+
+    query: str = Field(..., description="Original user query")
+    generated_answer: str = Field(
+        ...,
+        description="LLM-generated answer based on retrieved documents"
+    )
+    sources: list[SemanticSearchResult] = Field(
+        default_factory=list,
+        description="Source documents with excerpts and relevance scores"
+    )
+    total_found: int = Field(..., description="Total matching documents")
+    search_method: str = Field(
+        default="semantic_sampling",
+        description="Search method used"
+    )
+    model_used: str | None = Field(
+        default=None,
+        description="Model that generated the answer"
+    )
+    stop_reason: str | None = Field(
+        default=None,
+        description="Reason generation stopped"
+    )
+```
+
+### Tool Implementation
+
+Add to `nextcloud_mcp_server/server/semantic.py` (new file for semantic search tools):
+
+```python
+import logging
+from mcp.types import ModelHint, ModelPreferences, SamplingMessage, TextContent
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search_answer(
+    query: str,
+    ctx: Context,
+    limit: int = 5,
+    score_threshold: float = 0.7,
+    max_answer_tokens: int = 500,
+) -> SamplingSearchResponse:
+    """
+    Semantic search with LLM-generated answer using MCP sampling.
+
+    Retrieves relevant documents from Nextcloud across all indexed apps (notes,
+    calendar, deck, files, contacts) using vector similarity search, then uses
+    MCP sampling to request the client's LLM to generate a natural language
+    answer based on the retrieved context.
+
+    This tool combines the power of semantic search (finding relevant content
+    across all your Nextcloud apps) with LLM generation (synthesizing that
+    content into coherent answers). The generated answer includes citations
+    to specific documents with their types, allowing users to verify claims
+    and explore sources.
+
+    The LLM generation happens client-side via MCP sampling. The MCP client
+    controls which model is used, who pays for it, and whether to prompt the
+    user for approval. This keeps the server simple (no LLM API keys needed)
+    while giving users full control over their LLM interactions.
+
+    Args:
+        query: Natural language question to answer (e.g., "What are my Q1 objectives?" or "When is my next dentist appointment?")
+        ctx: MCP context for session access
+        limit: Maximum number of documents to retrieve (default: 5)
+        score_threshold: Minimum similarity score 0-1 (default: 0.7)
+        max_answer_tokens: Maximum tokens for generated answer (default: 500)
+
+    Returns:
+        SamplingSearchResponse containing:
+        - generated_answer: Natural language answer with citations
+        - sources: List of documents with excerpts and relevance scores
+        - model_used: Which model generated the answer
+        - stop_reason: Why generation stopped
+
+    Note: Requires MCP client to support sampling. If sampling is unavailable,
+    the tool gracefully degrades to returning documents with an explanation.
+    The client may prompt the user to approve the sampling request.
+
+    Examples:
+        >>> # Query about objectives across multiple apps
+        >>> result = await nc_semantic_search_answer(
+        ...     query="What are my Q1 2025 project goals?",
+        ...     ctx=ctx
+        ... )
+        >>> print(result.generated_answer)
+        "Based on Document 1 (note: Project Kickoff), Document 2 (calendar event:
+        Q1 Planning Meeting), and Document 3 (deck card: Implement semantic search),
+        your main goals are: 1) Improve semantic search accuracy by 20%,
+        2) Deploy new embedding model, 3) Reduce indexing latency..."
+
+        >>> # Query about appointments
+        >>> result = await nc_semantic_search_answer(
+        ...     query="When is my next dentist appointment?",
+        ...     ctx=ctx,
+        ...     limit=10
+        ... )
+        >>> len(result.sources)  # Calendar events and related notes
+        3
+    """
+    # 1. Retrieve relevant documents via existing semantic search
+    search_response = await nc_semantic_search(
+        query=query,
+        ctx=ctx,
+        limit=limit,
+        score_threshold=score_threshold,
+    )
+
+    # 2. Handle no results case - don't waste a sampling call
+    if not search_response.results:
+        logger.debug(f"No documents found for query: {query}")
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer="No relevant documents found in your Nextcloud content for this query.",
+            sources=[],
+            total_found=0,
+            search_method="semantic_sampling",
+            success=True,
+        )
+
+    # 3. Construct context from retrieved documents
+    context_parts = []
+    for idx, result in enumerate(search_response.results, 1):
+        context_parts.append(
+            f"[Document {idx}]\n"
+            f"Title: {result.title}\n"
+            f"Category: {result.category}\n"
+            f"Excerpt: {result.excerpt}\n"
+            f"Relevance Score: {result.score:.2f}\n"
+        )
+
+    context = "\n".join(context_parts)
+
+    # 4. Construct prompt - reuse user's query, add context and instructions
+    prompt = (
+        f"{query}\n\n"
+        f"Here are relevant documents from Nextcloud (notes, calendar events, deck cards, files, contacts):\n\n"
+        f"{context}\n\n"
+        f"Based on the documents above, please provide a comprehensive answer. "
+        f"Cite the document numbers when referencing specific information."
+    )
+
+    logger.debug(
+        f"Requesting sampling for query: {query} "
+        f"({len(search_response.results)} documents retrieved)"
+    )
+
+    # 5. Request LLM completion via MCP sampling
+    try:
+        sampling_result = await ctx.session.create_message(
+            messages=[
+                SamplingMessage(
+                    role="user",
+                    content=TextContent(type="text", text=prompt),
+                )
+            ],
+            max_tokens=max_answer_tokens,
+            temperature=0.7,
+            model_preferences=ModelPreferences(
+                hints=[ModelHint(name="claude-3-5-sonnet")],
+                intelligencePriority=0.8,
+                speedPriority=0.5,
+            ),
+            include_context="thisServer",
+        )
+
+        # 6. Extract answer from sampling response
+        if sampling_result.content.type == "text":
+            generated_answer = sampling_result.content.text
+        else:
+            # Handle non-text responses (shouldn't happen for text prompts)
+            generated_answer = (
+                f"Received non-text response of type: {sampling_result.content.type}"
+            )
+            logger.warning(
+                f"Unexpected content type from sampling: {sampling_result.content.type}"
+            )
+
+        logger.info(
+            f"Sampling successful: model={sampling_result.model}, "
+            f"stop_reason={sampling_result.stopReason}"
+        )
+
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=generated_answer,
+            sources=search_response.results,
+            total_found=search_response.total_found,
+            search_method="semantic_sampling",
+            model_used=sampling_result.model,
+            stop_reason=sampling_result.stopReason,
+            success=True,
+        )
+
+    except Exception as e:
+        # Fallback: Return documents without generated answer
+        logger.warning(
+            f"Sampling failed ({type(e).__name__}: {e}), "
+            f"returning search results only"
+        )
+
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=(
+                f"[Sampling unavailable: {str(e)}]\n\n"
+                f"Found {search_response.total_found} relevant documents. "
+                f"Please review the sources below."
+            ),
+            sources=search_response.results,
+            total_found=search_response.total_found,
+            search_method="semantic_sampling_fallback",
+            success=True,
+        )
+```
+
+### Import Updates
+
+Add to top of `nextcloud_mcp_server/server/semantic.py`:
+
+```python
+from mcp.types import ModelHint, ModelPreferences, SamplingMessage, TextContent
+```
+
+Add to `nextcloud_mcp_server/models/semantic.py` exports:
+
+```python
+__all__ = [
+    "SemanticSearchResult",
+    "SemanticSearchResponse",
+    "SamplingSearchResponse",
+]
+```
+
+## Consequences
+
+### Benefits
+
+**Improved User Experience**: Users receive direct answers to questions rather than lists of documents, matching expectations from modern AI interfaces.
+
+**Proper Attribution**: Generated answers include citations to source documents, allowing users to verify claims and explore deeper.
+
+**No Server-Side LLM**: The server has no LLM dependencies, API keys, or billing concerns. All LLM interactions happen client-side.
+
+**User Control**: MCP clients control which model is used and may prompt users to approve sampling requests, maintaining transparency and user agency.
+
+**Graceful Degradation**: The tool works even when sampling is unavailable, falling back to returning documents. Existing clients continue working without changes.
+
+**Consistent Architecture**: Follows MCP's client-server separation: servers provide data access, clients provide user interaction and LLM capabilities.
+
+### Limitations
+
+**Sampling Support Required**: Not all MCP clients implement sampling. Users with basic clients see fallback behavior (documents without answers).
+
+**Added Latency**: Sampling adds 2-5 seconds to tool execution due to client round-trip and LLM generation time. Users must wait longer for answers than for raw search results.
+
+**User Approval Friction**: MCP clients SHOULD prompt users to approve sampling requests. This adds an extra interaction step before answers are generated.
+
+**Limited Prompt Control**: The server cannot fully control how the client's LLM interprets the prompt. Different models may generate different quality answers.
+
+**No Caching**: Each query requires a new sampling call. The server doesn't cache generated answers (clients may cache if they choose).
+
+**Token Costs**: LLM generation consumes tokens from the user's or client's quota. Heavy users may incur costs or hit rate limits.
+
+### Performance Characteristics
+
+**Typical latency**:
+- Document retrieval (vector search): 100-300ms
+- Sampling round-trip (client communication): 50-200ms
+- LLM generation (client-side): 1-4 seconds
+- **Total**: 2-5 seconds end-to-end
+
+**Throughput**: Sampling is fully async. The server can handle multiple concurrent sampling requests (limited by MCP client's concurrency, not server capacity).
+
+**Resource usage**: Minimal server-side. No GPU, no LLM model loading, no large memory requirements. Sampling happens entirely client-side.
+
+### Security Considerations
+
+**Prompt Injection Risk**: If user queries contain adversarial text designed to manipulate LLM behavior, those queries are included verbatim in the sampling prompt. Mitigation: The structured prompt format and explicit instructions ("based on documents above") constrain LLM behavior.
+
+**Data Privacy**: User queries and document excerpts are sent to the client's LLM. For cloud LLMs (OpenAI, Anthropic), this means data leaves the server's control. Mitigation: MCP clients SHOULD present sampling requests to users for approval, making data flows transparent. Users choose their LLM provider.
+
+**Sampling Abuse**: A malicious server could spam sampling requests to drain user quotas. Mitigation: MCP clients control approval and can rate-limit or block sampling from misbehaving servers.
+
+## Alternatives Considered
+
+### Server-Side LLM Integration
+
+**Approach**: Configure the MCP server with OpenAI API key or local Ollama instance. Generate answers server-side.
+
+**Rejected Because**:
+- Duplicates LLM infrastructure that MCP clients already have
+- Creates billing and API key management burden for server operators
+- Locks users into server-configured models
+- Violates MCP's client-server separation principle
+
+### Multi-Turn Conversation Pattern
+
+**Approach**: `nc_notes_semantic_search` returns documents. User asks follow-up question. Client's LLM uses previous tool results as context.
+
+**Rejected Because**:
+- Requires users to know to ask follow-up questions
+- Consumes context window with full document content
+- Inconsistent behavior across clients
+- Poor citation (LLM may not reference which documents it used)
+
+### Pre-Generated Summaries
+
+**Approach**: Generate and cache summaries during indexing. Return summaries instead of excerpts.
+
+**Rejected Because**:
+- Summaries become stale as documents change
+- Summary quality depends on server-side LLM (same problems as server-side generation)
+- Summaries are generic, not tailored to specific queries
+
+### Streaming Responses
+
+**Approach**: Use MCP sampling with streaming to return incremental answer chunks.
+
+**Deferred Because**:
+- MCP sampling streaming support unclear in current specification
+- Adds significant implementation complexity
+- Tool responses in MCP are typically atomic
+- Can be added later without breaking changes
+
+## Related Decisions
+
+**ADR-007**: Background Vector Sync provides the semantic search infrastructure that this ADR enhances with LLM generation.
+
+**ADR-004**: Progressive Consent architecture applies to sampling—users consent to sampling requests via MCP client approval prompts.
+
+## References
+
+- [MCP Specification - Sampling](https://modelcontextprotocol.io/docs/specification/2025-06-18/client/sampling)
+- [MCP Python SDK - ServerSession.create_message](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/session.py#L215)
+- [MCP Python SDK - Sampling Example](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/sampling.py)
+- [MCP Types - SamplingMessage](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types.py#L1038)
+- [MCP Types - CreateMessageResult](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types.py#L1073)
+- [Retrieval-Augmented Generation (RAG) - Lewis et al. 2020](https://arxiv.org/abs/2005.11401)
+
+## Implementation Checklist
+
+- [ ] Create ADR-008 document (this file)
+- [ ] Create `nextcloud_mcp_server/models/semantic.py` for semantic search models
+- [ ] Add `SamplingSearchResponse` model to `nextcloud_mcp_server/models/semantic.py`
+- [ ] Create `nextcloud_mcp_server/server/semantic.py` for semantic search tools
+- [ ] Implement `nc_semantic_search_answer` tool in `nextcloud_mcp_server/server/semantic.py`
+- [ ] Add MCP sampling type imports (`SamplingMessage`, `TextContent`, etc.)
+- [ ] Write unit tests with mocked sampling (`tests/unit/server/test_semantic.py`)
+- [ ] Create integration tests (`tests/integration/test_sampling.py`)
+- [ ] Update `README.md` with new tool documentation in dedicated Semantic Search section
+- [ ] Update `CLAUDE.md` with sampling pattern guidance
+- [ ] Test with MCP client supporting sampling (Claude Desktop, MCP Inspector with callbacks)
+- [ ] Document client requirements and fallback behavior
+- [ ] Update oauth-architecture.md to add semantic:read scope
+- [ ] Create ADR-009 to document semantic:read scope decision

docs/ADR-009-semantic-search-oauth-scope.md

@@ -0,0 +1,268 @@
+# ADR-009: Generic `semantic:read` OAuth Scope for Multi-App Vector Search
+
+**Status**: Proposed
+**Date**: 2025-01-11
+**Depends On**: ADR-007 (Background Vector Sync), ADR-008 (MCP Sampling for Semantic Search)
+
+## Context
+
+ADR-007 established a background vector synchronization architecture that indexes content from multiple Nextcloud apps (notes, calendar events, deck cards, files, contacts) into a unified vector database. ADR-008 introduced semantic search tools (`nc_semantic_search`, `nc_semantic_search_answer`) that query this vector database and use MCP sampling to generate natural language answers.
+
+The question is: **What OAuth scopes should protect semantic search operations?**
+
+### Option 1: App-Specific Scopes
+
+Require users to have scopes for each app they want to search:
+
+```python
+@mcp.tool()
+@require_scopes("notes:read", "calendar:read", "deck:read", "files:read", "contacts:read")
+async def nc_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Search across all indexed apps"""
+```
+
+**Advantages**:
+- Granular control - users explicitly consent to searching each app
+- Aligns with app-specific authorization model
+- Clear security boundary - can only search apps you can access
+
+**Disadvantages**:
+- **Brittle user experience**: If a user grants only `notes:read` but the tool requires all 5 scopes, the tool becomes invisible/unusable
+- **All-or-nothing enforcement**: Can't search notes alone - must grant all scopes or none
+- **Poor progressive consent**: User can't start with notes search and later add calendar
+- **Scope inflation**: Every new app adds another required scope
+- **Mismatched semantics**: User thinks "I want to search my notes" but must grant calendar, deck, files, contacts just to make the tool appear
+
+### Option 2: Single Generic Scope (Chosen)
+
+Introduce a new semantic search-specific scope:
+
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Search across all indexed apps"""
+```
+
+**Advantages**:
+- **Simple authorization**: One scope grants semantic search capability
+- **Progressive enablement**: User grants `semantic:read`, searches notes initially, then enables calendar indexing later
+- **Logical grouping**: Semantic search is a cross-app feature, deserving its own scope
+- **Future-proof**: New apps can be added to vector sync without changing OAuth scopes
+- **Matches user mental model**: "I want semantic search" → grant `semantic:read` (not "I want semantic search" → grant 5 unrelated app scopes)
+
+**Considerations**:
+- User could search apps they can't directly access via app-specific tools
+  - **Mitigation**: Dual-phase authorization (Phase 1: scope check passes with `semantic:read`, Phase 2: verify user can access each returned document via app-specific permissions)
+- Less granular than app-specific scopes
+  - **Counterpoint**: Semantic search is inherently cross-app - forcing per-app authorization defeats its purpose
+
+### Option 3: Hybrid Approach (Rejected)
+
+Support both: semantic search works with either `semantic:read` OR all app-specific scopes:
+
+```python
+@mcp.tool()
+@require_scopes("semantic:read", alternative_scopes=["notes:read", "calendar:read", ...])
+async def nc_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Search across all indexed apps"""
+```
+
+**Rejected Because**:
+- Adds complexity to scope validation logic
+- Unclear to users which scopes they should grant
+- Alternative scopes still suffer from all-or-nothing problem
+- No significant benefit over Option 2 with dual-phase authorization
+
+## Decision
+
+We will introduce two new OAuth scopes specifically for semantic search operations:
+
+- **`semantic:read`**: Query vector database, perform semantic search, generate answers
+- **`semantic:write`**: Enable/disable background vector synchronization, manage indexing settings
+
+These scopes are **independent** of app-specific scopes (notes:read, calendar:read, etc.).
+
+### Tool Scope Assignments
+
+**Read Operations**:
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search(query: str, ctx: Context, limit: int = 10, score_threshold: float = 0.7) -> SemanticSearchResponse:
+    """Semantic search across all indexed Nextcloud apps"""
+
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search_answer(query: str, ctx: Context, limit: int = 5, max_answer_tokens: int = 500) -> SamplingSearchResponse:
+    """Semantic search with LLM-generated answer via MCP sampling"""
+
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_get_vector_sync_status(ctx: Context) -> VectorSyncStatusResponse:
+    """Get current vector synchronization status (indexed count, pending count, status)"""
+```
+
+**Write Operations**:
+```python
+@mcp.tool()
+@require_scopes("semantic:write")
+async def nc_enable_vector_sync(ctx: Context) -> VectorSyncResponse:
+    """Enable background vector synchronization for this user"""
+
+@mcp.tool()
+@require_scopes("semantic:write")
+async def nc_disable_vector_sync(ctx: Context) -> VectorSyncResponse:
+    """Disable background vector synchronization"""
+```
+
+### Dual-Phase Authorization
+
+To ensure users can only access documents they have permission to view, semantic search implements **dual-phase authorization**:
+
+**Phase 1: Scope Check** (MCP Server)
+- User must have `semantic:read` scope to call semantic search tools
+- This grants permission to query the vector database
+
+**Phase 2: Document Verification** (Per-Result Filtering)
+- For each returned document, verify user has access via app-specific permissions
+- Uses `DocumentVerifier` interface per app:
+  - Notes: Call `/apps/notes/api/v1/notes/{id}` - if 404/403, exclude from results
+  - Calendar: Call `/remote.php/dav/calendars/username/calendar/event.ics` - if 404/403, exclude
+  - Deck: Call `/apps/deck/api/v1.0/boards/{board_id}/stacks/{stack_id}/cards/{card_id}` - if 404/403, exclude
+  - Files: Call `/remote.php/dav/files/username/path` with PROPFIND - if 404/403, exclude
+  - Contacts: Call `/remote.php/dav/addressbooks/username/addressbook/contact.vcf` - if 404/403, exclude
+
+This two-phase approach ensures:
+1. Semantic search is a **distinct capability** (like "global search") requiring explicit consent
+2. Results are **filtered** to only include documents the user can access
+3. No privilege escalation - users can't discover content they shouldn't see
+
+**Implementation**: See ADR-007 Phase 3 (Document Verification) and `DocumentVerifier` interface.
+
+### Scope Discovery
+
+The new scopes will be:
+- **Advertised** via PRM endpoint (`/.well-known/oauth-protected-resource/mcp`)
+- **Dynamically discovered** from `@require_scopes` decorators on semantic search tools
+- **Documented** in OAuth architecture (oauth-architecture.md)
+- **Included** in default client registration scopes
+
+## Consequences
+
+### Benefits
+
+**User Experience**:
+- Simple authorization: one scope for semantic search capability
+- Progressive enablement: grant `semantic:read`, enable indexing for apps later
+- Natural mental model: "semantic search" is a distinct feature deserving its own scope
+
+**Security**:
+- Dual-phase authorization prevents privilege escalation
+- Users explicitly consent to cross-app search capability
+- Per-document verification ensures users only see accessible content
+
+**Maintainability**:
+- Adding new apps to vector sync doesn't require OAuth scope changes
+- Clear separation between app access (notes:read) and search capability (semantic:read)
+- Logical grouping of related operations (search, sync status, enable/disable)
+
+**Future-Proof**:
+- Can add new document types without breaking existing OAuth flows
+- Supports future semantic features (recommendations, clustering) under same scope
+- Aligns with potential future Nextcloud semantic capabilities
+
+### Trade-offs
+
+**Less Granular Than App-Specific Scopes**:
+- User can't grant "semantic search notes only"
+- Semantic search is all-or-nothing across enabled apps
+- **Mitigation**: Dual-phase verification ensures users only see documents they can access
+
+**New Scope to Learn**:
+- Users must understand `semantic:read` is distinct from app scopes
+- MCP clients must present scope clearly during consent
+- **Mitigation**: Clear scope descriptions in OAuth consent UI and documentation
+
+**Backend Complexity**:
+- Requires dual-phase authorization implementation
+- DocumentVerifier interface needed for each app
+- **Benefit**: Enforces proper security regardless of scope model
+
+### Migration Impact
+
+**Breaking Change**: Existing deployments using notes-specific semantic search will break.
+
+**Before (OLD - Breaking)**:
+```python
+@mcp.tool()
+@require_scopes("notes:read")
+async def nc_notes_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Semantic search notes"""
+```
+
+**After (NEW)**:
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Semantic search across all apps"""
+```
+
+**Migration Path**:
+1. Deploy server with new `semantic:read` scope
+2. Users re-authenticate, granting `semantic:read` scope
+3. Semantic search tools become visible/usable again
+4. **No data loss**: Vector database and indexed documents remain unchanged
+
+**Backward Compatibility**: None. This is an intentional breaking change to correct the scope model before broader adoption.
+
+## Alternatives Considered
+
+### Keep Notes-Specific Scopes
+
+**Approach**: Continue using `notes:read` for semantic search, even when searching other apps.
+
+**Rejected Because**:
+- Semantically incorrect - searching calendar events is not "reading notes"
+- Confuses users - why does searching calendar require notes:read?
+- Doesn't scale - what scope for multi-app search?
+
+### Create Per-App Semantic Scopes
+
+**Approach**: Introduce `notes:semantic`, `calendar:semantic`, `deck:semantic`, etc.
+
+**Rejected Because**:
+- Scope proliferation - doubles the number of scopes
+- Defeats purpose of unified vector search
+- Users would need to grant 5+ scopes for cross-app search
+- No clear benefit over dual-phase authorization with `semantic:read`
+
+### Require All App Scopes (Already Rejected in Option 1)
+
+**Approach**: Require `notes:read AND calendar:read AND deck:read AND files:read AND contacts:read`
+
+**Rejected Because**: Unusable UX (see Option 1 disadvantages above)
+
+## Related Decisions
+
+**ADR-007**: Background Vector Sync provides the indexing architecture that semantic scopes protect. The DocumentVerifier interface from ADR-007 Phase 3 implements dual-phase authorization.
+
+**ADR-008**: MCP Sampling for semantic search uses `semantic:read` to protect the sampling-enhanced search tool.
+
+**ADR-004**: Progressive Consent architecture supports users granting `semantic:read` initially, then enabling per-app indexing via `semantic:write` (enable_vector_sync with app selection).
+
+## Implementation Checklist
+
+- [ ] Create ADR-009 document (this file)
+- [ ] Update `oauth-architecture.md` to document `semantic:read` and `semantic:write` scopes ✅
+- [ ] Update `README.md` to show Semantic Search as separate tool category ✅
+- [ ] Update ADR-007 to reference `semantic:*` scopes instead of `sync:*` ✅
+- [ ] Update ADR-008 to use `semantic:read` instead of `notes:read` ✅
+- [ ] Implement DocumentVerifier interface for all apps (notes, calendar, deck, files, contacts)
+- [ ] Update semantic search tools to use `@require_scopes("semantic:read")`
+- [ ] Update vector sync tools to use `@require_scopes("semantic:write")`
+- [ ] Add dual-phase authorization to semantic search implementation
+- [ ] Test OAuth flow with `semantic:read` scope
+- [ ] Update scope discovery in PRM endpoint
+- [ ] Document migration path for existing deployments

docs/ADR-010-webhook-based-vector-sync.md

@@ -0,0 +1,661 @@
+# ADR-010: Webhook-Based Vector Database Synchronization
+
+**Status**: Proposed
+**Date**: 2025-01-10
+**Depends On**: ADR-007 (Background Vector Sync)
+
+## Context
+
+ADR-007 established a background synchronization architecture for maintaining the vector database using periodic polling. The scanner task runs on a configurable interval (default 3600 seconds / 1 hour) to detect changed documents across Nextcloud apps. While this polling approach is simple and reliable, it introduces significant latency between content changes and vector database updates.
+
+### Current Polling Architecture
+
+The existing scanner implementation in `nextcloud_mcp_server/vector/scanner.py` operates as follows:
+
+1. **Periodic Scanning**: The scanner task sleeps for `vector_sync_scan_interval` seconds between runs
+2. **Change Detection**: For each scan, it:
+   - Fetches all documents from Nextcloud (notes, calendar events, etc.)
+   - Queries Qdrant for the last indexed timestamp of each document
+   - Compares modification timestamps to detect changes
+   - Queues changed documents for processing
+3. **Document Processing**: Processor tasks pull from the queue, generate embeddings, and update Qdrant
+
+This architecture works but has fundamental limitations:
+
+**Latency**: With a 1-hour scan interval, content changes can take up to 1 hour to appear in semantic search results. For time-sensitive use cases (e.g., "What's on my calendar today?"), this delay is problematic.
+
+**API Load**: Every scan fetches *all* documents for *all* enabled users, regardless of whether anything changed. For large deployments with thousands of documents, this generates significant unnecessary API traffic to Nextcloud.
+
+**Resource Waste**: The scanner and processors consume compute resources even when no content has changed. During periods of low activity, the system performs wasteful polling.
+
+**Scalability**: As the number of users and documents grows, the time required to complete a full scan increases. Eventually, the scan duration may exceed the scan interval, causing scans to run continuously without idle periods.
+
+**Rate Limiting**: Fetching all documents for all users in rapid succession can trigger Nextcloud's rate limiting, especially on shared hosting environments with restrictive API quotas.
+
+These limitations are inherent to any polling-based architecture. Reducing the scan interval (e.g., to 5 minutes) reduces latency but exacerbates API load, resource waste, and rate limiting issues. The fundamental problem is that the system has no way to know *when* content changes occur—it must repeatedly check to find out.
+
+### Nextcloud Webhook Listeners
+
+Nextcloud provides a webhook_listeners app (bundled with Nextcloud 30+) that enables push-based change notifications. Instead of polling for changes, external services can register webhook endpoints and receive HTTP POST requests when specific events occur. Administrators register these webhooks using Nextcloud's OCS API or occ commands.
+
+The webhook_listeners app supports events for all Nextcloud apps relevant to this MCP server's vector database:
+
+**Files/Notes Events** (notes are stored as files):
+- `OCP\Files\Events\Node\NodeCreatedEvent`
+- `OCP\Files\Events\Node\NodeWrittenEvent`
+- `OCP\Files\Events\Node\BeforeNodeDeletedEvent` ⭐ **Use this for deletion (includes node.id)**
+- `OCP\Files\Events\Node\NodeDeletedEvent` (missing node.id - file already deleted)
+- `OCP\Files\Events\Node\NodeRenamedEvent`
+- `OCP\Files\Events\Node\NodeCopiedEvent`
+
+**Calendar Events**:
+- `OCP\Calendar\Events\CalendarObjectCreatedEvent`
+- `OCP\Calendar\Events\CalendarObjectUpdatedEvent`
+- `OCP\Calendar\Events\CalendarObjectDeletedEvent`
+- `OCP\Calendar\Events\CalendarObjectMovedEvent`
+
+**Tables Events**:
+- `OCA\Tables\Event\RowAddedEvent`
+- `OCA\Tables\Event\RowUpdatedEvent`
+- `OCA\Tables\Event\RowDeletedEvent`
+
+**Deck Events** (via file events since cards are stored as files in some configurations)
+
+Each webhook notification includes rich metadata:
+- User ID who triggered the event
+- Timestamp of the event
+- Document ID and metadata
+- Operation type (create, update, delete)
+- Path information (for files)
+
+Webhook notifications are dispatched via background jobs, with configurable delivery guarantees. Administrators can set up dedicated webhook worker processes to achieve near-real-time delivery (within seconds of the triggering event).
+
+### Why Not Replace Polling Entirely?
+
+While webhooks provide superior latency and efficiency, they cannot fully replace polling:
+
+**Missed Events**: If the MCP server is down when a webhook fires, the notification is lost. Nextcloud's background job system processes webhooks asynchronously, but does not queue failed deliveries indefinitely.
+
+**Administrator Setup**: Webhooks must be registered by Nextcloud administrators using the OCS API or occ commands. This is an optional optimization that administrators can enable when they want to reduce polling frequency.
+
+**Filter Configuration**: Webhook filters must be carefully configured to avoid notification floods. A poorly configured filter could send thousands of notifications for bulk operations (e.g., importing a calendar with hundreds of events).
+
+**Graceful Degradation**: In environments where webhooks are not configured, the system continues using polling without any degradation in functionality.
+
+**Deletion Detection**: Nextcloud's webhook system does not guarantee delivery of deletion events if the user's account is removed or the app is uninstalled. Periodic polling provides a safety mechanism to detect orphaned documents.
+
+A complementary architecture where webhooks supplement (but don't replace) polling provides low-latency updates when configured, with polling ensuring reliability.
+
+### Design Considerations
+
+**Push vs Pull Trade-offs**:
+Webhooks introduce new failure modes (network issues, endpoint unavailability, notification floods) that polling avoids. The webhook endpoint must handle failures gracefully without blocking semantic search functionality.
+
+**Webhook Endpoint Security**:
+The MCP server exposes an HTTP endpoint to receive webhooks. Authentication is optional—in production deployments, administrators can configure Nextcloud to send an `Authorization` header that the MCP server validates. For local development, authentication can be disabled for simplicity.
+
+**Idempotency**:
+The system may receive duplicate notifications (webhook + next scan) or out-of-order notifications (update fires before create completes). Document processing must be idempotent—processing the same document multiple times produces the same result.
+
+**Asynchronous Processing**:
+Nextcloud processes webhooks via background jobs, introducing delivery latency (typically seconds to minutes depending on background job configuration). This affects testing strategies—integration tests cannot rely on immediate webhook delivery.
+
+**Deployment Patterns**:
+The MCP server webhook endpoint is accessible at the same host/port as the MCP server itself. Administrators configure Nextcloud to POST to `https://<mcp-server-host>:<port>/webhooks/nextcloud` when registering webhook listeners.
+
+## Decision
+
+We will add a webhook endpoint to the MCP server that receives change notifications from Nextcloud and queues documents for vector database processing. This complements the existing polling architecture from ADR-007 without replacing it—webhooks provide low-latency updates when configured, while polling ensures reliability regardless of webhook availability.
+
+The architecture is intentionally simple: the webhook endpoint is just another producer of `DocumentTask` objects that feed into the existing processor queue. The scanner task, processor pool, and queue management remain unchanged from ADR-007.
+
+### Architecture Components
+
+**1. Webhook Endpoint**
+
+A new Starlette HTTP route will be added to receive webhook notifications from Nextcloud:
+
+```python
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+@app.route("/webhooks/nextcloud", methods=["POST"])
+async def handle_nextcloud_webhook(request: Request) -> JSONResponse:
+    """
+    Receive webhook notifications from Nextcloud.
+
+    Parses event payload, extracts document metadata, and queues
+    changed documents for processing using the same queue as the scanner.
+    """
+    # 1. Optional authentication validation
+    if settings.webhook_secret:
+        auth_header = request.headers.get("authorization", "")
+        if not auth_header.startswith("Bearer ") or \
+           auth_header[7:] != settings.webhook_secret:
+            logger.warning("Webhook authentication failed")
+            return JSONResponse(
+                {"status": "error", "message": "Unauthorized"},
+                status_code=401
+            )
+
+    # 2. Parse webhook payload
+    payload = await request.json()
+    event_class = payload["event"]["class"]
+    user_id = payload["user"]["uid"]
+
+    # 3. Extract document metadata from event
+    doc_task = extract_document_task(event_class, payload)
+    if not doc_task:
+        return JSONResponse({"status": "ignored", "reason": "unsupported event"})
+
+    # 4. Send to processor queue (same queue as scanner)
+    try:
+        await webhook_send_stream.send(doc_task)
+        logger.info(f"Queued document from webhook: {doc_task}")
+        return JSONResponse({"status": "queued"})
+    except Exception as e:
+        logger.error(f"Failed to queue webhook document: {e}")
+        return JSONResponse(
+            {"status": "error", "message": str(e)},
+            status_code=500
+        )
+```
+
+The endpoint:
+- Validates optional authentication via `Authorization: Bearer <secret>` header
+- Parses various event types (calendar, files, tables) into `DocumentTask` objects
+- Sends to the same processing queue that the scanner uses
+- Returns quickly (<50ms) to avoid blocking Nextcloud's webhook workers
+- Handles errors gracefully (invalid payload, queue full, etc.)
+
+**2. Webhook Registration Helper (Development Only)**
+
+For development and testing purposes, a helper method will be added to `NextcloudClient` for registering webhooks via the OCS API. This is NOT exposed as an MCP tool—administrators register webhooks manually using Nextcloud's admin interface or the OCS API directly.
+
+```python
+class NextcloudClient:
+    async def register_webhook(
+        self,
+        event_type: str,
+        uri: str,
+        http_method: str = "POST",
+        auth_method: str = "none",
+        headers: dict[str, str] | None = None,
+    ) -> dict:
+        """
+        Register a webhook with Nextcloud (requires admin credentials).
+
+        Used for development/testing. Production admins should register
+        webhooks using Nextcloud's admin UI or occ commands.
+        """
+        # Implementation uses OCS API: POST /ocs/v2.php/apps/webhook_listeners/api/v1/webhooks
+        ...
+```
+
+This keeps webhook registration out of the MCP tool surface while providing a convenient API for integration tests.
+
+**3. Event Parsing**
+
+A helper function extracts `DocumentTask` from various Nextcloud event types:
+
+```python
+def extract_document_task(event_class: str, payload: dict) -> DocumentTask | None:
+    """Extract DocumentTask from webhook event payload."""
+    user_id = payload["user"]["uid"]
+    event_data = payload["event"]
+
+    # File/Note events
+    if "NodeCreatedEvent" in event_class or "NodeWrittenEvent" in event_class:
+        # Only process markdown files (notes)
+        path = event_data["node"]["path"]
+        if not path.endswith(".md"):
+            return None
+        return DocumentTask(
+            user_id=user_id,
+            doc_id=event_data["node"]["id"],
+            doc_type="note",
+            operation="index",
+            modified_at=payload["time"],
+        )
+
+    # Calendar events
+    elif "CalendarObjectCreatedEvent" in event_class or \
+         "CalendarObjectUpdatedEvent" in event_class:
+        return DocumentTask(
+            user_id=user_id,
+            doc_id=str(event_data["objectData"]["id"]),
+            doc_type="calendar_event",
+            operation="index",
+            modified_at=event_data["objectData"]["lastmodified"],
+        )
+
+    # Deletion events (use BeforeNodeDeletedEvent for files to get node.id)
+    elif "BeforeNodeDeletedEvent" in event_class or \
+         "NodeDeletedEvent" in event_class or \
+         "CalendarObjectDeletedEvent" in event_class:
+        # Similar logic for delete operations
+        ...
+
+    return None  # Unsupported event type
+```
+
+**4. No Changes to Scanner or Processors**
+
+The existing scanner task from ADR-007 continues operating unchanged. It polls Nextcloud on its configured interval (`VECTOR_SYNC_SCAN_INTERVAL`), discovers changed documents, and queues them for processing. The scanner is unaware of webhooks—it simply adds `DocumentTask` objects to the queue.
+
+Similarly, the processor pool continues pulling `DocumentTask` objects from the queue, generating embeddings, and updating Qdrant. Processors don't know or care whether a task came from the scanner or a webhook.
+
+This design keeps concerns separated: webhooks and scanner are independent producers, processors are independent consumers, and the queue mediates between them.
+
+### Configuration
+
+A new optional environment variable controls webhook authentication:
+
+```bash
+# Optional: Shared secret for webhook authentication
+# If set, webhooks must include "Authorization: Bearer <secret>" header
+# If unset, no authentication is required (useful for local development)
+WEBHOOK_SECRET=<generate-random-secret>
+```
+
+The webhook endpoint is automatically available at `/webhooks/nextcloud` when the MCP server starts. No feature flags or additional configuration needed—if Nextcloud sends webhooks to this endpoint, they will be processed.
+
+**Reducing Polling Frequency**: Administrators who configure webhooks may want to reduce polling frequency to minimize API load while maintaining safety reconciliation scans:
+
+```bash
+# Increase scan interval from 1 hour (default) to 24 hours
+VECTOR_SYNC_SCAN_INTERVAL=86400
+```
+
+This is a manual configuration decision, not automatic—the scanner doesn't adapt based on webhook availability.
+
+### Webhook Event Mapping
+
+The webhook handler maps Nextcloud events to document types:
+
+| Nextcloud Event | Document Type | Operation |
+|----------------|---------------|-----------|
+| `NodeCreatedEvent` (path: `*/files/*.md`) | `note` | `index` |
+| `NodeWrittenEvent` (path: `*/files/*.md`) | `note` | `index` |
+| `NodeDeletedEvent` (path: `*/files/*.md`) | `note` | `delete` |
+| `CalendarObjectCreatedEvent` | `calendar_event` | `index` |
+| `CalendarObjectUpdatedEvent` | `calendar_event` | `index` |
+| `CalendarObjectDeletedEvent` | `calendar_event` | `delete` |
+| `RowAddedEvent` | `table_row` | `index` |
+| `RowUpdatedEvent` | `table_row` | `index` |
+| `RowDeletedEvent` | `table_row` | `delete` |
+
+Path filters in webhook registration ensure only relevant files trigger notifications (e.g., exclude `.jpg`, `.mp4` for file events).
+
+### Administrator Setup
+
+Administrators who want to enable webhooks:
+
+1. **Enable webhook_listeners app** in Nextcloud: `occ app:enable webhook_listeners`
+2. **Register webhook endpoints** using Nextcloud's OCS API or admin UI:
+   - Endpoint: `https://<mcp-server-host>:<port>/webhooks/nextcloud`
+   - Events: File created/updated/deleted, Calendar object events, Table row events
+   - Filters: Exclude non-content files (images, videos), system directories
+   - Optional: Configure `Authorization: Bearer <WEBHOOK_SECRET>` header
+3. **Optionally reduce scanner frequency**: Set `VECTOR_SYNC_SCAN_INTERVAL=86400` (24 hours)
+4. **Set up webhook workers** (optional): Configure dedicated background job workers for low-latency delivery
+
+Existing deployments continue using polling without any changes. Webhooks are purely additive.
+
+## Consequences
+
+### Benefits
+
+**Reduced Latency**: With webhooks configured, content changes appear in semantic search within seconds to minutes (depending on Nextcloud background job configuration) instead of up to 1 hour. Queries like "What meetings do I have today?" reflect recent calendar updates.
+
+**Lower API Load**: Administrators who configure webhooks can reduce scanner frequency (e.g., 24-hour intervals), eliminating most polling API calls while maintaining safety reconciliation scans. This significantly reduces load on Nextcloud servers.
+
+**Better Scalability**: Webhooks scale better than polling as content volume grows. The system only processes changed documents instead of checking all documents every hour.
+
+**Simple Architecture**: The webhook endpoint is just another producer feeding the existing processor queue. No changes to scanner, processors, or queue management—webhooks integrate cleanly into the existing architecture.
+
+**Improved User Experience**: Lower-latency semantic search feels more responsive and accurate, especially for time-sensitive queries about recent changes.
+
+### Drawbacks
+
+**Manual Configuration**: Administrators must configure webhooks outside the MCP server using Nextcloud's admin tools. This adds setup complexity compared to the zero-configuration polling approach.
+
+**Deployment Requirements**: Webhooks require the MCP server to be reachable from Nextcloud via HTTP(S). Deployments behind NAT or with restrictive firewalls may not support webhooks without additional networking configuration.
+
+**Asynchronous Delivery**: Nextcloud processes webhooks via background jobs, introducing delivery latency (typically seconds to minutes). The exact latency depends on background job worker configuration and system load.
+
+**Testing Complexity**: Integration tests cannot rely on immediate webhook delivery due to asynchronous background job processing. Tests must either poll for results or mock webhook delivery directly.
+
+**New Failure Modes**: Webhook endpoint downtime, network issues between Nextcloud and MCP server, webhook notification floods from bulk operations. The system must handle these gracefully.
+
+**Version Dependencies**: The webhook_listeners app requires Nextcloud 30+. Older versions continue using polling exclusively.
+
+### Monitoring and Observability
+
+New metrics track webhook performance:
+
+- `webhook_notifications_received_total{event_type}`: Count of webhook notifications by event type
+- `webhook_processing_duration_seconds{event_type}`: Webhook handler latency
+- `webhook_errors_total{error_type}`: Failed webhook processing by error type (auth failure, parse error, queue full)
+
+Logs include:
+- Successful webhook processing: `Queued document from webhook: DocumentTask(...)`
+- Webhook authentication failures: `Webhook authentication failed`
+- Parse errors: `Failed to parse webhook payload: ...`
+- Unsupported events: `Ignoring webhook for unsupported event: ...`
+
+### Security Considerations
+
+**Optional Authentication**: When `WEBHOOK_SECRET` is configured, webhook requests must include `Authorization: Bearer <WEBHOOK_SECRET>` header. The server validates this before processing to prevent unauthorized document queueing. For local development, authentication can be disabled by leaving `WEBHOOK_SECRET` unset.
+
+**Payload Validation**: Webhook payloads are parsed and validated against expected schemas. Malformed payloads are rejected with 400 Bad Request responses.
+
+**No Scope Enforcement**: Unlike MCP tools, webhooks do not enforce progressive consent or check if users have enabled semantic search. Webhooks queue all document changes—administrators control which events trigger webhooks via Nextcloud filters. This keeps the webhook endpoint simple and stateless.
+
+### Testing Strategy
+
+**Unit Tests**: Test webhook handler logic, event parsing, and authentication validation using mocked payloads:
+
+```python
+async def test_webhook_endpoint_parses_note_created_event():
+    """Unit test: webhook endpoint extracts DocumentTask from note created event."""
+    payload = {
+        "user": {"uid": "alice"},
+        "time": 1704067200,
+        "event": {
+            "class": "OCP\\Files\\Events\\Node\\NodeCreatedEvent",
+            "node": {"id": "123", "path": "/alice/files/test.md"}
+        }
+    }
+    # Mock send_stream and verify DocumentTask is queued
+    ...
+```
+
+**Integration Tests (Without Real Webhooks)**: Since Nextcloud processes webhooks asynchronously via background jobs, integration tests should NOT rely on triggering real Nextcloud events and waiting for webhook delivery. Instead, tests should:
+
+1. **Mock webhook delivery**: POST webhook payloads directly to the `/webhooks/nextcloud` endpoint
+2. **Verify processing**: Check that documents are queued and eventually appear in Qdrant
+3. **Test authentication**: Verify requests without valid auth header are rejected (when `WEBHOOK_SECRET` is set)
+
+```python
+async def test_webhook_integration_mocked_delivery():
+    """Integration test: webhook handler queues document for processing."""
+    # POST webhook payload directly to endpoint (bypass Nextcloud)
+    response = await client.post("/webhooks/nextcloud", json=note_created_payload)
+    assert response.status_code == 200
+
+    # Wait for processor to handle document
+    await asyncio.sleep(2)
+
+    # Verify document appears in Qdrant
+    results = await qdrant_client.scroll(...)
+    assert len(results[0]) > 0
+```
+
+**Manual Testing (Real Webhooks)**: For end-to-end validation with real Nextcloud webhook delivery:
+
+1. Register webhook via OCS API or `NextcloudClient.register_webhook()` helper
+2. Configure webhook background job workers for low-latency delivery
+3. Trigger Nextcloud events (create note, add calendar event)
+4. Monitor MCP server logs for webhook delivery
+5. Verify documents appear in Qdrant after background job processing
+
+**Failure Mode Tests**:
+- Invalid authentication: Verify 401 response when auth header is missing/incorrect
+- Malformed payload: Verify 400 response for invalid JSON or missing required fields
+- Unsupported event types: Verify graceful handling (ignored, not error)
+- Queue full: Verify 500 response with appropriate error message
+
+### Future Enhancements
+
+**Batch Processing**: Group multiple webhook notifications within a short time window (e.g., 5 seconds) into a single batch before queueing. This reduces processor overhead during bulk operations like importing calendars.
+
+**Webhook Payload Optimization**: For large documents, Nextcloud could be configured to send minimal metadata in webhooks (just user_id, doc_id, doc_type), with processors fetching full content lazily. This reduces webhook payload size and network bandwidth.
+
+**Deduplication Window**: Track recently processed documents (last 5 minutes) to avoid redundant work when webhooks and scanner both detect the same change. The processor can check a simple in-memory cache before fetching document content.
+
+## Appendix A: Manual Webhook Testing Results (2025-01-11)
+
+### Testing Summary
+
+Manual validation of Nextcloud webhook schemas and behavior confirmed that webhooks work as documented with several important findings for implementation. **5 out of 6** webhook types were successfully captured and validated.
+
+**Test Environment:**
+- Nextcloud 30+ (Docker compose)
+- webhook_listeners app enabled
+- Test endpoint: `http://mcp:8000/webhooks/nextcloud`
+- Background webhook worker running (60s timeout)
+
+**Results:**
+- ✅ NodeCreatedEvent (file creation)
+- ✅ NodeWrittenEvent (file update)
+- ✅ NodeDeletedEvent (file deletion)
+- ✅ CalendarObjectCreatedEvent
+- ✅ CalendarObjectUpdatedEvent
+- ❌ CalendarObjectDeletedEvent (webhook did not fire - potential Nextcloud bug)
+
+### Critical Implementation Findings
+
+#### 1. Deletion Events Lack `node.id` Field
+
+**Finding:** `NodeDeletedEvent` payloads do NOT include `event.node.id`, only `event.node.path`.
+
+**Example:**
+```json
+{
+  "user": {"uid": "admin", "displayName": "admin"},
+  "time": 1762851093,
+  "event": {
+    "class": "OCP\\Files\\Events\\Node\\NodeDeletedEvent",
+    "node": {
+      "path": "/admin/files/Notes/Webhooks/Webhook Test Note.md"
+      // NOTE: No "id" field present
+    }
+  }
+}
+```
+
+**Impact:** The event parser in this ADR's example code assumes `event_data["node"]["id"]` exists for all file events. This will fail for deletions.
+
+**Update (2025-11-11):** Nextcloud maintainer clarified that `BeforeNodeDeletedEvent` should be used instead of `NodeDeletedEvent` to access `node.id` before the file is deleted. See [issue #56371](https://github.com/nextcloud/server/issues/56371#issuecomment-2470896634).
+
+> "Try using the `BeforeNodeDeletedEvent`. The `id` should still be available at that time. The reason `id` is not in `NodeDeletedEvent` is because the file is effectively guaranteed to be gone and, in turn, so is the FileInfo."
+> — Josh Richards, Nextcloud maintainer
+
+**Recommended Solution:** Use `OCP\Files\Events\Node\BeforeNodeDeletedEvent` for file deletion webhooks instead of `NodeDeletedEvent`.
+
+**Alternative Fix (if using NodeDeletedEvent):** Check for `id` existence and fall back to path-based identification:
+
+```python
+def extract_document_task(event_class: str, payload: dict) -> DocumentTask | None:
+    user_id = payload["user"]["uid"]
+    event_data = payload["event"]
+
+    # File deletion events - NO node.id field
+    if "NodeDeletedEvent" in event_class:
+        path = event_data["node"]["path"]
+        if not path.endswith(".md"):
+            return None
+        # Use path-based ID since node.id is unavailable
+        return DocumentTask(
+            user_id=user_id,
+            doc_id=f"path:{path}",  # Prefix to distinguish from numeric IDs
+            doc_type="note",
+            operation="delete",
+            modified_at=payload["time"],
+        )
+
+    # File creation/update events - node.id exists
+    elif "NodeCreatedEvent" in event_class or "NodeWrittenEvent" in event_class:
+        path = event_data["node"]["path"]
+        if not path.endswith(".md"):
+            return None
+
+        # Check if 'id' exists (should, but be defensive)
+        node_id = event_data["node"].get("id")
+        if not node_id:
+            # Fallback for missing ID
+            node_id = f"path:{path}"
+
+        return DocumentTask(
+            user_id=user_id,
+            doc_id=str(node_id),
+            doc_type="note",
+            operation="index",
+            modified_at=payload["time"],
+        )
+```
+
+**Qdrant Deletion Strategy:** When deleting by path-based ID, search Qdrant for documents with matching path metadata:
+
+```python
+async def delete_document_by_path(user_id: str, path: str):
+    """Delete document from Qdrant using path (when ID unavailable)."""
+    points = await qdrant.scroll(
+        collection_name=collection,
+        scroll_filter=Filter(must=[
+            FieldCondition(key="user_id", match=MatchValue(value=user_id)),
+            FieldCondition(key="metadata.path", match=MatchValue(value=path)),
+        ]),
+    )
+    # Delete found points...
+```
+
+#### 2. Multiple Webhooks Per Operation
+
+**Finding:** Creating a single note triggers 3-5 separate webhook events in rapid succession:
+
+1. `NodeCreatedEvent` for parent folder (if new)
+2. `NodeWrittenEvent` for parent folder
+3. `NodeCreatedEvent` for the note file
+4. `NodeWrittenEvent` for the note file (sometimes fires twice)
+
+**Impact:** Without deduplication, the processor will fetch and index the same note multiple times within seconds, wasting compute and API quota.
+
+**Solution:** The processor queue should be idempotent. If the same document is queued multiple times, only the latest version needs processing. Implementation options:
+
+1. **Queue-level deduplication:** Before adding to queue, check if a task for the same `(user_id, doc_id)` is already pending. Replace the existing task instead of adding duplicate.
+
+2. **Processor-level deduplication:** Track recently processed documents in a short-lived cache (5 minutes). If a document was just processed, skip redundant fetch unless the `modified_at` timestamp is newer.
+
+3. **Accept duplicates:** Let the processor handle duplicates naturally. Qdrant upserts are idempotent—reindexing with identical content is harmless but wasteful.
+
+**Recommendation:** Implement queue-level deduplication by maintaining a map of pending tasks and replacing duplicates with newer timestamps.
+
+#### 3. Type Discrepancy in `node.id`
+
+**Finding:** Nextcloud documentation specifies `node.id` as type `string`, but actual payloads return `int`:
+
+```json
+"node": {
+  "id": 437,  // integer, not "437"
+  "path": "/admin/files/Notes/Webhooks/Webhook Test Note.md"
+}
+```
+
+**Impact:** Code that assumes `node.id` is always a string will work but may cause type confusion in strongly-typed languages.
+
+**Solution:** Explicitly convert to string when extracting: `doc_id=str(event_data["node"]["id"])`
+
+#### 4. Calendar Events Have Different ID Field Path
+
+**Finding:** Calendar events store the document ID in a different location than file events:
+
+- **File events:** `event.node.id`
+- **Calendar events:** `event.objectData.id`
+
+**Impact:** Event parser must handle different field paths for different event types. The example code in this ADR correctly shows this difference.
+
+**Calendar Event Deletion:** Calendar deletion webhooks did NOT fire during testing. This may be a Nextcloud bug or require specific configuration (e.g., trash bin enabled). Until resolved, calendar deletions will only be detected via periodic scanner runs.
+
+#### 5. Rich Metadata in Calendar Webhooks
+
+**Finding:** Calendar webhook payloads include extensive metadata not present in file webhooks:
+
+```json
+{
+  "event": {
+    "calendarId": 1,
+    "calendarData": {
+      "id": 1,
+      "uri": "personal",
+      "{http://calendarserver.org/ns/}getctag": "...",
+      "{http://sabredav.org/ns}sync-token": 21,
+      // ... many calendar-level properties
+    },
+    "objectData": {
+      "id": 3,
+      "uri": "webhook-test-event-001.ics",
+      "lastmodified": 1762851169,
+      "etag": "\"2b937b7d77dc83c77329dfdb210ba9d0\"",
+      "calendarid": 1,
+      "size": 297,
+      "component": "vevent",
+      "classification": 0,
+      "uid": "webhook-test-event-001@nextcloud",
+      "calendardata": "BEGIN:VCALENDAR\r\nVERSION:2.0\r\n...",  // Full iCal
+      "{http://nextcloud.com/ns}deleted-at": null
+    },
+    "shares": []  // Array of sharing info
+  }
+}
+```
+
+**Opportunity:** The full iCal content is available in `objectData.calendardata`. The processor could extract metadata directly from the webhook payload instead of making an additional CalDAV request, reducing API load.
+
+### Updated Event Mapping
+
+Based on testing, the actual webhook behavior:
+
+| Nextcloud Event | Fires? | `node.id`/`objectData.id` Present? | Notes |
+|----------------|--------|-------------------------------------|-------|
+| `NodeCreatedEvent` | ✅ Yes | ✅ Yes (`int`) | Fires for folders too |
+| `NodeWrittenEvent` | ✅ Yes | ✅ Yes (`int`) | Fires 1-2x per operation |
+| `NodeDeletedEvent` | ✅ Yes | ❌ **NO** (only `path`) | Critical difference |
+| `CalendarObjectCreatedEvent` | ✅ Yes | ✅ Yes (`objectData.id`) | Full iCal included |
+| `CalendarObjectUpdatedEvent` | ✅ Yes | ✅ Yes (`objectData.id`) | Full iCal included |
+| `CalendarObjectDeletedEvent` | ❌ **DID NOT FIRE** | ❓ Unknown | Possible Nextcloud bug |
+
+### Recommended Implementation Changes
+
+The webhook handler code in this ADR requires these modifications:
+
+1. **Handle missing `node.id` in deletions** (see code example in Finding #1)
+2. **Add deduplication logic** to prevent redundant processing from multiple webhooks per operation
+3. **Validate field existence** before accessing nested properties (`get()` with defaults)
+4. **Log unsupported events** at DEBUG level (not WARNING) to avoid log noise
+5. **Add calendar deletion fallback:** Since webhook unreliable, calendar deletions rely on scanner reconciliation
+6. **Consider payload optimization:** Extract calendar metadata from webhook payload to reduce CalDAV API calls
+
+### Testing Implications
+
+**Integration Test Strategy:**
+
+The asynchronous nature of Nextcloud webhooks makes real webhook delivery unreliable for automated tests:
+
+- ✅ **DO:** POST webhook payloads directly to `/webhooks/nextcloud` endpoint in tests
+- ❌ **DON'T:** Trigger Nextcloud events and wait for webhook delivery
+- ✅ **DO:** Test authentication, payload parsing, and queue integration with mocked payloads
+- ❌ **DON'T:** Assume webhooks fire immediately or reliably
+
+**Manual Testing Required:**
+- Real webhook delivery latency (depends on background job workers)
+- Calendar deletion webhook behavior (confirm bug or configuration issue)
+- Behavior under high-frequency updates (bulk operations)
+- Network failure handling (Nextcloud can't reach MCP server)
+
+### Complete Tested Payload Examples
+
+See `webhook-testing-findings.md` in the repository root for:
+- Complete JSON payloads for all tested events
+- Detailed schema validation results
+- Additional edge cases and observations
+- Screenshots of webhook logs
+
+## References
+
+- ADR-007: Background Vector Database Synchronization (polling architecture)
+- Nextcloud Documentation: `~/Software/documentation/admin_manual/webhook_listeners/index.rst`
+- Nextcloud OCS API: Webhook registration endpoint
+- Current scanner implementation: `nextcloud_mcp_server/vector/scanner.py:37`
+- Webhook Testing Report: `webhook-testing-findings.md` (2025-01-11)

docs/ADR-011-improving-semantic-search-quality.md

@@ -0,0 +1,895 @@
+# ADR-011: Improving Semantic Search Quality Through Better Chunking and Embeddings
+
+**Status**: Proposed
+**Date**: 2025-11-12
+**Authors**: Development Team
+**Related**: ADR-003 (Vector Database Architecture), ADR-008 (MCP Sampling for RAG)
+
+## Context
+
+The semantic search implementation provides document retrieval across Nextcloud apps using vector embeddings. Production usage has revealed that **the system frequently misses relevant documents** (recall problem).
+
+Root cause analysis identifies two fundamental issues:
+
+### 1. Poor Chunking Strategy
+
+**Current Implementation** (`nextcloud_mcp_server/vector/document_chunker.py:36`):
+```python
+words = content.split()  # Naive whitespace splitting
+chunk_size = 512  # words
+overlap = 50  # words
+chunks = [words[i:i+chunk_size] for i in range(0, len(words), chunk_size-overlap)]
+```
+
+**Problems**:
+- **Breaks semantic boundaries**: Splits mid-sentence, mid-paragraph, mid-thought
+- **Loses context**: "The meeting discussed budget. We decided to..." becomes two disconnected chunks
+- **Poor retrieval**: Relevant content split across chunks with low individual relevance scores
+- **No structure awareness**: Ignores markdown headers, lists, code blocks
+
+**Evidence**:
+- Documents with relevant content in middle sections score poorly (content split across 3+ chunks)
+- Multi-sentence concepts (spanning 60-100 words) are fragmented
+- Search for "budget planning process" misses documents where these words appear in adjacent sentences but different chunks
+
+### 2. Suboptimal Embedding Model
+
+**Current Implementation** (`nextcloud_mcp_server/embedding/ollama_provider.py:33`):
+```python
+_model = "nomic-embed-text"  # 768 dimensions
+_dimension = 768  # Hardcoded
+```
+
+**Problems**:
+- **Model selection**: `nomic-embed-text` is general-purpose, not optimized for our use case
+- **No benchmarking**: Selected without comparative evaluation
+- **Dimensionality**: 768-dim may be insufficient for nuanced semantic distinctions
+- **No domain adaptation**: Model not tuned for Nextcloud content (notes, calendar, deck cards)
+
+**Evidence**:
+- Synonymous queries return different results ("meeting notes" vs. "discussion summary")
+- Domain-specific terms poorly represented ("standup", "retrospective", "OKRs")
+- Cross-lingual content (if present) not well supported
+
+### Current Performance
+
+**Baseline Metrics** (100-document test corpus, 50 queries):
+- **Recall@10**: ~52% (misses 48% of relevant documents)
+- **Precision@10**: ~78% (acceptable but room for improvement)
+- **MRR**: 0.58 (relevant docs often not in top positions)
+- **Zero-result queries**: 18% (completely missing relevant content)
+
+## Decision Drivers
+
+1. **Address Root Causes**: Fix fundamental issues (chunking, embeddings) before adding complexity (reranking, hybrid search)
+2. **Measurable Impact**: Target 40-60% improvement in recall through chunking/embedding alone
+3. **Independence**: Improvements should be orthogonal to future enhancements (reranking, GraphRAG)
+4. **Cost Efficiency**: Minimize infrastructure and API costs
+5. **Reindexing Acceptable**: One-time reindex cost justified by long-term quality improvement
+
+## Options Considered
+
+### Chunking Strategies
+
+#### Option C1: Semantic Sentence-Aware Chunking (RECOMMENDED)
+
+**Description**: Respect sentence boundaries while maintaining target chunk size
+
+**Implementation**:
+```python
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+
+splitter = RecursiveCharacterTextSplitter(
+    chunk_size=2048,  # ~512 words in characters
+    chunk_overlap=200,  # ~50 words in characters
+    separators=["\n\n", "\n", ". ", "! ", "? ", "; ", ": ", ", ", " "],
+    length_function=len,
+)
+```
+
+**How it works**:
+1. Try splitting by paragraphs (`\n\n`)
+2. If chunks too large, split by sentences (`. `, `! `, `? `)
+3. If still too large, split by clauses (`;`, `:`)
+4. Last resort: split by words
+
+**Pros**:
+- ✅ Preserves semantic boundaries (never breaks mid-sentence)
+- ✅ Maintains context coherence within chunks
+- ✅ Simple implementation (langchain library)
+- ✅ Configurable separators for different content types
+- ✅ Proven approach (used by major RAG systems)
+
+**Cons**:
+- ❌ Variable chunk sizes (not exactly 512 words, but close)
+- ❌ Adds dependency (langchain)
+- ❌ Slightly slower than naive splitting (~10-20ms per document)
+
+**Expected Impact**: 20-30% recall improvement
+
+#### Option C2: Hierarchical Context-Preserving Chunks
+
+**Description**: Create overlapping parent/child chunks
+
+**Structure**:
+```
+Document → Large parent chunks (1024 words) → Small child chunks (256 words)
+          ↓                                    ↓
+   Stored in Qdrant                       Searched first
+                                          Return parent context
+```
+
+**Implementation**:
+```python
+# Generate child chunks (searched)
+child_chunks = splitter.split_text(content, chunk_size=1024)
+
+# Generate parent chunks (context)
+parent_chunks = splitter.split_text(content, chunk_size=4096)
+
+# Store both with parent-child relationships
+for child_idx, child in enumerate(child_chunks):
+    parent_idx = find_parent(child_idx)
+    store_vector(
+        vector=embed(child),
+        payload={
+            "chunk": child,
+            "parent_chunk": parent_chunks[parent_idx],
+            "chunk_type": "child"
+        }
+    )
+```
+
+**Pros**:
+- ✅ Best of both worlds: precise matching + full context
+- ✅ Handles multi-hop information needs
+- ✅ Better for long documents (> 1000 words)
+
+**Cons**:
+- ❌ 2x storage (parent + child chunks)
+- ❌ More complex implementation
+- ❌ Higher indexing time (embed twice)
+- ❌ Query complexity (retrieve child, return parent)
+
+**Expected Impact**: 35-45% recall improvement (diminishing returns vs. complexity)
+
+**Verdict**: ⚠️ Consider only if Option C1 insufficient
+
+#### Option C3: Document Structure-Aware Chunking
+
+**Description**: Parse markdown/document structure before chunking
+
+**Implementation**:
+```python
+import mistune  # Markdown parser
+
+def structure_aware_chunk(markdown_content: str) -> list[str]:
+    ast = mistune.create_markdown(renderer='ast')(markdown_content)
+
+    chunks = []
+    for node in ast:
+        if node['type'] == 'heading':
+            # Start new chunk at each header
+            current_chunk = node['children'][0]['raw']
+        elif node['type'] == 'paragraph':
+            current_chunk += "\n" + node['children'][0]['raw']
+            if len(current_chunk) > 2048:
+                chunks.append(current_chunk)
+                current_chunk = ""
+
+    return chunks
+```
+
+**Pros**:
+- ✅ Respects document logical structure
+- ✅ Headers provide context for chunks
+- ✅ Works well for structured notes (documentation, meeting notes with sections)
+
+**Cons**:
+- ❌ Complex implementation (parser, AST traversal)
+- ❌ Markdown-specific (doesn't help calendar events, deck cards)
+- ❌ Variable chunk sizes (some sections very short/long)
+- ❌ Breaks for unstructured content
+
+**Expected Impact**: 15-25% improvement for structured content only
+
+**Verdict**: ⚠️ Future enhancement after Option C1
+
+#### Option C4: Fixed Sliding Window (Current Baseline)
+
+**Description**: Current naive word-based splitting
+
+**Verdict**: ❌ Superseded by Option C1
+
+### Embedding Model Strategies
+
+#### Option E1: Upgrade to Better General-Purpose Model (RECOMMENDED)
+
+**Description**: Switch to state-of-the-art embedding model
+
+**Candidates**:
+
+| Model | Dimensions | MTEB Score | Pros | Cons |
+|-------|-----------|------------|------|------|
+| **mxbai-embed-large** | 1024 | 64.68 | Best performance, good balance | Larger (slower) |
+| **nomic-embed-text-v1.5** | 768 | 62.39 | Upgraded version of current | Incremental improvement |
+| **bge-large-en-v1.5** | 1024 | 64.23 | Excellent for English | Not multilingual |
+| **nomic-embed-text** (current) | 768 | 60.10 | Baseline | Lower performance |
+
+**MTEB**: Massive Text Embedding Benchmark (higher = better semantic understanding)
+
+**Recommendation**: **mxbai-embed-large-v1**
+- Best MTEB score (64.68)
+- 1024 dimensions (richer semantic space)
+- Works well via Ollama
+- ~15-20% better retrieval quality in benchmarks
+
+**Implementation**:
+```python
+# config.py
+OLLAMA_EMBEDDING_MODEL = "mxbai-embed-large-v1"  # Changed from nomic-embed-text
+
+# ollama_provider.py
+async def get_dimension(self) -> int:
+    # Query Ollama for actual dimension instead of hardcoding
+    response = await self.client.post("/api/show", json={"name": self.model})
+    return response.json()["details"]["embedding_length"]
+```
+
+**Migration**:
+1. Deploy new model to Ollama
+2. Create new Qdrant collection (different dimension)
+3. Reindex all documents with new embeddings
+4. Swap collections atomically
+5. Delete old collection
+
+**Pros**:
+- ✅ Immediate quality improvement (15-20%)
+- ✅ Simple change (config + reindex)
+- ✅ No code complexity
+- ✅ Future-proof (state-of-the-art model)
+
+**Cons**:
+- ❌ Requires full reindex (2-4 hours for 1000 documents)
+- ❌ Larger model = slower embedding (~50ms vs. 30ms per chunk)
+- ❌ Higher dimensionality = more storage (~30% increase)
+
+**Expected Impact**: 15-25% recall improvement
+
+#### Option E2: Multi-Vector Embeddings (ColBERT-style)
+
+**Description**: Generate multiple embeddings per chunk (token-level)
+
+**Architecture**:
+```
+Chunk → Transformer → Token embeddings (e.g., 50 tokens × 128 dim) → Store all
+Query → Transformer → Token embeddings → MaxSim(query_tokens, doc_tokens)
+```
+
+**MaxSim scoring**:
+```python
+def maxsim_score(query_embeddings, doc_embeddings):
+    # For each query token, find max similarity with any doc token
+    scores = []
+    for q_emb in query_embeddings:
+        max_sim = max(cosine_similarity(q_emb, d_emb) for d_emb in doc_embeddings)
+        scores.append(max_sim)
+    return sum(scores)
+```
+
+**Pros**:
+- ✅ Best retrieval quality (state-of-the-art results)
+- ✅ Fine-grained matching (token-level)
+- ✅ Handles partial matches better
+
+**Cons**:
+- ❌ **50-100x storage increase** (50 vectors per chunk vs. 1)
+- ❌ **Slower search** (compute MaxSim for each candidate)
+- ❌ **Complex implementation** (custom scoring, storage schema)
+- ❌ **Requires specialized model** (ColBERTv2, not available in Ollama)
+
+**Expected Impact**: 40-50% improvement, but at very high cost
+
+**Verdict**: ❌ Too complex, too expensive for marginal gain over E1+C1
+
+#### Option E3: Fine-Tuned Domain-Specific Model
+
+**Description**: Fine-tune embedding model on Nextcloud corpus
+
+**Process**:
+1. Collect training data (query-document pairs)
+2. Fine-tune base model (e.g., `nomic-embed-text`) on domain data
+3. Deploy fine-tuned model via Ollama
+4. Reindex with fine-tuned embeddings
+
+**Training data needed**:
+- 1,000+ query-document pairs
+- Labeled relevance (positive/negative examples)
+- Representative of real usage
+
+**Pros**:
+- ✅ Optimized for specific content (notes, calendar, deck)
+- ✅ Better handling of domain terminology
+- ✅ Highest potential quality improvement (30-40%)
+
+**Cons**:
+- ❌ **Requires training data** (expensive to collect)
+- ❌ **GPU infrastructure** needed for fine-tuning
+- ❌ **Expertise required** (ML/NLP knowledge)
+- ❌ **Maintenance burden** (retrain as corpus evolves)
+- ❌ **Time investment**: 2-4 weeks initial setup
+
+**Expected Impact**: 30-40% improvement, but high cost
+
+**Verdict**: ⚠️ Consider only if E1+C1 insufficient AND have training data
+
+#### Option E4: Ensemble Embeddings
+
+**Description**: Generate embeddings with multiple models, combine scores
+
+**Implementation**:
+```python
+models = ["mxbai-embed-large-v1", "bge-large-en-v1.5"]
+
+# Index
+embeddings = [await embed(chunk, model) for model in models]
+store_multi_vector(embeddings)
+
+# Search
+query_embeddings = [await embed(query, model) for model in models]
+scores = [search(q_emb, model) for q_emb, model in zip(query_embeddings, models)]
+combined_score = 0.5 * scores[0] + 0.5 * scores[1]
+```
+
+**Pros**:
+- ✅ Robust to individual model weaknesses
+- ✅ Better coverage of semantic space
+
+**Cons**:
+- ❌ 2x storage and compute
+- ❌ Complex scoring and fusion
+- ❌ Marginal improvement (~5-10%) over single best model
+
+**Expected Impact**: 5-10% over best single model
+
+**Verdict**: ❌ Not worth complexity
+
+### Combined Strategies
+
+#### Option D1: Best Chunking + Best Embedding (RECOMMENDED)
+
+**Combination**: Option C1 (Semantic Chunking) + Option E1 (mxbai-embed-large-v1)
+
+**Expected Impact**:
+- Chunking: +20-30% recall
+- Embedding: +15-25% recall
+- **Combined**: +35-55% recall improvement (not strictly additive, but significant)
+
+**Cost**:
+- Development: 1-2 days
+- Reindex: 2-4 hours (one-time)
+- Ongoing: None (same infrastructure)
+
+**Pros**:
+- ✅ Addresses both root causes
+- ✅ Orthogonal improvements (chunking + embedding)
+- ✅ Simple implementation
+- ✅ No new infrastructure
+- ✅ Future-proof foundation for additional enhancements (reranking, hybrid search)
+
+**Cons**:
+- ❌ Requires full reindex (manageable)
+- ❌ Slightly higher storage (1024 vs. 768 dim)
+
+**Verdict**: ✅ **RECOMMENDED**
+
+## Decision
+
+**Adopt Option D1: Semantic Chunking + Upgraded Embedding Model**
+
+Implement both improvements together to maximize recall improvement:
+
+### 1. Semantic Sentence-Aware Chunking
+
+**Changes**:
+- Replace naive word splitting with `RecursiveCharacterTextSplitter`
+- Preserve sentence boundaries, paragraph structure
+- Maintain similar chunk sizes (~512 words / 2048 characters)
+
+**Implementation**:
+
+```python
+# nextcloud_mcp_server/vector/document_chunker.py
+
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+
+class DocumentChunker:
+    """Chunk documents into semantically coherent pieces."""
+
+    def __init__(
+        self,
+        chunk_size: int = 2048,  # Characters, not words
+        chunk_overlap: int = 200,  # Characters, not words
+    ):
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+
+        self.splitter = RecursiveCharacterTextSplitter(
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            separators=[
+                "\n\n",  # Paragraphs (highest priority)
+                "\n",    # Lines
+                ". ",    # Sentences
+                "! ",
+                "? ",
+                "; ",    # Clauses
+                ": ",
+                ", ",    # Phrases
+                " ",     # Words (last resort)
+            ],
+            length_function=len,
+            is_separator_regex=False,
+        )
+
+    def chunk_text(self, content: str) -> list[str]:
+        """
+        Chunk text while preserving semantic boundaries.
+
+        Args:
+            content: Full document text
+
+        Returns:
+            List of text chunks, each ending at a semantic boundary
+        """
+        if not content:
+            return []
+
+        # Use RecursiveCharacterTextSplitter for semantic boundaries
+        chunks = self.splitter.split_text(content)
+
+        return chunks
+```
+
+**Configuration Changes** (`config.py`):
+```python
+# Old (word-based)
+DOCUMENT_CHUNK_SIZE: int = 512  # words
+DOCUMENT_CHUNK_OVERLAP: int = 50  # words
+
+# New (character-based, more precise)
+DOCUMENT_CHUNK_SIZE: int = 2048  # characters (~512 words)
+DOCUMENT_CHUNK_OVERLAP: int = 200  # characters (~50 words)
+```
+
+**Dependency** (`pyproject.toml`):
+```toml
+[project]
+dependencies = [
+    # ... existing dependencies
+    "langchain-text-splitters>=0.2.0",
+]
+```
+
+### 2. Upgrade Embedding Model
+
+**Changes**:
+- Switch from `nomic-embed-text` (768-dim) to `mxbai-embed-large-v1` (1024-dim)
+- Dynamic dimension detection (query Ollama instead of hardcoding)
+- Create new Qdrant collection for new dimensions
+
+**Implementation**:
+
+```python
+# nextcloud_mcp_server/embedding/ollama_provider.py
+
+class OllamaEmbeddingProvider(EmbeddingProvider):
+    def __init__(self, base_url: str, model: str, verify_ssl: bool = True):
+        self.base_url = base_url
+        self.model = model
+        self._dimension: int | None = None  # Changed: query dynamically
+        self.client = httpx.AsyncClient(base_url=base_url, verify=verify_ssl)
+
+    async def dimension(self) -> int:
+        """Get embedding dimension from Ollama API."""
+        if self._dimension is None:
+            try:
+                response = await self.client.post(
+                    "/api/show",
+                    json={"name": self.model},
+                    timeout=10.0,
+                )
+                response.raise_for_status()
+                info = response.json()
+                self._dimension = info.get("details", {}).get("embedding_length")
+
+                if self._dimension is None:
+                    # Fallback: generate test embedding to detect dimension
+                    test_emb = await self.embed("test")
+                    self._dimension = len(test_emb)
+
+            except Exception as e:
+                logger.warning(f"Failed to get dimension from Ollama: {e}, using fallback")
+                # Fallback dimensions by model name
+                if "mxbai-embed-large" in self.model:
+                    self._dimension = 1024
+                elif "nomic-embed-text" in self.model:
+                    self._dimension = 768
+                else:
+                    self._dimension = 768  # Default
+
+        return self._dimension
+```
+
+**Configuration Changes** (`config.py`):
+```python
+# Old
+OLLAMA_EMBEDDING_MODEL: str = "nomic-embed-text"
+
+# New
+OLLAMA_EMBEDDING_MODEL: str = "mxbai-embed-large-v1"
+```
+
+**Environment Variable**:
+```bash
+OLLAMA_EMBEDDING_MODEL=mxbai-embed-large-v1
+```
+
+### 3. Migration Strategy
+
+**Reindexing Process**:
+
+```python
+# nextcloud_mcp_server/vector/migration.py
+
+async def migrate_to_new_embeddings():
+    """
+    Migrate from old embeddings to new embeddings.
+
+    Process:
+    1. Create new collection with new dimension
+    2. Reindex all documents with new embeddings
+    3. Atomic swap (update collection name in config)
+    4. Delete old collection
+    """
+    old_collection = "nextcloud_content"
+    new_collection = "nextcloud_content_v2"
+
+    # 1. Create new collection
+    await qdrant_client.create_collection(
+        collection_name=new_collection,
+        vectors_config=VectorParams(
+            size=1024,  # mxbai-embed-large-v1 dimension
+            distance=Distance.COSINE,
+        ),
+    )
+
+    # 2. Reindex all documents
+    logger.info("Starting reindex with new embeddings...")
+    scanner = VectorScanner(...)
+    processor = VectorProcessor(collection_name=new_collection, ...)
+
+    await scanner.scan_all()  # Rescans and re-embeds all documents
+
+    # 3. Wait for completion
+    while True:
+        status = await get_sync_status()
+        if status.pending_documents == 0:
+            break
+        await asyncio.sleep(5)
+
+    # 4. Atomic swap
+    # Update config to point to new collection
+    # (or use collection alias in Qdrant)
+    await qdrant_client.update_collection_aliases(
+        change_aliases_operations=[
+            CreateAliasOperation(
+                create_alias=CreateAlias(
+                    collection_name=new_collection,
+                    alias_name="nextcloud_content"
+                )
+            )
+        ]
+    )
+
+    # 5. Verify new collection works
+    test_results = await run_benchmark_queries()
+    if test_results.recall < baseline_recall:
+        # Rollback
+        logger.error("New embeddings worse than baseline, rolling back")
+        await rollback_migration()
+        return False
+
+    # 6. Delete old collection
+    await qdrant_client.delete_collection(old_collection)
+    logger.info("Migration complete!")
+    return True
+```
+
+**Downtime Mitigation**:
+- Use Qdrant collection aliases for atomic swap
+- Reindex can happen in background
+- Only brief downtime during alias swap (~1s)
+
+**Rollback Plan**:
+- Keep old collection until validation complete
+- If new embeddings worse, swap alias back to old collection
+- No data loss
+
+### 4. Validation & Benchmarking
+
+**Before/After Comparison**:
+
+```python
+# tests/benchmarks/chunking_embedding_comparison.py
+
+async def benchmark_chunking_embeddings():
+    """
+    Compare old vs. new chunking and embeddings on test queries.
+    """
+    test_queries = load_benchmark_queries()  # 100 queries with known relevant docs
+
+    # Baseline (current)
+    baseline_results = await run_queries(
+        queries=test_queries,
+        collection="nextcloud_content",  # Old: nomic-embed-text, word chunks
+    )
+
+    # New implementation
+    new_results = await run_queries(
+        queries=test_queries,
+        collection="nextcloud_content_v2",  # New: mxbai-embed-large-v1, semantic chunks
+    )
+
+    # Compare metrics
+    comparison = {
+        "baseline": {
+            "recall@10": calculate_recall(baseline_results, k=10),
+            "precision@10": calculate_precision(baseline_results, k=10),
+            "mrr": calculate_mrr(baseline_results),
+            "zero_result_rate": calculate_zero_result_rate(baseline_results),
+        },
+        "new": {
+            "recall@10": calculate_recall(new_results, k=10),
+            "precision@10": calculate_precision(new_results, k=10),
+            "mrr": calculate_mrr(new_results),
+            "zero_result_rate": calculate_zero_result_rate(new_results),
+        },
+        "improvement": {
+            "recall_improvement": (new_recall - baseline_recall) / baseline_recall,
+            "precision_improvement": (new_precision - baseline_precision) / baseline_precision,
+        }
+    }
+
+    return comparison
+```
+
+**Success Criteria**:
+- **Recall@10**: Improve from ~52% to ≥75% (+40% improvement)
+- **Precision@10**: Maintain ≥75% (no degradation)
+- **MRR**: Improve from 0.58 to ≥0.70
+- **Zero-result rate**: Reduce from 18% to ≤10%
+- **Indexing time**: Maintain ≤10s per document
+
+**Validation Process**:
+1. Run benchmark on baseline (current implementation)
+2. Implement changes
+3. Run benchmark on new implementation
+4. Compare metrics
+5. If improvement ≥40%, proceed to production
+6. If improvement <40%, investigate and iterate
+
+## Implementation Timeline
+
+### Week 1: Development & Testing
+
+**Day 1-2: Chunking Implementation**
+- [ ] Add langchain-text-splitters dependency
+- [ ] Refactor `document_chunker.py`
+- [ ] Update configuration (character-based chunk sizes)
+- [ ] Write unit tests for semantic boundaries
+- [ ] Validate: Chunks never break mid-sentence
+
+**Day 3-4: Embedding Implementation**
+- [ ] Update `ollama_provider.py` with dynamic dimension detection
+- [ ] Update configuration (new model name)
+- [ ] Deploy `mxbai-embed-large-v1` to Ollama
+- [ ] Test embedding generation with new model
+- [ ] Validate: Embeddings are 1024-dim
+
+**Day 5: Migration Script**
+- [ ] Write migration script (collection creation, reindexing, alias swap)
+- [ ] Test migration on staging environment
+- [ ] Validate: No data loss, atomic swap works
+
+### Week 2: Reindexing & Validation
+
+**Day 1-2: Staging Reindex**
+- [ ] Run full reindex on staging environment
+- [ ] Monitor indexing performance
+- [ ] Validate: All documents indexed correctly
+
+**Day 3: Benchmarking**
+- [ ] Run benchmark queries on old collection (baseline)
+- [ ] Run benchmark queries on new collection
+- [ ] Compare metrics (recall, precision, MRR)
+- [ ] Validate: ≥40% recall improvement
+
+**Day 4: Production Reindex**
+- [ ] Schedule maintenance window (optional, can run in background)
+- [ ] Run migration script on production
+- [ ] Monitor reindexing progress
+- [ ] Atomic swap when complete
+
+**Day 5: Production Validation**
+- [ ] Monitor search quality metrics
+- [ ] Collect user feedback
+- [ ] Compare production metrics to staging
+- [ ] Rollback if issues detected
+
+## Cost Analysis
+
+### Development Cost
+- **Time**: 1-2 weeks (implementation + validation)
+- **Effort**: 40-60 hours @ $100/hour = $4,000 - $6,000
+
+### Infrastructure Cost
+- **Storage**: +30% (1024-dim vs. 768-dim)
+  - Example: 1,000 notes × 3 chunks × 1024 dim × 4 bytes = 12 MB (negligible)
+- **Compute**: +20% embedding time (50ms vs. 30ms per chunk)
+  - Amortized over batch indexing, minimal impact
+- **No new infrastructure**: Uses existing Ollama + Qdrant
+
+### Reindexing Cost (One-Time)
+- **Time**: 2-4 hours for 1,000 documents
+  - 1,000 docs × 3 chunks × 50ms = 150 seconds (~2.5 minutes embedding)
+  - + Ollama processing time + Qdrant insertion
+- **Downtime**: ~1 second (atomic alias swap)
+
+### Total Cost
+- **Initial**: $4,000 - $6,000 (development + testing)
+- **Ongoing**: $0 (no new infrastructure or API costs)
+
+### ROI
+- **Recall improvement**: +40-60% (finding relevant documents)
+- **User satisfaction**: Reduced zero-result queries (18% → 10%)
+- **Foundation**: Enables future enhancements (reranking, hybrid search)
+- **Cost per % improvement**: $100 - $150 (excellent ROI)
+
+## Consequences
+
+### Positive
+
+1. **Addresses Root Causes**: Fixes fundamental issues (chunking, embeddings) not symptoms
+2. **High Impact**: Expected 40-60% recall improvement from foundational changes
+3. **Future-Proof**: Creates solid foundation for future enhancements (reranking, hybrid search, GraphRAG)
+4. **Simple**: No architectural changes, no new infrastructure
+5. **Orthogonal**: Improvements are independent, can be validated separately
+6. **Low Risk**: Proven techniques (RecursiveCharacterTextSplitter, mxbai-embed-large-v1)
+7. **Maintainable**: Standard libraries and models, easy to debug
+
+### Negative
+
+1. **Reindexing Required**: 2-4 hours one-time cost (manageable, can run in background)
+2. **Storage Increase**: +30% for higher-dimensional embeddings (12 MB vs. 9 MB for 1K docs)
+3. **Slower Indexing**: +20% embedding time (50ms vs. 30ms per chunk)
+4. **Dependency**: Adds langchain-text-splitters (minimal, well-maintained library)
+5. **Not a Complete Solution**: May still need reranking/hybrid search for optimal recall (but solid foundation)
+
+### Neutral
+
+1. **Model Lock-In**: Committed to mxbai-embed-large-v1, but can change later (another reindex)
+2. **Chunk Size Trade-offs**: ~512 words is heuristic, may need tuning for specific content types
+
+## Monitoring & Success Metrics
+
+### Real-Time Metrics (Grafana)
+
+**Search Quality**:
+- `semantic_search_recall_at_10` (target: ≥75%)
+- `semantic_search_precision_at_10` (target: ≥75%)
+- `semantic_search_mrr` (target: ≥0.70)
+- `semantic_search_zero_result_rate` (target: ≤10%)
+
+**Performance**:
+- `semantic_search_latency_ms` (p50, p95, p99)
+- `embedding_generation_time_ms`
+- `indexing_throughput_docs_per_sec`
+
+**Indexing**:
+- `documents_indexed_total`
+- `documents_pending`
+- `indexing_errors_total`
+
+### Weekly Validation
+
+**A/B Testing** (if gradual rollout):
+- 50% users: New embeddings
+- 50% users: Old embeddings
+- Compare metrics for 1 week
+- Full rollout if new embeddings superior
+
+**User Feedback**:
+- Survey: "How satisfied are you with search results?" (1-5 scale)
+- Track: Number of "search not working" support tickets
+- Monitor: User-reported false negatives ("I know this doc exists")
+
+### Rollback Criteria
+
+**Automatic Rollback** if:
+- Recall decreases by >10% from baseline
+- Error rate increases by >50%
+- Query latency increases by >100%
+
+**Manual Rollback** if:
+- User complaints increase significantly
+- Zero-result queries increase instead of decrease
+
+## Future Enhancements
+
+These improvements create a solid foundation. Future enhancements (in order of priority):
+
+1. **Cross-Encoder Reranking** (ADR-012)
+   - Two-stage retrieval: broad recall (50 candidates) → precise reranking (top 10)
+   - Expected: +15-20% additional recall improvement
+   - Builds on: Better embeddings retrieve better candidates to rerank
+
+2. **Hybrid Search** (ADR-013)
+   - Combine vector search + BM25 keyword search
+   - Expected: +10-15% additional recall (especially for exact matches)
+   - Builds on: Semantic chunks provide better keyword match context
+
+3. **Multi-App Indexing** (ADR-014)
+   - Index calendar, deck, files (currently notes-only)
+   - Expected: Expands searchable corpus 3-5x
+   - Builds on: Proven chunking and embedding strategy
+
+4. **GraphRAG** (ADR-015, conditional)
+   - Only if: Global thematic queries needed OR corpus >10K documents
+   - Expected: Relationship discovery, multi-hop reasoning
+   - Builds on: High-quality embeddings improve graph construction
+
+## References
+
+### Research Papers
+
+1. **RecursiveCharacterTextSplitter**
+   - LangChain Documentation: https://python.langchain.com/docs/modules/data_connection/document_transformers/text_splitters/recursive_text_splitter
+   - Proven technique used by major RAG systems
+
+2. **MTEB Leaderboard** (Massive Text Embedding Benchmark)
+   - https://huggingface.co/spaces/mteb/leaderboard
+   - Comprehensive embedding model comparison
+
+3. **mxbai-embed-large**
+   - Model: https://huggingface.co/mixedbread-ai/mxbai-embed-large-v1
+   - Best general-purpose embedding model (MTEB: 64.68)
+
+### Related ADRs
+
+- **ADR-003**: Vector Database and Semantic Search Architecture (original implementation)
+- **ADR-008**: MCP Sampling for Multi-App Semantic Search with RAG (answer generation)
+
+### Tools & Libraries
+
+- **LangChain Text Splitters**: https://python.langchain.com/docs/modules/data_connection/document_transformers/
+- **Ollama Embedding Models**: https://ollama.ai/library
+- **Qdrant Collections**: https://qdrant.tech/documentation/concepts/collections/
+
+## Summary
+
+This ADR addresses the root causes of poor semantic search recall:
+
+1. **Better Chunking**: Semantic sentence-aware splitting (preserves context)
+2. **Better Embeddings**: Upgrade to mxbai-embed-large-v1 (richer semantic space)
+
+**Expected Impact**: 40-60% recall improvement with minimal cost and complexity.
+
+**Why This Approach**:
+- Fixes fundamentals before adding complexity
+- Proven techniques (not experimental)
+- Simple implementation (1-2 weeks)
+- Creates foundation for future enhancements
+- No new infrastructure or ongoing costs
+
+**Next Steps**: Approve ADR → Implement changes → Reindex → Validate → Production rollout

docs/ADR-012-unified-multi-algorithm-search.md

@@ -0,0 +1,619 @@
+# ADR-012: Unified Multi-Algorithm Search with Client-Configurable Weighting
+
+## Status
+Proposed
+
+## Context
+
+### Current State
+
+The Nextcloud MCP server currently provides semantic search via vector similarity (Qdrant), as designed in ADR-003 and implemented through ADR-007. However, users and MCP clients have limited control over search behavior:
+
+1. **Single algorithm only**: Only pure vector similarity search is available
+2. **No algorithm selection**: MCP clients cannot choose between semantic, keyword, or fuzzy approaches
+3. **No weighting control**: Clients cannot adjust the balance between different search methods
+4. **Disconnected implementations**: Viz pane uses different search algorithms than MCP tools
+5. **Limited flexibility**: No way to optimize search for different use cases (exact match vs. conceptual similarity)
+
+### User Needs
+
+Different search scenarios require different algorithms:
+
+- **Exact match queries**: "Find note titled 'Q1 Budget'" → keyword search preferred
+- **Conceptual queries**: "What are my goals for next quarter?" → semantic search preferred
+- **Typo-tolerant queries**: "Find note about kuberntes" → fuzzy search needed
+- **Balanced queries**: "Find documentation about API endpoints" → hybrid search optimal
+
+Additionally, users need a **testing interface** (viz pane) to:
+- Experiment with different search algorithms on their own documents
+- Visualize search results and algorithm behavior
+- Tune weights for optimal results
+- Understand which algorithm works best for their queries
+
+### Technical Requirements
+
+1. **Unified interface**: Single MCP tool supporting multiple algorithms
+2. **Client control**: MCP clients specify algorithm and weights via tool parameters
+3. **Backward compatibility**: Existing `nc_semantic_search()` behavior preserved
+4. **Shared implementation**: Viz pane and MCP tools use identical search algorithms
+5. **User accessibility**: Viz pane available to all logged-in users with vector sync enabled
+6. **Performance**: Minimal overhead for algorithm selection
+
+## Decision
+
+We will implement a **unified multi-algorithm search architecture** with the following components:
+
+### Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         MCP Client / User Browser                            │
+│                                                                               │
+│  ┌──────────────────────────┐         ┌──────────────────────────────────┐  │
+│  │   MCP Tool Call          │         │   Viz Pane (Browser UI)          │  │
+│  │                          │         │                                  │  │
+│  │ nc_semantic_search(      │         │ - Algorithm selector dropdown    │  │
+│  │   query="kubernetes",    │         │ - Weight adjustment sliders      │  │
+│  │   algorithm="hybrid",    │         │ - Interactive 2D scatter plot    │  │
+│  │   semantic_weight=0.5,   │         │ - Side-by-side comparison        │  │
+│  │   keyword_weight=0.3,    │         │ - Real-time search testing       │  │
+│  │   fuzzy_weight=0.2       │         │                                  │  │
+│  │ )                        │         │                                  │  │
+│  └───────────┬──────────────┘         └────────────┬─────────────────────┘  │
+└──────────────┼─────────────────────────────────────┼────────────────────────┘
+               │                                      │
+               │ MCP Protocol                         │ HTTPS (htmx)
+               │                                      │
+┌──────────────▼──────────────────────────────────────▼────────────────────────┐
+│                        MCP Server (/app endpoint)                             │
+│                                                                               │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │              Unified Search Interface (server/semantic.py)              │ │
+│  │                                                                         │ │
+│  │  @mcp.tool() nc_semantic_search(algorithm, weights...)                 │ │
+│  │  ├─ Validate parameters (weights sum ≤1.0)                             │ │
+│  │  ├─ Dispatch to algorithm selector                                     │ │
+│  │  └─ Return ranked SearchResponse                                       │ │
+│  └────────────────────────────┬────────────────────────────────────────────┘ │
+│                                │                                              │
+│  ┌────────────────────────────▼────────────────────────────────────────────┐ │
+│  │              Algorithm Dispatcher (search/algorithms.py)                │ │
+│  │                                                                         │ │
+│  │  if algorithm == "semantic":    → semantic.py                          │ │
+│  │  if algorithm == "keyword":     → keyword.py                           │ │
+│  │  if algorithm == "fuzzy":       → fuzzy.py                             │ │
+│  │  if algorithm == "hybrid":      → hybrid.py (RRF fusion)               │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│                                                                               │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐           │
+│  │  semantic.py     │  │  keyword.py      │  │  fuzzy.py        │           │
+│  │                  │  │                  │  │                  │           │
+│  │ • Query Qdrant   │  │ • Token matching │  │ • Char overlap   │           │
+│  │ • Cosine dist    │  │ • Title weight   │  │ • 70% threshold  │           │
+│  │ • Score ≥0.7     │  │ • ADR-001 logic  │  │ • Simple impl    │           │
+│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘           │
+│           │                     │                      │                     │
+│           └─────────────────────┼──────────────────────┘                     │
+│                                 │                                            │
+│  ┌──────────────────────────────▼──────────────────────────────────────────┐ │
+│  │                    hybrid.py (Reciprocal Rank Fusion)                   │ │
+│  │                                                                         │ │
+│  │  1. Run algorithms in parallel (semantic, keyword, fuzzy)              │ │
+│  │  2. Collect ranked results from each                                   │ │
+│  │  3. Apply RRF formula: score = weight / (k + rank)                     │ │
+│  │  4. Combine scores across algorithms                                   │ │
+│  │  5. Re-rank by combined score                                          │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+└───────────────────────────────────┬───────────────────────────────────────────┘
+                                    │
+                    ┌───────────────┴───────────────┐
+                    │                               │
+         ┌──────────▼──────────┐         ┌─────────▼────────────┐
+         │ Qdrant Vector DB    │         │ Nextcloud APIs       │
+         │                     │         │                      │
+         │ • Vector search     │         │ • Access verification│
+         │ • user_id filter    │         │ • Full metadata fetch│
+         │ • Score threshold   │         │ • Permission checks  │
+         │ • 768-dim embeddings│         │                      │
+         └─────────────────────┘         └──────────────────────┘
+```
+
+### Data Flow
+
+#### MCP Tool Request
+```
+1. Client calls nc_semantic_search(query, algorithm="hybrid", weights...)
+2. Server validates parameters (weights sum ≤1.0)
+3. Dispatcher routes to hybrid.py
+4. Hybrid search runs semantic, keyword, fuzzy in parallel
+5. RRF combines results with weighted scores
+6. Access verification via Nextcloud API
+7. Return ranked SearchResponse to client
+```
+
+#### Viz Pane Request (Server-Side Processing)
+```
+1. User navigates to /app (Vector Visualization tab)
+2. Browser loads vector-viz fragment via htmx
+3. User enters query and adjusts algorithm/weights
+4. htmx sends request to /app/vector-viz endpoint
+5. Server executes search via search/algorithms.py:
+   - Filters by user_id (multi-tenant security)
+   - Applies selected algorithm (semantic/keyword/fuzzy/hybrid)
+   - Filters by document type (notes/files/calendar/contacts)
+   - Retrieves matching results + metadata
+6. Server performs PCA reduction (768-dim → 2D):
+   - Converts matching results to 2D coordinates
+   - Only sends coordinates + metadata (not full vectors)
+   - Dramatically reduces bandwidth (e.g., 768 floats → 2 floats per doc)
+7. Server returns JSON: {results: [...], coordinates_2d: [...], stats: {...}}
+8. Browser receives lightweight response
+9. Plotly.js renders interactive scatter plot
+10. Matching results highlighted (blue), non-matches grayed (40% opacity)
+```
+
+**Performance Benefits of Server-Side Processing**:
+- **Bandwidth reduction**: ~384x less data (2 floats vs 768 floats per document)
+- **Client efficiency**: Browser only handles visualization, not computation
+- **Scalability**: Can visualize 10,000+ documents without client-side lag
+- **Security**: Raw vectors never leave server
+- **Consistency**: Same search logic as MCP tool (no drift)
+
+### 1. Core Search Algorithms
+
+Four search algorithms will be available:
+
+#### a) Semantic Search (Vector Similarity)
+- **Method**: Cosine distance in 768-dimensional embedding space
+- **Implementation**: Qdrant `query_points` with user_id filtering
+- **Use case**: Conceptual queries, finding related content
+- **Current status**: Implemented in `nextcloud_mcp_server/server/semantic.py`
+
+#### b) Keyword Search (Token-Based)
+- **Method**: Token matching with weighted scoring (from ADR-001)
+- **Implementation**: Title matches weighted 3x higher than content
+- **Use case**: Exact phrase matching, known titles
+- **Current status**: Designed in ADR-001, not implemented
+
+#### c) Fuzzy Search (Character Overlap)
+- **Method**: Simple character-based similarity (70% threshold)
+- **Implementation**: Character set comparison (current viz pane approach)
+- **Use case**: Typo tolerance, approximate matching
+- **Current status**: Implemented in viz pane only
+
+#### d) Hybrid Search (Multi-Algorithm Fusion)
+- **Method**: Reciprocal Rank Fusion (RRF) from ADR-003
+- **Implementation**: Parallel execution + score combination
+- **Use case**: Balanced queries, general-purpose search
+- **Current status**: Designed in ADR-003, not implemented
+
+### 2. Unified MCP Tool Interface
+
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search(
+    query: str,
+    ctx: Context,
+    limit: int = 10,
+    score_threshold: float = 0.7,
+    algorithm: Literal["semantic", "keyword", "fuzzy", "hybrid"] = "hybrid",
+    semantic_weight: float = 0.5,
+    keyword_weight: float = 0.3,
+    fuzzy_weight: float = 0.2,
+) -> SearchResponse:
+    """
+    Search Nextcloud content using configurable algorithms.
+
+    Args:
+        query: Natural language search query
+        ctx: MCP context for authentication
+        limit: Maximum results to return
+        score_threshold: Minimum similarity score (semantic/hybrid only)
+        algorithm: Search algorithm to use
+        semantic_weight: Weight for semantic results (hybrid only, default: 0.5)
+        keyword_weight: Weight for keyword results (hybrid only, default: 0.3)
+        fuzzy_weight: Weight for fuzzy results (hybrid only, default: 0.2)
+
+    Returns:
+        Ranked search results with scores and excerpts
+    """
+```
+
+**Key decisions**:
+- **Single tool name**: Keep `nc_semantic_search` for backward compatibility
+- **Algorithm parameter**: Explicit selection via enum
+- **Weight parameters**: Client-configurable, only apply to hybrid mode
+- **Validation**: Weights must sum to ≤1.0, enforced server-side
+- **Defaults**: Hybrid mode with balanced weights (semantic 50%, keyword 30%, fuzzy 20%)
+
+### 3. Shared Algorithm Implementation
+
+Extract search algorithms into reusable module:
+
+```
+nextcloud_mcp_server/
+├── search/
+│   ├── __init__.py
+│   ├── algorithms.py          # Core search implementations
+│   ├── semantic.py             # Vector similarity search
+│   ├── keyword.py              # Token-based search (ADR-001)
+│   ├── fuzzy.py                # Character overlap search
+│   └── hybrid.py               # RRF fusion (ADR-003)
+└── server/
+    └── semantic.py             # MCP tool wrapper
+```
+
+**Benefits**:
+- Viz pane and MCP tools share identical implementations
+- Testable in isolation
+- Easy to add new algorithms (e.g., BM25, neural reranking)
+- Clear separation of concerns
+
+### 4. Viz Pane Integration
+
+Update viz pane (`nextcloud_mcp_server/auth/userinfo_routes.py`) to:
+
+1. **Use shared algorithms**: Import from `search/algorithms.py`
+2. **Server-side filtering**: All search and filtering operations happen server-side
+   - Query execution via shared search backend
+   - Document type filtering (notes, files, calendar, contacts)
+   - User ID filtering for multi-tenant security
+   - Only matching results + metadata sent to client
+   - Reduces bandwidth and improves performance
+3. **PCA reduction**: Server performs dimensionality reduction (768-dim → 2D)
+   - Only 2D coordinates sent to browser for visualization
+   - Dramatically reduces data transfer vs sending full vectors
+   - Enables visualization of large document collections
+4. **User accessibility**: Available to all users with vector sync enabled
+5. **Security**: Filter results by `user_id` (only show user's own documents)
+6. **Interactive testing**: Allow users to:
+   - Select algorithm type
+   - Adjust weights (hybrid mode)
+   - Compare results across algorithms
+   - Visualize result distribution in 2D space
+
+#### Viz Pane UI Components
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│ Vector Visualization                                          [Status] │
+├────────────────────────────────────────────────────────────────────────┤
+│                                                                        │
+│ ┌──────────────────────────────────────────────────────────────────┐  │
+│ │ Search Configuration                                             │  │
+│ │                                                                  │  │
+│ │ Query: [_______________________________________________] [Search]│  │
+│ │                                                                  │  │
+│ │ Algorithm: [Hybrid ▼]  [Semantic] [Keyword] [Fuzzy]             │  │
+│ │                                                                  │  │
+│ │ Weights (Hybrid Mode):                                           │  │
+│ │   Semantic: [========50========] 0.5                             │  │
+│ │   Keyword:  [======30======    ] 0.3                             │  │
+│ │   Fuzzy:    [====20====        ] 0.2                             │  │
+│ │                                                                  │  │
+│ │ Document Types: ☑ Notes  ☑ Files  ☑ Calendar  ☑ Contacts        │  │
+│ └──────────────────────────────────────────────────────────────────┘  │
+│                                                                        │
+│ ┌──────────────────────────────────────────────────────────────────┐  │
+│ │ Vector Space Visualization (PCA 2D Projection)                   │  │
+│ │                                                                  │  │
+│ │        ▲                                                         │  │
+│ │    PC2 │     ●  ● ●      🔵 Matching results (full opacity)     │  │
+│ │        │  ●     ●  ●     ⚪ Non-matching results (40% opacity)   │  │
+│ │        │    🔵  ● ●                                              │  │
+│ │        │  ●  🔵  ●       Hover: Show document title + excerpt    │  │
+│ │        │  ● ●  🔵 ●      Click: Open document in Nextcloud       │  │
+│ │    ────┼──●─🔵──●─●────► PC1                                     │  │
+│ │        │   ● ●  ●                                                │  │
+│ │        │    🔵 ●   ●     Explained Variance:                     │  │
+│ │        │  ●    ●  ●      PC1: 23.4% | PC2: 18.7%                 │  │
+│ │        │     ● ●                                                 │  │
+│ │                                                                  │  │
+│ └──────────────────────────────────────────────────────────────────┘  │
+│                                                                        │
+│ ┌──────────────────────────────────────────────────────────────────┐  │
+│ │ Search Results (12 matching documents)                           │  │
+│ │                                                                  │  │
+│ │ 🔵 Kubernetes Setup Guide                        Score: 0.87     │  │
+│ │    "...configure kubectl to connect to cluster..."              │  │
+│ │    [Open in Nextcloud]                                           │  │
+│ │                                                                  │  │
+│ │ 🔵 Container Orchestration Notes                 Score: 0.82     │  │
+│ │    "...deployment strategies for kubernetes..."                 │  │
+│ │    [Open in Nextcloud]                                           │  │
+│ │                                                                  │  │
+│ │ 🔵 K8s Troubleshooting                           Score: 0.79     │  │
+│ │    "...common kuberntes errors and solutions..."                │  │
+│ │    [Open in Nextcloud]                                           │  │
+│ │                                                                  │  │
+│ │ [Show More Results...]                                           │  │
+│ └──────────────────────────────────────────────────────────────────┘  │
+│                                                                        │
+│ ┌──────────────────────────────────────────────────────────────────┐  │
+│ │ Algorithm Performance Comparison                                 │  │
+│ │                                                                  │  │
+│ │ Algorithm    │ Results │ Avg Score │ Time (ms) │ Precision     │  │
+│ │ ─────────────┼─────────┼───────────┼───────────┼───────────     │  │
+│ │ Semantic     │   45    │   0.78    │   145ms   │  ████░ 0.82   │  │
+│ │ Keyword      │   23    │   0.91    │    42ms   │  ███░░ 0.67   │  │
+│ │ Fuzzy        │   67    │   0.72    │    89ms   │  ██░░░ 0.45   │  │
+│ │ Hybrid (RRF) │   52    │   0.84    │   198ms   │  █████ 0.89   │  │
+│ └──────────────────────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+**Key UI Features**:
+
+1. **Search Input**: Real-time query testing with instant visualization
+2. **Algorithm Selector**: Dropdown + quick-select buttons
+3. **Weight Sliders**: Visual adjustment with live preview (hybrid mode only)
+4. **Document Type Filters**: Checkboxes for notes, files, calendar, contacts
+5. **2D Scatter Plot**: Interactive Plotly.js visualization
+   - Blue dots = matching documents (full opacity)
+   - Gray dots = non-matching documents (40% opacity)
+   - Hover = show title + excerpt tooltip
+   - Click = open document in Nextcloud
+   - Zoom/pan controls for exploration
+6. **Results Panel**: Ranked list with scores and excerpts
+7. **Performance Table**: Compare algorithm speed and accuracy
+8. **Explained Variance**: Show how much information PCA preserves
+
+**Technology Stack**:
+- **Frontend**: htmx for dynamic loading, Alpine.js for reactivity
+- **Visualization**: Plotly.js for interactive scatter plots
+- **Styling**: Tailwind CSS (consistent with existing /app UI)
+- **Backend**: Shared `search/algorithms.py` implementation
+
+### 5. Reciprocal Rank Fusion (RRF) for Hybrid Search
+
+Following ADR-003's design:
+
+```python
+def reciprocal_rank_fusion(
+    results: dict[str, list[SearchResult]],
+    weights: dict[str, float],
+    k: int = 60
+) -> list[SearchResult]:
+    """
+    Combine multiple ranked result lists using RRF.
+
+    Args:
+        results: Dict of algorithm_name -> ranked results
+        weights: Dict of algorithm_name -> weight (0-1)
+        k: RRF constant (default: 60, standard value)
+
+    Returns:
+        Combined and re-ranked results
+    """
+    scores = defaultdict(float)
+
+    for algo_name, algo_results in results.items():
+        weight = weights.get(algo_name, 0.0)
+        for rank, result in enumerate(algo_results, start=1):
+            # RRF formula: 1 / (k + rank)
+            rrf_score = weight / (k + rank)
+            scores[result.doc_id] += rrf_score
+
+    # Sort by combined score, return top results
+    return sorted(scores.items(), key=lambda x: x[1], reverse=True)
+```
+
+**RRF properties**:
+- **Rank-based**: Uses position, not raw scores (handles score scale differences)
+- **Proven effective**: Standard approach in information retrieval
+- **Configurable**: `k` parameter controls rank decay (default: 60)
+- **Weight support**: Allows algorithm-specific importance
+
+## Implementation Plan
+
+### Phase 1: Extract and Unify Algorithms (Week 1)
+
+1. Create `nextcloud_mcp_server/search/` module
+2. Implement `algorithms.py` with base interface
+3. Extract semantic search logic from `server/semantic.py`
+4. Implement keyword search from ADR-001 design
+5. Extract fuzzy search from viz pane
+6. Implement RRF hybrid search from ADR-003
+7. Add comprehensive unit tests for each algorithm
+
+### Phase 2: Update MCP Tool (Week 1-2)
+
+1. Add `algorithm` parameter to `nc_semantic_search()`
+2. Add weight parameters (`semantic_weight`, etc.)
+3. Implement algorithm dispatcher
+4. Add parameter validation (weights sum ≤1.0)
+5. Update response model to include algorithm metadata
+6. Maintain backward compatibility (default: hybrid)
+7. Add integration tests for all algorithm modes
+
+### Phase 3: Update Viz Pane (Week 2)
+
+**Critical: All processing must happen server-side**
+
+1. **Remove client-side search filtering**
+   - Delete JavaScript-based keyword/fuzzy matching
+   - Remove client-side document type filtering
+   - No search logic in browser
+2. **Implement server-side endpoint** (`/app/vector-viz`)
+   - Accept query, algorithm, weights, doc_type filters
+   - Execute search via `search/algorithms.py`
+   - Filter results by user_id (security)
+   - Perform PCA reduction (768-dim → 2D)
+   - Return JSON with 2D coordinates + metadata only
+3. **Update frontend**
+   - htmx form submission to `/app/vector-viz`
+   - Algorithm selector dropdown
+   - Weight adjustment sliders (htmx updates on change)
+   - Document type checkboxes
+   - Plotly.js visualization of server response
+4. **Performance optimization**
+   - Limit results to user's documents only
+   - Cache PCA transformation (invalidate on new vectors)
+   - Stream large result sets if needed
+   - Add loading indicators for server processing
+
+### Phase 4: Documentation and Testing (Week 2-3)
+
+1. Update MCP tool documentation
+2. Add algorithm selection guide
+3. Document weight tuning recommendations
+4. Add end-to-end tests (MCP + viz pane)
+5. Performance benchmarks for each algorithm
+6. Update CLAUDE.md with search patterns
+
+## Consequences
+
+### Positive
+
+1. **Flexibility**: MCP clients can optimize search for their use case
+2. **Unified implementation**: Single source of truth for search algorithms
+3. **User empowerment**: Viz pane enables query testing and tuning
+4. **Backward compatible**: Existing semantic search behavior preserved
+5. **Extensible**: Easy to add new algorithms (BM25, neural reranking)
+6. **Testable**: Each algorithm can be unit tested independently
+7. **Standards-based**: RRF is proven in production systems
+
+### Negative
+
+1. **Complexity**: More parameters for clients to understand
+2. **API surface**: Larger tool signature (8 parameters)
+3. **Performance**: Hybrid search requires multiple queries
+4. **Validation overhead**: Weight validation adds processing
+5. **Documentation burden**: Need to explain when to use each algorithm
+
+### Neutral
+
+1. **Weight defaults**: May need tuning based on user feedback
+2. **Algorithm performance**: Will vary by content type and query
+3. **Viz pane adoption**: Unknown if users will utilize testing interface
+
+## Alternatives Considered
+
+### Alternative 1: Separate Tools Per Algorithm
+
+```python
+@mcp.tool()
+async def nc_semantic_search(query: str, ctx: Context, ...) -> SearchResponse:
+    """Pure vector similarity search."""
+
+@mcp.tool()
+async def nc_keyword_search(query: str, ctx: Context, ...) -> SearchResponse:
+    """Pure keyword matching."""
+
+@mcp.tool()
+async def nc_hybrid_search(query: str, ctx: Context, weights: dict, ...) -> SearchResponse:
+    """Hybrid search with weights."""
+```
+
+**Rejected because**:
+- API proliferation (3+ tools instead of 1)
+- Harder to discover capabilities
+- Backward compatibility issues
+- DRY violation (repeated parameters)
+
+### Alternative 2: Server-Wide Configuration Only
+
+```python
+# .env configuration
+SEARCH_ALGORITHM=hybrid
+SEMANTIC_WEIGHT=0.5
+KEYWORD_WEIGHT=0.3
+FUZZY_WEIGHT=0.2
+```
+
+**Rejected because**:
+- No per-query flexibility
+- MCP clients cannot optimize for different tasks
+- Requires server restart for changes
+- User's requirement: "expose a way for users to override the default weights"
+
+### Alternative 3: Production-Grade Fuzzy (Levenshtein/RapidFuzz)
+
+**Rejected because**:
+- Adds external dependency
+- Simple character overlap performs adequately
+- Can always upgrade later if needed
+- User's preference: "Keep simple character overlap"
+
+## Related ADRs
+
+- **ADR-001**: Enhanced Note Search (keyword algorithm design)
+- **ADR-003**: Vector Database and Semantic Search (hybrid search + RRF design)
+- **ADR-007**: Background Vector Sync (semantic search implementation)
+- **ADR-008**: MCP Sampling for RAG (uses semantic search results)
+- **ADR-009**: Semantic Search OAuth Scope (security model)
+- **ADR-011**: Improving Semantic Search Quality (mentions future "ADR-013" for hybrid search)
+
+**This ADR supersedes**:
+- ADR-011's placeholder for "ADR-013: Hybrid Search"
+
+**This ADR implements**:
+- ADR-003's hybrid search design (previously unimplemented)
+- ADR-001's keyword search design (previously unimplemented)
+
+## References
+
+- **Reciprocal Rank Fusion**: Cormack, G. V., Clarke, C. L., & Buettcher, S. (2009). "Reciprocal rank fusion outperforms condorcet and individual rank learning methods." SIGIR '09.
+- **Vector Search**: Malkov, Y. A., & Yashunin, D. A. (2018). "Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs." TPAMI.
+- **Hybrid Search Best Practices**: Qdrant documentation on hybrid search patterns
+- **MCP Protocol**: Model Context Protocol specification for tool design
+
+## Implementation Notes
+
+### Weight Validation
+
+```python
+def validate_weights(
+    semantic_weight: float,
+    keyword_weight: float,
+    fuzzy_weight: float
+) -> None:
+    """Validate hybrid search weights."""
+    if semantic_weight < 0 or keyword_weight < 0 or fuzzy_weight < 0:
+        raise ValueError("Weights must be non-negative")
+
+    total = semantic_weight + keyword_weight + fuzzy_weight
+    if total > 1.0:
+        raise ValueError(f"Weights sum to {total:.2f}, must be ≤1.0")
+
+    if total == 0.0:
+        raise ValueError("At least one weight must be > 0")
+```
+
+### Backward Compatibility
+
+The default behavior (`algorithm="hybrid"` with balanced weights) provides better results than current pure semantic search, while maintaining the same tool name and signature structure. Existing clients will automatically benefit from hybrid search without code changes.
+
+### Performance Considerations
+
+- **Semantic search**: ~50-200ms (vector DB query)
+- **Keyword search**: ~10-50ms (in-memory token matching)
+- **Fuzzy search**: ~20-100ms (character comparison)
+- **Hybrid search**: ~100-300ms (parallel execution + fusion)
+
+Parallel execution of algorithms minimizes hybrid search latency.
+
+### Security Model
+
+All algorithms respect the same security boundaries:
+1. **User filtering**: Qdrant queries filter by `user_id`
+2. **Access verification**: Results verified via Nextcloud API
+3. **OAuth scope**: `semantic:read` required for all algorithms
+4. **Viz pane**: Shows only current user's documents
+
+## Success Metrics
+
+1. **Adoption**: % of MCP clients using algorithm parameter
+2. **Performance**: Search latency percentiles (p50, p95, p99)
+3. **Quality**: User satisfaction with result relevance
+4. **Viz pane usage**: % of users accessing testing interface
+5. **Weight distribution**: Most common weight configurations
+
+## Future Enhancements
+
+1. **Additional algorithms**: BM25, TF-IDF, neural reranking
+2. **Auto-tuning**: Learn optimal weights per user
+3. **Query analysis**: Automatic algorithm selection based on query
+4. **Cross-app search**: Extend beyond notes to calendar, files, etc.
+5. **Feedback loop**: Use click-through rate to improve weights

docs/CRITICAL-TOKEN-EXCHANGE-PATTERN.md

@@ -0,0 +1,348 @@
+# Token Acquisition Patterns for ADR-004 Progressive Consent
+
+## Overview
+
+ADR-004 Progressive Consent establishes the authorization architecture (Flow 1 for client auth, Flow 2 for resource provisioning). This document describes **how tokens are acquired for different operational contexts** within that architecture.
+
+**Key Principle**: Refresh tokens from Flow 2 (Progressive Consent) should **NEVER** be used for MCP tool calls - they are exclusively for background jobs.
+
+## Implementation Status
+
+**Current Status**: ✅ Token exchange infrastructure implemented, available as opt-in feature
+
+The MCP server supports two token acquisition modes:
+1. **Pass-through mode** (default, `ENABLE_TOKEN_EXCHANGE=false`): Simple, stateless
+2. **Token exchange mode** (opt-in, `ENABLE_TOKEN_EXCHANGE=true`): Enhanced security with token delegation
+
+Both modes maintain the critical separation: **refresh tokens are never used for tool calls**.
+
+## Current Default (Pass-Through Mode)
+
+### What Happens (ENABLE_TOKEN_EXCHANGE=false):
+1. Client gets Flow 1 token (`aud: "mcp-server"`)
+2. Client calls MCP tool
+3. Server validates Flow 1 token
+4. Server passes Flow 1 token to Nextcloud
+5. Nextcloud validates token with IdP
+6. Refresh tokens (from Flow 2) used **only** for background jobs
+
+### Characteristics:
+- ✅ Simple, stateless operation
+- ✅ Clear separation: Flow 1 tokens for sessions, refresh tokens for background
+- ✅ Lower latency (no token exchange round-trip)
+- ✅ Works with any OAuth IdP
+
+## Optional Token Exchange Mode
+
+### Token Exchange Pattern (ENABLE_TOKEN_EXCHANGE=true)
+
+**MCP Session (Foreground Operations)**:
+
+```
+┌─────────────┐     Flow 1 Token      ┌──────────────┐
+│  MCP Client │ ───(aud: mcp-server)──> │  MCP Server  │
+└─────────────┘                        └──────────────┘
+                                              │
+                    Tool Call                 │
+                    "search_notes()"          │
+                                              ▼
+                                    ┌─────────────────────┐
+                                    │ Token Exchange      │
+                                    │ 1. Validate Flow 1  │
+                                    │ 2. Check permission │
+                                    │ 3. Request delegated│
+                                    │    Nextcloud token  │
+                                    └─────────────────────┘
+                                              │
+                                              │ Exchange Request
+                                              ▼
+                                    ┌─────────────────────┐
+                                    │ IdP Token Endpoint  │
+                                    │ (Token Exchange)    │
+                                    └─────────────────────┘
+                                              │
+                                              │ Delegated Token
+                                              │ (aud: nextcloud)
+                                              │ (limited scopes)
+                                              │ (short-lived)
+                                              ▼
+                                    ┌─────────────────────┐
+                                    │ Nextcloud API Call  │
+                                    │ GET /notes          │
+                                    └─────────────────────┘
+```
+
+**Key Properties of Session Tokens:**
+- ✅ Generated **on-demand** during tool execution
+- ✅ **Ephemeral** - used only for current operation
+- ✅ **NOT stored** - discarded after use
+- ✅ **Limited scopes** - only what tool needs (e.g., `notes:read` for search)
+- ✅ **Short-lived** - expires quickly (e.g., 5 minutes)
+
+**Background Jobs (Offline Operations)**:
+
+```
+┌─────────────────┐     Scheduled Job      ┌──────────────┐
+│ Background      │ ──────────────────────> │  Worker      │
+│ Scheduler       │                         │  Process     │
+└─────────────────┘                         └──────────────┘
+                                                    │
+                                                    │ Use stored
+                                                    │ refresh token
+                                                    ▼
+                                          ┌─────────────────────┐
+                                          │ Refresh Token Store │
+                                          │ (Flow 2 provisioned)│
+                                          └─────────────────────┘
+                                                    │
+                                                    │ Refresh Token
+                                                    ▼
+                                          ┌─────────────────────┐
+                                          │ IdP Token Endpoint  │
+                                          │ (Refresh Grant)     │
+                                          └─────────────────────┘
+                                                    │
+                                                    │ Background Token
+                                                    │ (aud: nextcloud)
+                                                    │ (different scopes)
+                                                    │ (longer-lived)
+                                                    ▼
+                                          ┌─────────────────────┐
+                                          │ Nextcloud API       │
+                                          │ (Background Sync)   │
+                                          └─────────────────────┘
+```
+
+**Key Properties of Background Tokens:**
+- ✅ Obtained from **stored refresh token** (Flow 2)
+- ✅ **Different scopes** than session tokens (e.g., `notes:sync`, `files:sync`)
+- ✅ **Longer-lived** for background operations
+- ✅ **Never used for MCP sessions**
+- ✅ **Only for offline/background jobs**
+
+## Implementation Requirements
+
+### 1. Token Exchange Endpoint
+
+Implement RFC 8693 Token Exchange:
+
+```python
+# nextcloud_mcp_server/auth/token_exchange.py
+
+async def exchange_token_for_delegation(
+    flow1_token: str,
+    requested_audience: str = "nextcloud",
+    requested_scopes: list[str] | None = None
+) -> tuple[str, int]:
+    """
+    Exchange Flow 1 MCP token for delegated Nextcloud token.
+
+    This implements RFC 8693 Token Exchange for on-behalf-of delegation.
+
+    IMPORTANT: Nextcloud doesn't support OAuth scopes natively. Scopes are
+    soft-scopes enforced by the MCP server via @require_scopes decorator,
+    not by the IdP or Nextcloud. Therefore, requested_scopes are not passed
+    to the IdP during token exchange.
+
+    Args:
+        flow1_token: The MCP session token (aud: "mcp-server")
+        requested_audience: Target audience (usually "nextcloud")
+        requested_scopes: Ignored (Nextcloud doesn't support scopes)
+
+    Returns:
+        Tuple of (delegated_token, expires_in)
+    """
+    # 1. Validate Flow 1 token (audience check)
+    # 2. Check user has provisioned Nextcloud access (Flow 2)
+    # 3. Request token exchange from IdP (without scopes - Nextcloud doesn't support them)
+    # 4. Return ephemeral delegated token
+```
+
+### 2. Unified get_client() Pattern
+
+The token acquisition mode is handled transparently by `get_client()`:
+
+```python
+# nextcloud_mcp_server/context.py
+
+async def get_client(ctx: Context) -> NextcloudClient:
+    """
+    Get the appropriate Nextcloud client based on authentication mode.
+
+    This function handles three modes:
+    1. BasicAuth mode: Returns shared client from lifespan context
+    2. OAuth pass-through mode (ENABLE_TOKEN_EXCHANGE=false, default):
+       Verifies Flow 1 token and passes it to Nextcloud
+    3. OAuth token exchange mode (ENABLE_TOKEN_EXCHANGE=true):
+       Exchanges Flow 1 token for ephemeral Nextcloud token via RFC 8693
+    """
+    settings = get_settings()
+    lifespan_ctx = ctx.request_context.lifespan_context
+
+    # BasicAuth mode - use shared client (no token exchange)
+    if hasattr(lifespan_ctx, "client"):
+        return lifespan_ctx.client
+
+    # OAuth mode (has 'nextcloud_host' attribute)
+    if hasattr(lifespan_ctx, "nextcloud_host"):
+        # Check if token exchange is enabled
+        if settings.enable_token_exchange:
+            # Token exchange mode: Exchange Flow 1 token for ephemeral Nextcloud token
+            return await get_session_client_from_context(
+                ctx, lifespan_ctx.nextcloud_host
+            )
+        else:
+            # Pass-through mode (default): Verify and pass Flow 1 token to Nextcloud
+            return get_client_from_context(ctx, lifespan_ctx.nextcloud_host)
+```
+
+### 3. MCP Tool Pattern (No Changes Required!)
+
+Tools use the same pattern regardless of token acquisition mode:
+
+```python
+@mcp.tool()
+@require_scopes("notes:read")  # Soft-scope enforced by MCP server, not Nextcloud
+@require_provisioning
+async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
+    """Search notes by title or content."""
+
+    # get_client() handles both pass-through and token exchange modes
+    client = await get_client(ctx)
+
+    # Execute operation
+    results = await client.notes.search_notes(query=query)
+
+    # In token exchange mode, ephemeral token is automatically discarded
+    # In pass-through mode, Flow 1 token was validated and passed through
+    return SearchNotesResponse(results=results)
+```
+
+**Key Benefit**: Tools don't need to know which mode is active. The token acquisition pattern is configured at the server level via `ENABLE_TOKEN_EXCHANGE`.
+
+### 4. Background Job Pattern
+
+Background jobs use a **different token acquisition pattern** - they use refresh tokens from Flow 2:
+
+```python
+# Background worker
+async def sync_notes_job(user_id: str):
+    """Background job to sync notes."""
+
+    # Get refresh token stored during Flow 2 (Progressive Consent)
+    token_storage = get_token_storage()
+    refresh_token = await token_storage.get_refresh_token(user_id)
+
+    if not refresh_token:
+        logger.warning(f"No refresh token for user {user_id}")
+        return
+
+    # Use refresh token to get Nextcloud access token
+    idp_client = get_idp_client()
+    response = await idp_client.refresh_token(
+        refresh_token=refresh_token,
+        audience='nextcloud'
+    )
+
+    # Create client with background token (can be cached)
+    client = NextcloudClient.from_token(
+        base_url=NEXTCLOUD_HOST,
+        token=response.access_token,
+        username=user_id
+    )
+
+    # Perform background sync
+    await client.notes.sync_all()
+```
+
+**Key differences from tool calls:**
+- Uses refresh tokens from Flow 2 (Progressive Consent provisioning)
+- Tokens can be cached for efficiency (longer-lived operations)
+- No user interaction possible (offline)
+- Never triggered during MCP tool execution
+
+## Security Benefits
+
+### Proper Token Exchange:
+1. ✅ **Least Privilege**: Each operation gets only needed scopes
+2. ✅ **Time-Limited**: Session tokens expire quickly
+3. ✅ **Audit Trail**: Each exchange can be logged
+4. ✅ **Token Isolation**: Session ≠ Background tokens
+5. ✅ **Revocation**: Can revoke background access without affecting active sessions
+
+### Current Incorrect Pattern:
+1. ❌ **Over-Privileged**: Refresh token has all scopes
+2. ❌ **Long-Lived**: Same token reused indefinitely
+3. ❌ **No Separation**: Sessions and background jobs use same credential
+4. ❌ **Revocation Issues**: Revoking affects everything
+
+## Implementation Steps
+
+### Phase 1: Token Exchange (High Priority)
+1. Implement RFC 8693 token exchange endpoint
+2. Update Token Broker with `get_session_token()` vs `get_background_token()`
+3. Modify tool pattern to use token exchange
+
+### Phase 2: Scope Separation (High Priority)
+1. Define session scopes vs background scopes
+2. Update provisioning flow to request appropriate scopes
+3. Validate scopes in token exchange
+
+### Phase 3: Background Jobs (Medium Priority)
+1. Implement background worker pattern
+2. Create scheduled jobs (note sync, etc.)
+3. Use background token pattern
+
+### Phase 4: Testing (High Priority)
+1. Test token exchange flow end-to-end
+2. Verify session tokens are ephemeral
+3. Verify background tokens are separate
+4. Load test token exchange performance
+
+## References
+
+- **RFC 8693**: OAuth 2.0 Token Exchange
+- **RFC 9068**: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
+- **ADR-004**: Progressive Consent OAuth Flows
+- **OAuth 2.0 Delegation**: On-Behalf-Of vs Impersonation patterns
+
+## Status
+
+**Current Status**: ✅ Token exchange infrastructure implemented, available as opt-in feature
+**Modes Available**:
+- ✅ Pass-through mode (default, `ENABLE_TOKEN_EXCHANGE=false`): Simple, stateless
+- ✅ Token exchange mode (opt-in, `ENABLE_TOKEN_EXCHANGE=true`): Enhanced security
+
+**Implementation Complete**:
+- ✅ `token_exchange.py` module with RFC 8693 support
+- ✅ Fallback to refresh grant when RFC 8693 not supported
+- ✅ `get_client()` unified pattern (handles both modes transparently)
+- ✅ Tokens never cached in token exchange mode (ephemeral)
+- ✅ Background jobs use separate pattern (refresh tokens from Flow 2)
+
+## Configuration
+
+To enable token exchange mode:
+
+```bash
+# docker-compose.yml or .env
+ENABLE_TOKEN_EXCHANGE=true
+```
+
+When enabled, all MCP tool calls will use token exchange (RFC 8693) to obtain ephemeral Nextcloud tokens. When disabled (default), Flow 1 tokens are passed through to Nextcloud.
+
+## Nextcloud Scope Limitation
+
+**IMPORTANT**: Nextcloud does not support OAuth scopes natively. Scopes like "notes:read" are **soft-scopes** enforced by the MCP server via `@require_scopes` decorator, not by the IdP or Nextcloud.
+
+This means:
+- Token exchange provides audit and delegation benefits, not scope restriction
+- All Nextcloud tokens have equivalent permissions at the Nextcloud level
+- Fine-grained access control is enforced by MCP server, not Nextcloud
+
+## Next Actions (Optional Enhancements)
+
+1. [ ] Add integration tests for token exchange mode with actual MCP tools
+2. [ ] Document background job patterns for scheduled sync operations
+3. [ ] Add metrics for token exchange performance
+4. [ ] Consider making token exchange the default in future major version

docs/audience-validation-setup.md

@@ -0,0 +1,521 @@
+# Audience Validation Setup
+
+## Overview
+
+This document explains the **separate clients architecture** for Keycloak → MCP Server → Nextcloud integration, following OAuth 2.0 best practices and RFC 8707 (Resource Indicators).
+
+## Architecture: Separate Clients Pattern
+
+```
+Keycloak Realm: nextcloud-mcp
+├── Client: "nextcloud" (Resource Server)
+│   └── Represents Nextcloud as a protected resource
+│   └── Used by user_oidc for bearer token validation
+│   └── Validates tokens with aud="nextcloud"
+│
+└── Client: "nextcloud-mcp-server" (OAuth Client)
+    └── MCP Server uses this to REQUEST tokens
+    └── Issues tokens with aud="nextcloud" (targeting resource)
+    └── Future: aud=["nextcloud", "other-service"]
+
+Token Flow:
+MCP Server (client: nextcloud-mcp-server)
+  ↓ requests token from Keycloak
+Token issued:
+  - aud: "nextcloud"             (intended for Nextcloud resource)
+  - azp: "nextcloud-mcp-server"  (requested by MCP Server)
+  - preferred_username: "admin"  (on behalf of user)
+  ↓ sent to Nextcloud API
+Nextcloud user_oidc (client: nextcloud)
+  ✓ validates aud matches configured client_id
+```
+
+**Key Benefits**:
+- ✅ **Proper OAuth separation**: OAuth client ≠ resource server
+- ✅ **Future extensibility**: MCP Server can request multi-resource tokens
+- ✅ **RFC 8707 compliance**: Audience indicates intended resource
+- ✅ **Clear requester identification**: azp claim identifies MCP Server
+
+## Token Claims
+
+Tokens issued by the `nextcloud-mcp-server` client contain:
+
+- **`aud: "nextcloud"`** - Audience: Token intended for Nextcloud resource server (matches user_oidc client_id)
+- **`azp: "nextcloud-mcp-server"`** - Authorized Party: Identifies MCP Server as the OAuth client that requested the token
+- **`preferred_username: "admin"`** - User identifier (Keycloak uses this for password grant; `sub` for authorization_code grant)
+- **`scope: "openid profile email offline_access"`** - Requested scopes including offline access for background jobs
+
+**How user_oidc Validates**:
+1. SelfEncodedValidator checks: `aud == user_oidc.client_id`?
+   - ✓ "nextcloud" == "nextcloud" → PASS
+2. Fast JWT verification with JWKS (no HTTP call to userinfo endpoint)
+3. User provisioned based on `preferred_username` or `sub` claim
+
+**For Background Jobs**:
+- MCP Server stores encrypted refresh tokens
+- Refreshes access tokens when needed
+- All tokens have `aud: "nextcloud"` → validated by user_oidc
+- No admin credentials required
+
+## Configuration
+
+The configuration requires **two separate clients** in Keycloak:
+
+1. **`nextcloud`** - Resource server client (for user_oidc validation)
+2. **`nextcloud-mcp-server`** - OAuth client (for MCP Server to request tokens)
+
+### 1. Keycloak - Create Resource Server Client
+
+First, create the `nextcloud` client that represents Nextcloud as a resource server:
+
+**Via Keycloak Admin API:**
+
+```bash
+# Get admin token
+ADMIN_TOKEN=$(curl -X POST "http://localhost:8888/realms/master/protocol/openid-connect/token" \
+  -d "grant_type=password" \
+  -d "client_id=admin-cli" \
+  -d "username=admin" \
+  -d "password=admin" | jq -r '.access_token')
+
+# Create 'nextcloud' resource server client
+curl -X POST "http://localhost:8888/admin/realms/nextcloud-mcp/clients" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "nextcloud",
+    "name": "Nextcloud Resource Server",
+    "description": "Resource server for Nextcloud APIs - used by user_oidc for bearer token validation",
+    "enabled": true,
+    "clientAuthenticatorType": "client-secret",
+    "secret": "nextcloud-secret-change-in-production",
+    "bearerOnly": true,
+    "standardFlowEnabled": false,
+    "directAccessGrantsEnabled": false,
+    "serviceAccountsEnabled": false,
+    "publicClient": false
+  }'
+```
+
+**Via Realm Export** (`keycloak/realm-export.json`):
+
+```json
+{
+  "clients": [
+    {
+      "clientId": "nextcloud",
+      "name": "Nextcloud Resource Server",
+      "enabled": true,
+      "bearerOnly": true,
+      "secret": "nextcloud-secret-change-in-production"
+    }
+  ]
+}
+```
+
+### 2. Keycloak - Create OAuth Client with Audience Mapper
+
+Next, create the `nextcloud-mcp-server` client that MCP Server uses to request tokens:
+
+**Via Keycloak Admin API:**
+
+```bash
+# Create 'nextcloud-mcp-server' OAuth client
+curl -X POST "http://localhost:8888/admin/realms/nextcloud-mcp/clients" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "nextcloud-mcp-server",
+    "name": "Nextcloud MCP Server",
+    "enabled": true,
+    "clientAuthenticatorType": "client-secret",
+    "secret": "mcp-secret-change-in-production",
+    "standardFlowEnabled": true,
+    "directAccessGrantsEnabled": true,
+    "redirectUris": ["http://localhost:*/callback"]
+  }'
+
+# Get client internal ID
+CLIENT_ID=$(curl "http://localhost:8888/admin/realms/nextcloud-mcp/clients" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" | jq -r '.[] | select(.clientId=="nextcloud-mcp-server") | .id')
+
+# Add audience mapper targeting 'nextcloud' resource
+curl -X POST "http://localhost:8888/admin/realms/nextcloud-mcp/clients/$CLIENT_ID/protocol-mappers/models" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "audience-nextcloud",
+    "protocol": "openid-connect",
+    "protocolMapper": "oidc-audience-mapper",
+    "consentRequired": false,
+    "config": {
+      "included.custom.audience": "nextcloud",
+      "access.token.claim": "true",
+      "id.token.claim": "false"
+    }
+  }'
+```
+
+**Option B: Via Realm Export** (for infrastructure-as-code)
+
+Update `keycloak/realm-export.json`:
+
+```json
+{
+  "clients": [
+    {
+      "clientId": "nextcloud-mcp-server",
+      "name": "Nextcloud MCP Server",
+      "protocolMappers": [
+        {
+          "name": "audience-nextcloud-mcp-server",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-audience-mapper",
+          "consentRequired": false,
+          "config": {
+            "included.custom.audience": "nextcloud-mcp-server",
+            "access.token.claim": "true",
+            "id.token.claim": "false"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Then re-import realm or restart Keycloak.
+
+**Option C: Via Keycloak Admin UI**
+
+1. Go to Keycloak Admin Console → Realm → Clients → `nextcloud-mcp-server`
+2. Click "Client scopes" tab
+3. Click "Add client scope" → "Create dedicated scope"
+4. Add protocol mapper: "Audience"
+   - Mapper Type: `Audience`
+   - Included Custom Audience: `nextcloud`
+   - Add to access token: ON
+   - Add to ID token: OFF
+
+### 3. Nextcloud user_oidc - Configure Resource Server Client
+
+Configure user_oidc to use the `nextcloud` resource server client:
+
+```bash
+docker compose exec app php occ user_oidc:provider keycloak \
+  --clientid="nextcloud" \
+  --clientsecret="nextcloud-secret-change-in-production" \
+  --discoveryuri="http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration" \
+  --check-bearer=1 \
+  --bearer-provisioning=1 \
+  --unique-uid=1 \
+  --mapping-uid="sub" \
+  --mapping-display-name="name" \
+  --mapping-email="email"
+```
+
+**Result**: user_oidc validates tokens with `aud="nextcloud"` using SelfEncodedValidator (fast JWT verification).
+
+### 3. Nextcloud user_oidc - Realm-Level Validation
+
+Nextcloud's `user_oidc` app validates at **realm level** via userinfo endpoint:
+
+- ✅ **No configuration needed** - works automatically
+- ✅ Validates any token from Keycloak realm
+- ✅ Audience check is **optional** (disabled by default)
+
+**Optional: Disable strict audience checking** (if enabled):
+
+```bash
+docker compose exec app php occ config:app:set user_oidc \
+  selfencoded_bearer_validation_audience_check --value=false --type=boolean
+```
+
+## Verification
+
+### 1. Check Token Claims
+
+```bash
+# Get token from Keycloak
+TOKEN=$(curl -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
+  -d "grant_type=password" \
+  -d "client_id=nextcloud-mcp-server" \
+  -d "client_secret=mcp-secret-change-in-production" \
+  -d "username=admin" \
+  -d "password=admin" | jq -r '.access_token')
+
+# Decode JWT
+echo $TOKEN | cut -d'.' -f2 | base64 -d | jq '.'
+
+# Should show:
+{
+  "aud": "nextcloud",  # ✓ Intended for Nextcloud
+  "azp": "nextcloud-mcp-server",  # ✓ Requested by MCP Server
+  "iss": "http://localhost:8888/realms/nextcloud-mcp",
+  "scope": "openid email profile offline_access",
+  ...
+}
+```
+
+### 2. Test with Nextcloud API
+
+```bash
+# Token should be accepted
+curl -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:8080/ocs/v2.php/cloud/capabilities"
+
+# Should return HTTP 200 OK
+```
+
+### 3. Test Audience Rejection
+
+```bash
+# Get token from different client (without audience mappers)
+TOKEN_WRONG=$(curl -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
+  -d "grant_type=password" \
+  -d "client_id=test-client-b" \
+  -d "client_secret=test-secret-b" \
+  -d "username=admin" \
+  -d "password=admin" | jq -r '.access_token')
+
+# This token has NO audience claim - should be rejected by MCP server
+# (But accepted by Nextcloud user_oidc which validates at realm level)
+```
+
+## Token Flow Example
+
+### Successful Request (Background Job)
+
+```
+1. User authorizes MCP Client via OAuth
+   └─ MCP Server gets refresh token (stored encrypted)
+
+2. Background worker needs to sync data
+   └─ MCP Server refreshes access token from Keycloak
+   └─ Token issued with aud: "nextcloud", azp: "nextcloud-mcp-server"
+
+3. MCP Server → Nextcloud API (with token)
+   └─ user_oidc validates via userinfo endpoint ✓
+   └─ Nextcloud identifies:
+       - Token intended for Nextcloud (aud: "nextcloud")
+       - Request from MCP Server (azp: "nextcloud-mcp-server")
+       - On behalf of user (sub: "user-id")
+
+4. Success! MCP Server can act on behalf of user in background.
+```
+
+### Rejected Request
+
+```
+1. Attacker gets token for different client
+   └─ Token has aud: "other-service"
+
+2. Attacker → Nextcloud API (with wrong token)
+   └─ user_oidc validates via userinfo endpoint
+   └─ Token validation fails (invalid/expired/wrong realm)
+   └─ HTTP 401 Unauthorized
+
+3. Request blocked - token not valid for this realm/service
+```
+
+## OAuth Flows and User Consent
+
+### When Does the User Grant Consent?
+
+User consent happens during the **Authorization Code Flow** (production OAuth):
+
+```
+1. User clicks "Connect" in MCP Client (e.g., Claude Desktop)
+2. MCP Client initiates OAuth flow by opening browser to Keycloak:
+   https://keycloak/realms/nextcloud-mcp/protocol/openid-connect/auth?
+     client_id=nextcloud-mcp-server&
+     redirect_uri=<mcp-client-redirect-uri>&
+     response_type=code&
+     scope=openid profile email offline_access
+
+3. Keycloak shows login screen (if not logged in)
+4. **Keycloak shows consent screen:**
+   "Nextcloud MCP Server wants to access your Nextcloud data on your behalf"
+   Requested permissions:
+   - Access your profile (openid, profile, email)
+   - Offline access (background operations with refresh tokens)
+
+5. User clicks "Allow" → grants consent
+6. Keycloak redirects back to MCP Client with authorization code
+7. MCP Client exchanges code for tokens (receives access + refresh tokens)
+8. MCP Client shares tokens with MCP Server via MCP protocol
+9. MCP Server stores refresh token encrypted for background operations
+```
+
+**Key Architecture Notes:**
+- **MCP Server is a protected resource** (requires OAuth to access)
+- **MCP Client** (Claude Desktop) is the OAuth client that initiates the flow
+- **MCP Client handles the redirect** and token exchange with Keycloak
+- **MCP Client shares refresh token** with MCP Server so it can act on behalf of user in background
+
+**Key Points:**
+- ✅ **Explicit user consent** before any access
+- ✅ **Scopes displayed** so user knows what's being requested
+- ✅ **Offline access** must be explicitly granted (for background jobs)
+- ✅ **Revocable** - user can revoke consent in Keycloak at any time
+
+### Grant Types
+
+Our architecture supports multiple OAuth grant types:
+
+**1. Authorization Code + PKCE (Production)**
+```
+Use case: Interactive login from MCP clients
+Consent: Yes - explicit user authorization
+Tokens: Access token + Refresh token (if offline_access granted)
+Security: PKCE prevents authorization code interception
+```
+
+**2. Password Grant (Testing Only)**
+```
+Use case: Integration testing with docker-compose
+Consent: No - username/password provided directly
+Tokens: Access token + Refresh token
+Security: NOT for production - exposes user credentials
+```
+
+**3. Refresh Token Grant (Background Jobs)**
+```
+Use case: MCP Server refreshing expired access tokens
+Consent: No new consent - uses previously granted refresh token
+Tokens: New access token (refresh token may rotate)
+Security: Refresh tokens stored encrypted, rotated on use
+```
+
+## Authentication Strategies for Background Jobs
+
+> **Note on Service Account Tokens**: Service account tokens (`client_credentials` grant) were evaluated but **rejected** as they create Nextcloud user accounts (e.g., `service-account-{client_id}`) which violates OAuth "act on-behalf-of" principles. See ADR-002 "Will Not Implement" section for details.
+
+### Current Approach: Offline Access with Refresh Tokens
+
+The MCP server uses **offline_access** scope to enable background operations:
+
+**How it works:**
+1. User grants `offline_access` scope during OAuth consent
+2. MCP Client receives refresh token from Keycloak
+3. MCP Client shares refresh token with MCP Server via MCP protocol
+4. MCP Server stores refresh token encrypted (see ADR-002)
+5. Background jobs exchange refresh token for fresh access tokens as needed
+
+**Benefits:**
+- ✅ Works today with Keycloak and all OIDC providers
+- ✅ Standard OAuth pattern (RFC 6749)
+- ✅ Explicit user consent to `offline_access` scope
+- ✅ MCP Server can act on behalf of user in background
+
+**Limitations:**
+- ⚠️ Requires secure token storage on MCP Server
+- ⚠️ MCP Client must trust MCP Server with refresh token
+- ⚠️ Weak audit trail - API requests appear to come from user directly
+- ⚠️ No visibility that MCP Server is the actual actor
+
+### Token Exchange with Delegation (ADR-002 Tier 2 - Implemented)
+
+**RFC 8693 Delegation** would provide better audit trail and security:
+
+**How it would work:**
+1. User grants `may_act:nextcloud-mcp-server` scope during authentication
+2. Subject token includes: `{ "may_act": { "client": "nextcloud-mcp-server" } }`
+3. MCP Server has its own service account token (actor_token)
+4. Background job requests token exchange:
+   - `subject_token` (user's token with may_act claim)
+   - `actor_token` (mcp-server's service token)
+5. Keycloak validates actor matches may_act claim
+6. Returns delegated token: `{ "sub": "user", "act": "nextcloud-mcp-server" }`
+
+**Benefits:**
+- ✅ Better audit trail - Nextcloud APIs see both user and actor
+- ✅ No token storage needed (tokens generated on-demand)
+- ✅ Fine-grained permissions via `may_act` claim
+- ✅ User explicitly consents to MCP Server acting on their behalf
+- ✅ RFC 8693 compliant
+
+**Current Status:**
+- ❌ **NOT implemented in Keycloak yet** ([Issue #38279](https://github.com/keycloak/keycloak/issues/38279))
+- ❌ Would require custom implementation or waiting for upstream
+- 📝 Proposal includes `act` claim and `may_act` consent mechanism
+
+**Why Not Available:**
+- Keycloak supports **impersonation** (changes `sub` claim), but not **delegation** (`act` claim)
+- Impersonation has poor audit trail (actor invisible)
+- Delegation proposal is open but not implemented yet
+
+**Reference:** See `docs/ADR-002-vector-sync-authentication.md` for detailed comparison of authentication tiers.
+
+## Security Benefits
+
+1. **Intent Validation**: Tokens explicitly declare Nextcloud as the intended recipient via `aud` claim
+2. **Requester Identification**: The `azp` claim identifies MCP Server as the requester
+3. **User Context**: The `sub` claim preserves user identity for audit and authorization
+4. **Background Jobs**: Refresh tokens enable MCP Server to act on behalf of users without admin credentials
+5. **OAuth Standards**: Follows RFC 8707 (Resource Indicators) and RFC 6749 (OAuth 2.0)
+
+**Current Limitations:**
+- API requests from background jobs appear to come from user directly (no `act` claim yet)
+- See "Authentication Strategies for Background Jobs" section for future delegation support
+
+## Token Claims
+
+### Key Claims
+
+- **`aud: "nextcloud"`** - Audience: Token intended for Nextcloud APIs
+- **`azp: "nextcloud-mcp-server"`** - Authorized Party: MCP Server requested the token
+- **`sub: "user-id"`** - Subject: User on whose behalf the request is made
+- **`scope: "openid profile email offline_access"`** - Requested scopes including offline access for background jobs
+
+### Client Naming
+
+The Keycloak client is named `nextcloud-mcp-server` to clarify:
+- **MCP Server** uses this client to get tokens for Nextcloud
+- **MCP Clients** (like Claude Desktop) connect to MCP Server via separate OAuth flows
+- **Not** named "mcp-client" to avoid confusion about which component is the client
+
+## Troubleshooting
+
+### Token Has No Audience
+
+**Symptom**: `"aud": null` in decoded JWT
+
+**Cause**: Protocol mappers not configured
+
+**Solution**: Add audience mappers via Keycloak Admin API (see Configuration section)
+
+### MCP Server Rejects Token
+
+**Symptom**: HTTP 401 with "JWT validation failed"
+
+**Cause**: Token audience doesn't match expected value
+
+**Solution**:
+1. Check token has correct `aud` claim
+2. Verify MCP server expects correct audience value in code
+3. Check logs for specific JWT validation error
+
+### Nextcloud Rejects Token
+
+**Symptom**: HTTP 401 from Nextcloud API
+
+**Cause**: User not provisioned or token invalid
+
+**Solution**:
+1. Check user_oidc provider is configured: `php occ user_oidc:provider keycloak`
+2. Check bearer validation enabled: `--check-bearer=1`
+3. Test token with userinfo endpoint: `curl -H "Authorization: Bearer $TOKEN" http://keycloak/realms/.../userinfo`
+
+## Related Documentation
+
+- **Multi-client validation**: `docs/keycloak-multi-client-validation.md`
+- **ADR-002**: `docs/ADR-002-vector-sync-authentication.md`
+- **OAuth setup**: `docs/oauth-setup.md`
+- **Keycloak integration**: `docs/keycloak-integration.md` (if created)
+
+## References
+
+- [RFC 8707 - Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)
+- [OIDC Core - ID Token aud claim](https://openid.net/specs/openid-connect-core-1_0.html#IDToken)
+- [Keycloak Audience Protocol Mappers](https://www.keycloak.org/docs/latest/server_admin/#_audience)

docs/configuration.md

@@ -45,8 +45,7 @@ NEXTCLOUD_HOST=https://your.nextcloud.instance.com
 NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
 NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
 
-# OAuth Storage and Callback Settings (optional)
-NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
+# OAuth Callback Settings (optional)
 NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
 
 # Leave these EMPTY for OAuth mode
@@ -61,7 +60,6 @@ NEXTCLOUD_PASSWORD=
 | `NEXTCLOUD_HOST` | ✅ Yes | - | Full URL of your Nextcloud instance (e.g., `https://cloud.example.com`) |
 | `NEXTCLOUD_OIDC_CLIENT_ID` | ⚠️ Optional | - | OAuth client ID (auto-registers if empty) |
 | `NEXTCLOUD_OIDC_CLIENT_SECRET` | ⚠️ Optional | - | OAuth client secret (auto-registers if empty) |
-| `NEXTCLOUD_OIDC_CLIENT_STORAGE` | ⚠️ Optional | `.nextcloud_oauth_client.json` | Path to store auto-registered client credentials |
 | `NEXTCLOUD_MCP_SERVER_URL` | ⚠️ Optional | `http://localhost:8000` | MCP server URL for OAuth callbacks |
 | `NEXTCLOUD_USERNAME` | ❌ Must be empty | - | Leave empty to enable OAuth mode |
 | `NEXTCLOUD_PASSWORD` | ❌ Must be empty | - | Leave empty to enable OAuth mode |
@@ -110,6 +108,317 @@ NEXTCLOUD_PASSWORD=your_app_password_or_password
 
 ---
 
+## Semantic Search Configuration (Optional)
+
+The MCP server includes semantic search capabilities powered by vector embeddings. This feature requires a vector database (Qdrant) and an embedding service.
+
+### Qdrant Vector Database Modes
+
+The server supports three Qdrant deployment modes:
+
+1. **In-Memory Mode** (Default) - Simplest for development and testing
+2. **Persistent Local Mode** - For single-instance deployments with persistence
+3. **Network Mode** - For production with dedicated Qdrant service
+
+#### 1. In-Memory Mode (Default)
+
+No configuration needed! If neither `QDRANT_URL` nor `QDRANT_LOCATION` is set, the server defaults to in-memory mode:
+
+```dotenv
+# No Qdrant configuration needed - defaults to :memory:
+VECTOR_SYNC_ENABLED=true
+```
+
+**Pros:**
+- Zero configuration
+- Fast startup
+- Perfect for testing
+
+**Cons:**
+- Data lost on restart
+- Limited to available RAM
+
+#### 2. Persistent Local Mode
+
+For single-instance deployments that need persistence without a separate Qdrant service:
+
+```dotenv
+# Local persistent storage
+QDRANT_LOCATION=/app/data/qdrant  # Or any writable path
+VECTOR_SYNC_ENABLED=true
+```
+
+**Pros:**
+- Data persists across restarts
+- No separate service needed
+- Suitable for small/medium deployments
+
+**Cons:**
+- Limited to single instance
+- Shares resources with MCP server
+
+#### 3. Network Mode
+
+For production deployments with a dedicated Qdrant service:
+
+```dotenv
+# Network mode configuration
+QDRANT_URL=http://qdrant:6333
+QDRANT_API_KEY=your-secret-api-key  # Optional
+QDRANT_COLLECTION=nextcloud_content  # Optional
+VECTOR_SYNC_ENABLED=true
+```
+
+**Pros:**
+- Scalable and performant
+- Can be shared across multiple MCP instances
+- Supports clustering and replication
+
+**Cons:**
+- Requires separate Qdrant service
+- More complex deployment
+
+### Qdrant Collection Naming
+
+Collection names are automatically generated to include the embedding model, ensuring safe model switching and preventing dimension mismatches.
+
+#### Auto-Generated Naming (Default)
+
+**Format:** `{deployment-id}-{model-name}`
+
+**Components:**
+- **Deployment ID:** `OTEL_SERVICE_NAME` (if configured) or `hostname` (fallback)
+- **Model name:** `OLLAMA_EMBEDDING_MODEL`
+
+**Examples:**
+
+```bash
+# With OTEL service name configured
+OTEL_SERVICE_NAME=my-mcp-server
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# → Collection: "my-mcp-server-nomic-embed-text"
+
+# Simple Docker deployment (OTEL not configured)
+# hostname=mcp-container
+OLLAMA_EMBEDDING_MODEL=all-minilm
+# → Collection: "mcp-container-all-minilm"
+```
+
+#### Switching Embedding Models
+
+When you change `OLLAMA_EMBEDDING_MODEL`, a new collection is automatically created:
+
+```bash
+# Initial setup
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# Collection: "my-server-nomic-embed-text" (768 dimensions)
+
+# Change model
+OLLAMA_EMBEDDING_MODEL=all-minilm
+# Collection: "my-server-all-minilm" (384 dimensions)
+# → New collection created, full re-embedding occurs
+```
+
+**Important:**
+- **Collections are mutually exclusive** - vectors cannot be shared between different embedding models
+- **Switching models requires re-embedding** all documents (may take time for large note collections)
+- **Old collection remains** in Qdrant and can be deleted manually if no longer needed
+
+#### Explicit Override
+
+Set `QDRANT_COLLECTION` to use a specific collection name:
+
+```bash
+QDRANT_COLLECTION=my-custom-collection  # Bypasses auto-generation
+```
+
+**Use cases:**
+- Backward compatibility with existing deployments
+- Custom naming schemes
+- Sharing a collection across deployments (advanced)
+
+#### Multi-Server Deployments
+
+Each server should have a unique deployment ID to avoid collection collisions:
+
+```bash
+# Server 1 (Production)
+OTEL_SERVICE_NAME=mcp-prod
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# → Collection: "mcp-prod-nomic-embed-text"
+
+# Server 2 (Staging)
+OTEL_SERVICE_NAME=mcp-staging
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# → Collection: "mcp-staging-nomic-embed-text"
+
+# Server 3 (Different model)
+OTEL_SERVICE_NAME=mcp-experimental
+OLLAMA_EMBEDDING_MODEL=bge-large
+# → Collection: "mcp-experimental-bge-large"
+```
+
+**Benefits:**
+- Multiple MCP servers can share one Qdrant instance safely
+- No naming collisions between deployments
+- Clear collection ownership (can see which deployment and model)
+
+#### Dimension Validation
+
+The server validates collection dimensions on startup:
+
+```
+Dimension mismatch for collection 'my-server-nomic-embed-text':
+  Expected: 384 (from embedding model 'all-minilm')
+  Found: 768
+This usually means you changed the embedding model.
+Solutions:
+  1. Delete the old collection: Collection will be recreated with new dimensions
+  2. Set QDRANT_COLLECTION to use a different collection name
+  3. Revert OLLAMA_EMBEDDING_MODEL to the original model
+```
+
+**What this prevents:**
+- Runtime errors from dimension mismatches
+- Data corruption in Qdrant
+- Confusing error messages during indexing
+
+### Vector Sync Configuration
+
+Control background indexing behavior:
+
+```dotenv
+# Vector sync settings (ADR-007)
+VECTOR_SYNC_ENABLED=true              # Enable background indexing
+VECTOR_SYNC_SCAN_INTERVAL=300         # Scan interval in seconds (default: 5 minutes)
+VECTOR_SYNC_PROCESSOR_WORKERS=3       # Concurrent indexing workers (default: 3)
+VECTOR_SYNC_QUEUE_MAX_SIZE=10000      # Max queued documents (default: 10000)
+
+# Document chunking settings (for vector embeddings)
+DOCUMENT_CHUNK_SIZE=512               # Words per chunk (default: 512)
+DOCUMENT_CHUNK_OVERLAP=50             # Overlapping words between chunks (default: 50)
+```
+
+### Embedding Service Configuration
+
+The server uses an embedding service to generate vector representations. Two options are available:
+
+#### Ollama (Recommended)
+
+Use a local Ollama instance for embeddings:
+
+```dotenv
+OLLAMA_BASE_URL=http://ollama:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Default model
+OLLAMA_VERIFY_SSL=true                   # Verify SSL certificates
+```
+
+#### Simple Embedding Provider (Fallback)
+
+If `OLLAMA_BASE_URL` is not set, the server uses a simple random embedding provider for testing. This is **not suitable for production** as it generates random embeddings with no semantic meaning.
+
+### Document Chunking Configuration
+
+The server chunks documents before embedding to handle documents larger than the embedding model's context window. Chunk size and overlap can be tuned based on your embedding model and content type.
+
+#### Choosing Chunk Size
+
+**Smaller chunks (256-384 words)**:
+- More precise matching
+- Less context per chunk
+- Better for finding specific information
+- Higher storage requirements (more vectors)
+
+**Larger chunks (768-1024 words)**:
+- More context per chunk
+- Less precise matching
+- Better for understanding broader topics
+- Lower storage requirements (fewer vectors)
+
+**Default (512 words)**:
+- Balanced approach suitable for most use cases
+- Works well with typical note lengths
+- Good compromise between precision and context
+
+#### Choosing Overlap
+
+Overlap preserves context across chunk boundaries. Recommended settings:
+
+- **10-20% of chunk size** (e.g., 50-100 words for 512-word chunks)
+- **Too small** (<10%): May lose context at boundaries
+- **Too large** (>20%): Redundant storage, diminishing returns
+
+**Examples**:
+```dotenv
+# Precise matching for short notes
+DOCUMENT_CHUNK_SIZE=256
+DOCUMENT_CHUNK_OVERLAP=25
+
+# Default balanced configuration
+DOCUMENT_CHUNK_SIZE=512
+DOCUMENT_CHUNK_OVERLAP=50
+
+# More context for long documents
+DOCUMENT_CHUNK_SIZE=1024
+DOCUMENT_CHUNK_OVERLAP=100
+```
+
+**Important**: Changing chunk size requires re-embedding all documents. The collection naming strategy (see "Qdrant Collection Naming" above) helps manage this by creating separate collections for different configurations.
+
+### Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `QDRANT_URL` | ⚠️ Optional | - | Qdrant service URL (network mode) - mutually exclusive with `QDRANT_LOCATION` |
+| `QDRANT_LOCATION` | ⚠️ Optional | `:memory:` | Local Qdrant path (`:memory:` or `/path/to/data`) - mutually exclusive with `QDRANT_URL` |
+| `QDRANT_API_KEY` | ⚠️ Optional | - | Qdrant API key (network mode only) |
+| `QDRANT_COLLECTION` | ⚠️ Optional | `nextcloud_content` | Qdrant collection name |
+| `VECTOR_SYNC_ENABLED` | ⚠️ Optional | `false` | Enable background vector indexing |
+| `VECTOR_SYNC_SCAN_INTERVAL` | ⚠️ Optional | `300` | Document scan interval (seconds) |
+| `VECTOR_SYNC_PROCESSOR_WORKERS` | ⚠️ Optional | `3` | Concurrent indexing workers |
+| `VECTOR_SYNC_QUEUE_MAX_SIZE` | ⚠️ Optional | `10000` | Max queued documents |
+| `OLLAMA_BASE_URL` | ⚠️ Optional | - | Ollama API endpoint for embeddings |
+| `OLLAMA_EMBEDDING_MODEL` | ⚠️ Optional | `nomic-embed-text` | Embedding model to use |
+| `OLLAMA_VERIFY_SSL` | ⚠️ Optional | `true` | Verify SSL certificates |
+| `DOCUMENT_CHUNK_SIZE` | ⚠️ Optional | `512` | Words per chunk for document embedding |
+| `DOCUMENT_CHUNK_OVERLAP` | ⚠️ Optional | `50` | Overlapping words between chunks (must be < chunk size) |
+
+### Docker Compose Example
+
+Enable network mode Qdrant with docker-compose:
+
+```yaml
+services:
+  mcp:
+    environment:
+      - QDRANT_URL=http://qdrant:6333
+      - VECTOR_SYNC_ENABLED=true
+
+  qdrant:
+    image: qdrant/qdrant:latest
+    ports:
+      - 127.0.0.1:6333:6333
+    volumes:
+      - qdrant-data:/qdrant/storage
+    profiles:
+      - qdrant  # Optional service
+
+volumes:
+  qdrant-data:
+```
+
+Start with Qdrant service:
+```bash
+docker-compose --profile qdrant up
+```
+
+Or use default in-memory mode (no `--profile` needed):
+```bash
+docker-compose up
+```
+
+---
+
 ## Loading Environment Variables
 
 After creating your `.env` file, load the environment variables:
@@ -160,10 +469,6 @@ Options:
                                   NEXTCLOUD_OIDC_CLIENT_ID env var)
   --oauth-client-secret TEXT      OAuth client secret (can also use
                                   NEXTCLOUD_OIDC_CLIENT_SECRET env var)
-  --oauth-storage-path TEXT       Path to store OAuth client credentials
-                                  (can also use
-                                  NEXTCLOUD_OIDC_CLIENT_STORAGE env var)
-                                  [default: .nextcloud_oauth_client.json]
   --mcp-server-url TEXT           MCP server URL for OAuth callbacks (can
                                   also use NEXTCLOUD_MCP_SERVER_URL env
                                   var)  [default: http://localhost:8000]
@@ -225,10 +530,7 @@ uv run nextcloud-mcp-server --no-oauth \
 - Store OAuth client credentials securely
 - Use environment variables from your deployment platform (Docker secrets, Kubernetes ConfigMaps, etc.)
 - Never commit credentials to version control
-- Set appropriate file permissions on credential storage:
-  ```bash
-  chmod 600 .nextcloud_oauth_client.json
-  ```
+- SQLite database permissions are handled automatically by the server
 
 ### For Docker
 

docs/jwt-oauth-reference.md

@@ -0,0 +1,898 @@
+# 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 SQLite database 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_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. SQLite Database (Second Priority)
+   └─ OAuth client credentials table
+
+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 SQLite database
+- Database is encrypted and protected by file system permissions
+- Credentials are reused on subsequent starts (no re-registration needed)
+- Stored credentials are 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: SQLite database (second priority)
+# Credentials are automatically saved to the database after DCR
+# Server will automatically load them 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. Clear the SQLite database OAuth client entry 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/keycloak-multi-client-validation.md

@@ -0,0 +1,298 @@
+# Keycloak Multi-Client Token Validation
+
+## Executive Summary
+
+**Question**: Can Nextcloud's `user_oidc` app (configured with client A) validate bearer tokens from client B in the same Keycloak realm?
+
+**Answer**: ✅ **YES** - user_oidc validates tokens at the **realm level**, not per-client.
+
+## Test Results
+
+### Setup
+- **Keycloak Realm**: `nextcloud-mcp`
+- **Provider in user_oidc**: Configured with `mcp-client` credentials
+- **Test**: Get token from `test-client-b`, validate via Nextcloud API
+
+### Result
+```bash
+# Token from test-client-b (client B)
+$ TOKEN=$(curl -X POST ".../token" -d "client_id=test-client-b" ...)
+
+# Validated successfully by Nextcloud (configured with mcp-client = client A)
+$ curl -H "Authorization: Bearer $TOKEN" "http://nextcloud/ocs/.../capabilities"
+HTTP/1.1 200 OK
+{"ocs":{"meta":{"status":"ok"}}}
+```
+
+✅ **Token from client B validated successfully!**
+
+## How It Works
+
+### Token Structure from Keycloak
+
+**Access Token** (password grant):
+```json
+{
+  "iss": "http://keycloak/realms/nextcloud-mcp",
+  "azp": "test-client-b",           // Authorized party = client B
+  "typ": "Bearer",
+  "exp": 1234567890,
+  // NO "sub" claim
+  // NO "aud" claim
+  "scope": "openid profile email"
+}
+```
+
+**ID Token** (for comparison):
+```json
+{
+  "iss": "http://keycloak/realms/nextcloud-mcp",
+  "aud": "test-client-b",            // Audience = client B
+  "sub": "923da741-7ebe-4cf9-baf2-37fcf2ecc95d",
+  "azp": "test-client-b"
+}
+```
+
+**Key Observation**: Access tokens from Keycloak's password grant **do not contain** `sub` or `aud` claims!
+
+### Validation Flow in user_oidc
+
+From source code analysis (`~/Software/user_oidc/lib/User/Backend.php`):
+
+```
+1. Request with Bearer token arrives
+   ↓
+2. user_oidc loops through providers with checkBearer=true
+   ↓
+3. Try SelfEncodedValidator (JWT/JWKS validation):
+   - Validates JWT signature using Keycloak's JWKS
+   - Tries to extract 'sub' claim → FAILS (no sub in access token)
+   ↓
+4. Fallback to UserInfoValidator:
+   - Calls Keycloak userinfo endpoint with bearer token
+   - Keycloak validates token server-side
+   - Returns userinfo with 'sub' claim
+   → SUCCESS!
+   ↓
+5. User identified, request authorized
+```
+
+### Why This Works
+
+**Realm-Level Trust**:
+- Keycloak's userinfo endpoint validates ANY valid token from the realm
+- It doesn't matter which client issued the token
+- The token is validated by Keycloak itself (via userinfo call)
+
+**No Audience Check**:
+- Access tokens have no `aud` claim
+- SelfEncodedValidator's audience check is bypassed (no audience to validate)
+- UserInfoValidator doesn't check audience (delegates to Keycloak)
+
+**Client Credentials Role**:
+- The configured `client_id`/`client_secret` in user_oidc are **NOT used** for bearer token validation
+- They're only used for OAuth login flows (authorization code exchange)
+- Userinfo endpoint doesn't require client authentication
+
+## Source Code Evidence
+
+### SelfEncodedValidator - Audience Check
+
+```php
+// ~/Software/user_oidc/lib/User/Validator/SelfEncodedValidator.php:64-76
+
+$checkAudience = !isset($oidcSystemConfig['selfencoded_bearer_validation_audience_check'])
+    || !in_array($oidcSystemConfig['selfencoded_bearer_validation_audience_check'],
+         [false, 'false', 0, '0'], true);
+
+if ($checkAudience) {
+    $tokenAudience = $payload->aud ?? null;
+
+    if ((is_string($tokenAudience) && $tokenAudience !== $providerClientId)
+        || (is_array($tokenAudience) && !in_array($providerClientId, $tokenAudience))) {
+        $this->logger->debug('Audience does not match client ID');
+        return null;  // REJECT
+    }
+}
+
+// If $tokenAudience is null (our case), both conditions are false → validation continues
+```
+
+### UserInfoValidator - No Client Auth
+
+```php
+// ~/Software/user_oidc/lib/Service/OIDCService.php:28-45
+
+public function userinfo(Provider $provider, string $accessToken): array {
+    $url = $this->discoveryService->obtainDiscovery($provider)['userinfo_endpoint'];
+
+    // Bearer token passed directly - NO client credentials used
+    $options = ['headers' => ['Authorization' => 'Bearer ' . $accessToken]];
+
+    return json_decode($this->clientService->get($url, [], $options), true);
+}
+```
+
+### Keycloak Userinfo Response
+
+```bash
+$ curl -H "Authorization: Bearer $TOKEN_FROM_CLIENT_B" \
+    "http://keycloak/realms/nextcloud-mcp/protocol/openid-connect/userinfo"
+
+{
+  "sub": "923da741-7ebe-4cf9-baf2-37fcf2ecc95d",
+  "email_verified": true,
+  "name": "Admin User",
+  "email": "admin@example.com"
+}
+```
+
+Keycloak validates the token **regardless of which client issued it**, as long as it's from the same realm.
+
+## Implications for Your Architecture
+
+### Desired Architecture
+```
+MCP Server (client A) ← DCR with Keycloak
+MCP Clients (client B, C, D...) ← DCR with Keycloak
+Nextcloud user_oidc ← configured once with any client from realm
+```
+
+### What This Means
+
+✅ **You can do exactly what you want!**
+
+1. **Configure user_oidc once** with any client from the Keycloak realm (e.g., a dedicated `nextcloud-validator` client)
+
+2. **MCP Server registers via DCR** as a unique client (e.g., `mcp-server-abc123`)
+   - Gets its own client credentials
+   - Issues tokens with `azp: "mcp-server-abc123"`
+   - These tokens will be validated by user_oidc!
+
+3. **MCP Clients also use DCR** (each gets unique identity)
+   - Client A: `client-123`
+   - Client B: `client-456`
+   - Tokens from all clients validated by user_oidc!
+
+4. **Tokens from ANY client** in the realm can access Nextcloud APIs
+   - user_oidc validates via Keycloak userinfo endpoint
+   - Realm-level trust (not per-client)
+
+### Configuration
+
+**Step 1: Configure user_oidc Provider**
+```bash
+php occ user_oidc:provider keycloak-realm \
+    --clientid="nextcloud-validator" \
+    --clientsecret="***" \
+    --discoveryuri="https://keycloak/realms/my-realm/.well-known/openid-configuration" \
+    --check-bearer=1 \
+    --bearer-provisioning=1
+```
+
+**Step 2: MCP Server Registers with Keycloak (DCR)**
+```python
+# MCP server startup
+registration_response = await keycloak_client.register_client(
+    client_name="MCP Server Instance",
+    redirect_uris=["http://mcp-server/oauth/callback"]
+)
+# Store: client_id, client_secret
+```
+
+**Step 3: Issue Tokens to Users**
+- Users authenticate via Keycloak
+- MCP server gets tokens issued to its `client_id`
+- These tokens validated by user_oidc!
+
+**Step 4: Background Operations (ADR-002)**
+- Store user refresh tokens (encrypted)
+- Refresh access tokens as needed
+- All tokens validated by user_oidc regardless of issuing client
+
+## Important Notes
+
+### Token Grant Types Matter
+
+**Password Grant** (what we tested):
+- Access tokens have NO `sub` or `aud`
+- Forces validation via userinfo endpoint
+- Works with any client in realm
+
+**Authorization Code Grant** (production):
+- Tokens MAY include `aud` claim
+- Need to verify behavior with real OAuth flows
+- May require disabling audience check
+
+### Recommendation for Production
+
+**Option 1: Disable Audience Check (Simplest)**
+```php
+// config.php
+'user_oidc' => [
+    'selfencoded_bearer_validation_audience_check' => false,
+],
+```
+
+**Option 2: Rely on UserInfo Validation**
+```php
+// config.php
+'user_oidc' => [
+    'userinfo_bearer_validation' => true,  // Enable userinfo validation
+],
+```
+
+**Option 3: Configure Keycloak to Not Include aud in Access Tokens**
+- Keep default behavior (works as tested)
+- Tokens validated via userinfo endpoint
+
+## Testing Script
+
+```bash
+#!/bin/bash
+# Test multi-client validation
+
+# Create second client in Keycloak
+curl -X POST "http://keycloak/admin/realms/my-realm/clients" \
+    -H "Authorization: Bearer $ADMIN_TOKEN" \
+    -d '{
+        "clientId": "test-client-b",
+        "secret": "test-secret-b",
+        "standardFlowEnabled": true,
+        "directAccessGrantsEnabled": true
+    }'
+
+# Get token from client B
+TOKEN=$(curl -X POST "http://keycloak/realms/my-realm/protocol/openid-connect/token" \
+    -d "grant_type=password" \
+    -d "client_id=test-client-b" \
+    -d "client_secret=test-secret-b" \
+    -d "username=testuser" \
+    -d "password=password" | jq -r '.access_token')
+
+# Test with Nextcloud (configured with client A)
+curl -H "Authorization: Bearer $TOKEN" \
+    "http://nextcloud/ocs/v2.php/cloud/capabilities"
+
+# Should return 200 OK!
+```
+
+## Conclusion
+
+✅ **Your proposed architecture is fully supported!**
+
+- user_oidc configured once with ANY client from Keycloak realm
+- MCP server registers dynamically via DCR
+- MCP clients also register dynamically
+- ALL tokens from realm validated successfully
+- No per-client configuration needed
+
+The key insight: **user_oidc validates tokens at the realm level** (via Keycloak's userinfo endpoint), not at the client level.
+
+## References
+
+- Source code: `~/Software/user_oidc/lib/User/Backend.php:260-343`
+- SelfEncodedValidator: `~/Software/user_oidc/lib/User/Validator/SelfEncodedValidator.php`
+- UserInfoValidator: `~/Software/user_oidc/lib/User/Validator/UserInfoValidator.php`
+- Test setup: `docker-compose.yml` (mcp-keycloak service)
+- Configuration: `.env.keycloak.sample`

docs/notes.md

@@ -8,7 +8,9 @@
 | `nc_notes_update_note` | Update an existing note by ID |
 | `nc_notes_append_content` | Append content to an existing note with a clear separator |
 | `nc_notes_delete_note` | Delete a note by ID |
-| `nc_notes_search_notes` | Search notes by title or content |
+| `nc_notes_search_notes` | Search notes by title or content (keyword search) |
+| `nc_notes_semantic_search` | Search notes by meaning using vector embeddings (requires vector sync) |
+| `nc_notes_semantic_search_answer` | Search notes semantically and generate a natural language answer via MCP sampling (requires vector sync and sampling-capable MCP client) |
 
 ### Note Attachments
 

docs/oauth-architecture-comparison.md

@@ -0,0 +1,323 @@
+# OAuth Architecture Comparison: MCP Server Authentication Patterns
+
+This document compares three authentication architectures for the MCP server, explaining the evolution from pass-through authentication to true offline access capabilities.
+
+## Pattern 1: Pass-Through Authentication (Current Implementation)
+
+### Architecture
+```
+┌─────────────┐     OAuth Flow    ┌─────────────┐
+│  MCP Client │◄──────────────────│   OAuth     │
+│   (Claude)  │                   │  Provider   │
+└──────┬──────┘                   └─────────────┘
+       │
+       │ Access Token
+       │ (per request)
+       ▼
+┌─────────────┐                   ┌─────────────┐
+│ MCP Server  │───────────────────►│  Nextcloud  │
+│(Pass-through)                   │    APIs     │
+└─────────────┘                   └─────────────┘
+```
+
+### Characteristics
+| Aspect | Description |
+|--------|-------------|
+| **Token Flow** | MCP Client → MCP Server → Nextcloud |
+| **Token Storage** | None (tokens exist only during request) |
+| **Offline Access** | ❌ Impossible |
+| **Background Workers** | ❌ Not supported |
+| **User Consent** | Single OAuth flow (client-managed) |
+| **Complexity** | Low |
+| **Security** | High (no token persistence) |
+
+### How It Works
+1. MCP Client performs OAuth with provider
+2. Client includes access token in each MCP request
+3. MCP Server validates token and forwards to Nextcloud
+4. Token discarded after request completes
+
+### Limitations
+- No operations possible without active MCP session
+- Background sync/indexing impossible
+- Cannot refresh tokens independently
+
+---
+
+## Pattern 2: Token Exchange Delegation (ADR-002 - Flawed)
+
+### Architecture
+```
+┌─────────────┐                    ┌─────────────┐
+│ MCP Client  │────────────────────│   OAuth     │
+│  (Claude)   │                    │  Provider   │
+└──────┬──────┘                    └──────┬──────┘
+       │                                   │
+       │ Access Token                      │ Service Account Token
+       ▼                                   ▼
+┌─────────────────────────────────────────────┐
+│            MCP Server                        │
+│  ┌────────────────────────────────────┐     │
+│  │ Token Exchange (RFC 8693)          │     │
+│  │ Subject: Service Account           │     │
+│  │ Target: User                       │     │
+│  └────────────────────────────────────┘     │
+└───────────────┬─────────────────────────────┘
+                │ Exchanged Token
+                ▼
+         ┌─────────────┐
+         │  Nextcloud  │
+         │    APIs     │
+         └─────────────┘
+```
+
+### Characteristics
+| Aspect | Description |
+|--------|-------------|
+| **Token Flow** | Service Account → Exchange → User Token |
+| **Token Storage** | None (MCP server still stateless) |
+| **Offline Access** | ❌ Still impossible (circular dependency) |
+| **Background Workers** | ❌ Requires service account (rejected) |
+| **User Consent** | Implicit through service account |
+| **Complexity** | High |
+| **Security** | ⚠️ Service accounts violate OAuth principles |
+
+### Why It Fails
+1. **Circular Dependency**: To exchange tokens, you need a token to exchange
+2. **Service Account Problem**: Creates Nextcloud user identity for service
+3. **OAuth Violation**: Service acts as itself, not on behalf of users
+4. **No Bootstrap**: Still can't obtain initial tokens offline
+
+### The Fatal Flaw
+```
+Q: How does background worker get tokens?
+A: Use token exchange with service account
+
+Q: How does service account get authorized?
+A: Client credentials grant creates user account (violates OAuth)
+
+Q: Can we use user's refresh token?
+A: MCP server never sees refresh tokens (by design)
+```
+
+---
+
+## Pattern 3: Sign-in with Nextcloud (Previous ADR-004 Draft)
+
+### Architecture
+```
+┌─────────────┐                      ┌─────────────────┐                     ┌────────────┐
+│  MCP Client ├───────────────────>  │   MCP Server    ├────────────────────>│ Nextcloud  │
+│  (Claude)   │  (MCP Protocol)      │  (OAuth Client) │   (OIDC + APIs)     │   (IdP)    │
+└─────────────┘                      └─────────────────┘                     └────────────┘
+                                             │
+                                      ┌──────▼────────┐
+                                      │ Token Storage │
+                                      │ (NC Tokens)   │
+                                      └───────────────┘
+```
+
+### Characteristics
+| Aspect | Description |
+|--------|-------------|
+| **Token Flow** | MCP Server uses Nextcloud as identity provider |
+| **Token Storage** | ✅ Encrypted Nextcloud refresh tokens |
+| **Offline Access** | ✅ Full support |
+| **Background Workers** | ✅ Use stored refresh tokens |
+| **User Consent** | Single OAuth flow (Nextcloud only) |
+| **Complexity** | Medium |
+| **Security** | High (with token rotation) |
+
+### How It Works
+1. **Initial Setup**:
+   - User tries to use MCP tool
+   - MCP server returns auth required
+   - User authenticates with Nextcloud's OIDC endpoint
+   - Nextcloud may use user_oidc to delegate to external IdP (Keycloak, etc.)
+   - MCP server stores Nextcloud-issued refresh token (encrypted)
+
+2. **Subsequent Requests**:
+   - MCP server uses stored Nextcloud tokens
+   - Refreshes automatically when expired
+   - No client involvement needed
+
+3. **Background Operations**:
+   - Worker retrieves stored refresh token
+   - Refreshes with Nextcloud directly
+   - Performs operations independently
+
+### Advantages
+- ✅ Single sign-on with Nextcloud
+- ✅ True offline access capability
+- ✅ OAuth-compliant with proper consent
+- ✅ Supports external IdPs via user_oidc
+- ✅ Simpler integration - only one OAuth endpoint
+
+### Trade-offs
+- Authentication flows through Nextcloud
+- Nextcloud manages IdP relationships (via user_oidc)
+- MCP server only knows about Nextcloud, not the underlying IdP
+
+---
+
+## Pattern 4: Federated Authentication Architecture (ADR-004 - Solution)
+
+### Architecture
+```
+┌─────────────┐                ┌─────────────────┐                ┌──────────────┐              ┌────────────┐
+│  MCP Client │◄──────401──────│   MCP Server    │◄────OAuth──────│  Shared IdP  │──Validates──►│ Nextcloud  │
+│  (Claude)   │                │  (OAuth Client) │   (On-Behalf)  │  (Keycloak)  │   Tokens     │(Resource)  │
+└─────────────┘                └─────────────────┘                └──────────────┘              └────────────┘
+                                        │
+                                ┌───────▼────────┐
+                                │ Token Storage  │
+                                │ (IdP Tokens)   │
+                                └────────────────┘
+```
+
+### Characteristics
+| Aspect | Description |
+|--------|-------------|
+| **Token Flow** | Shared IdP issues tokens for Nextcloud access |
+| **Token Storage** | ✅ Encrypted IdP refresh tokens |
+| **Offline Access** | ✅ Full support |
+| **Background Workers** | ✅ Use stored IdP refresh tokens |
+| **User Consent** | Single OAuth flow (IdP manages consent) |
+| **Complexity** | Medium-High |
+| **Security** | Highest (enterprise-grade IdP) |
+
+### How It Works
+1. **Initial Setup**:
+   - MCP client connects, receives 401
+   - Browser opens MCP server OAuth URL
+   - MCP server redirects to shared IdP
+   - User authenticates once to IdP
+   - IdP shows consent for both identity and Nextcloud access
+   - MCP server stores IdP refresh token (encrypted)
+   - MCP server issues session token to client
+
+2. **Subsequent Requests**:
+   - MCP server validates session token
+   - Uses stored IdP token for Nextcloud
+   - Refreshes with IdP when expired
+   - No client involvement needed
+
+3. **Background Operations**:
+   - Worker retrieves stored IdP refresh token
+   - Gets new access token from IdP
+   - Uses token to access Nextcloud
+   - Performs operations independently
+
+### Advantages
+- ✅ True single sign-on (SSO)
+- ✅ Enterprise-ready with SAML/LDAP support
+- ✅ OAuth-compliant with proper delegation
+- ✅ Direct IdP relationship - no intermediary
+- ✅ Flexible - can swap resource servers
+- ✅ Industry-standard federated pattern
+
+### Trade-offs
+- Requires shared IdP infrastructure
+- More complex initial setup
+- Token validation overhead
+
+---
+
+## Comparison Matrix
+
+| Feature | Pass-Through | Token Exchange | Sign-in with NC | Federated Auth |
+|---------|--------------|----------------|-----------------|----------------|
+| **Offline Access** | ❌ No | ❌ No | ✅ Yes | ✅ Yes |
+| **Background Workers** | ❌ No | ❌ No* | ✅ Yes | ✅ Yes |
+| **Token Storage** | None | None | NC refresh tokens | IdP refresh tokens |
+| **OAuth Compliance** | ✅ Full | ⚠️ Violates | ✅ Full | ✅ Full |
+| **User Consent** | Once | Implicit | Once (NC) | Once (IdP) |
+| **Implementation Complexity** | Low | High | Medium | Medium-High |
+| **Security** | High | Medium | High | Highest |
+| **Enterprise Ready** | ❌ No | ❌ No | ⚠️ Indirect | ✅ Yes |
+| **Identity Provider** | Client-managed | N/A | Nextcloud (+user_oidc) | Shared IdP |
+| **Suitable For** | Interactive only | N/A (flawed) | Small teams | Enterprise |
+
+\* *Requires service accounts that violate OAuth principles*
+
+---
+
+## Evolution Summary
+
+### Stage 1: Simple Pass-Through ✅
+- **Goal**: Basic MCP functionality
+- **Result**: Works well for interactive use
+- **Limitation**: No offline capabilities
+
+### Stage 2: Attempted Delegation ❌
+- **Goal**: Enable offline access without changing architecture
+- **Result**: Circular dependencies, OAuth violations
+- **Learning**: MCP protocol constraints are fundamental
+
+### Stage 3: Sign-in with Nextcloud ⚠️
+- **Goal**: True offline access with OAuth compliance
+- **Result**: MCP server uses Nextcloud as identity provider
+- **Limitation**: Tight coupling to Nextcloud, no enterprise IdP
+
+### Stage 4: Federated Pattern ✅
+- **Goal**: Enterprise-ready offline access
+- **Result**: Shared IdP for both MCP server and Nextcloud
+- **Trade-off**: Additional infrastructure justified by enterprise needs
+
+---
+
+## Key Insights
+
+1. **Pattern 3 vs Pattern 4**: Both support external IdPs, but differ in integration approach:
+   - Pattern 3: MCP → Nextcloud OIDC → (user_oidc) → External IdP
+   - Pattern 4: MCP → External IdP directly (Nextcloud also uses same IdP)
+   - Choose Pattern 3 for Nextcloud-centric deployments, Pattern 4 for IdP-centric enterprises
+
+2. **The MCP Protocol Boundary**: The MCP protocol creates a fundamental boundary between client and server token management. Attempting to breach this boundary (ADR-002) leads to architectural contradictions.
+
+3. **Service Accounts Don't Solve User Problems**: Using service accounts for user operations violates OAuth's core principle of acting on behalf of users, not as a service identity.
+
+4. **Double OAuth is Industry Standard**: Major platforms (Zapier, IFTTT, Microsoft Power Automate) use this pattern - the integration platform is an OAuth client that maintains its own relationships with upstream services.
+
+5. **Refresh Tokens Are The Solution**: The OAuth spec designed refresh tokens specifically for offline access. Rejecting them (as ADR-002 did) means rejecting the standard solution.
+
+6. **Complexity is Justified**: The additional complexity of managing OAuth flows is acceptable when offline access is a requirement. The alternative is no offline access at all.
+
+---
+
+## Recommendations
+
+### For Simple Deployments
+Use **Pattern 1 (Pass-Through)** if:
+- Offline access not needed
+- Only interactive operations required
+- Simplicity is priority
+
+### For Teams Using Nextcloud
+Use **Pattern 3 (Sign-in with Nextcloud)** if:
+- Background sync/indexing required
+- Nextcloud manages your authentication
+- Can use external IdPs via user_oidc
+- Prefer single integration point through Nextcloud
+
+### For Enterprise Deployments
+Use **Pattern 4 (Federated Authentication)** if:
+- Enterprise IdP already exists (Keycloak, Okta, Azure AD)
+- Multiple resource servers beyond Nextcloud
+- Compliance requirements for centralized auth
+- Building platform for multiple organizations
+
+### Never Use Pattern 2
+Token Exchange with service accounts should not be used as it:
+- Doesn't enable true offline access
+- Violates OAuth principles
+- Adds complexity without solving the problem
+
+---
+
+## References
+
+- [ADR-002: Vector Database Background Sync Authentication (Deprecated)](./ADR-002-vector-sync-authentication.md)
+- [ADR-004: MCP Server as OAuth Client for Offline Access](./ADR-004-mcp-application-oauth.md)
+- [RFC 6749: OAuth 2.0 Framework](https://datatracker.ietf.org/doc/html/rfc6749)
+- [RFC 8693: OAuth 2.0 Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693)

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 SQLite database         │
+                                          │                                     │
+                                          │  ✓ 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 SQLite database
+- **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 SQLite database
+
+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
 
@@ -218,7 +515,7 @@ NEXTCLOUD_HOST=https://nextcloud.example.com
 **How it works**:
 1. Server checks `/.well-known/openid-configuration` for `registration_endpoint`
 2. Calls `/apps/oidc/register` to register a client on first startup
-3. Saves credentials to `.nextcloud_oauth_client.json`
+3. Saves credentials to SQLite database
 4. Reuses these credentials on subsequent startups
 5. Re-registers only if credentials are missing or expired
 
@@ -272,14 +569,151 @@ 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
+
+#### Semantic Search (Multi-App Vector Database)
+- `semantic:read` - Query vector database, perform semantic search across all indexed Nextcloud apps (notes, calendar, deck, files, contacts)
+- `semantic:write` - Enable/disable background vector synchronization, manage indexing settings
+
+> **Note**: Semantic search scopes provide access to the vector database that indexes content across **all** Nextcloud apps. Unlike app-specific scopes (e.g., `notes:read`), semantic scopes grant cross-app search capabilities powered by background vector synchronization (ADR-007).
+
+### 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:
@@ -290,7 +724,6 @@ See [Configuration Guide](configuration.md) for all OAuth environment variables:
 | `NEXTCLOUD_OIDC_CLIENT_ID` | Pre-configured client ID (optional) |
 | `NEXTCLOUD_OIDC_CLIENT_SECRET` | Pre-configured client secret (optional) |
 | `NEXTCLOUD_MCP_SERVER_URL` | MCP server URL for OAuth callbacks |
-| `NEXTCLOUD_OIDC_CLIENT_STORAGE` | Path for auto-registered credentials |
 
 ## Testing
 

docs/oauth-impersonation-findings.md

@@ -0,0 +1,387 @@
+# OAuth Impersonation Investigation Findings
+
+**Date**: 2025-11-02
+**Last Updated**: 2025-11-02 (Token Exchange Resolution)
+**Status**: Implementation Complete - Token Exchange Working
+**Conclusion**: Keycloak Standard Token Exchange (RFC 8693) working for internal-to-internal token exchange. User impersonation requires Legacy V1.
+
+---
+
+## ⚠️ IMPORTANT UPDATE (2025-11-02)
+
+**This document contains outdated information regarding service account tokens.**
+
+After implementation and testing, we discovered that service account tokens (`client_credentials` grant) **violate OAuth "act on-behalf-of" principles** by creating Nextcloud user accounts (e.g., `service-account-nextcloud-mcp-server`). This approach has been **REJECTED** and moved to ADR-002's "Will Not Implement" section.
+
+**Key Changes:**
+- ❌ **Service account tokens (client_credentials) are INVALID** - Creates user accounts, breaks audit trail
+- ✅ **Token exchange (RFC 8693) is the correct approach** - Implemented and working (ADR-002 Tier 2)
+- ✅ **Offline access with refresh tokens** - Still valid for background operations (ADR-002 primary approach)
+
+**For current architecture, see**: `docs/ADR-002-vector-sync-authentication.md`
+
+---
+
+## Summary
+
+We investigated options for implementing user impersonation to enable background operations without requiring admin credentials (ADR-002 Tier 2). Here are the findings:
+
+## 1. Keycloak Token Exchange (RFC 8693)
+
+### What We Implemented
+- ✅ Service account token acquisition (`client_credentials` grant)
+- ✅ `get_service_account_token()` method in `KeycloakOAuthClient`
+- ✅ `exchange_token_for_user()` method implementing RFC 8693
+- ✅ Token exchange configuration in Keycloak realm
+
+### What Works ✅
+**Keycloak Standard V2 Token Exchange (RFC 8693) is WORKING**:
+- ✅ Service account token acquisition via `client_credentials` grant
+- ✅ Token exchange for internal-to-internal tokens
+- ✅ Audience and scope modifications
+- ✅ Integration with Nextcloud APIs using exchanged tokens
+
+**Configuration Requirements**:
+To enable Standard Token Exchange in Keycloak 26.2+, add to client attributes in `realm-export.json`:
+```json
+"attributes": {
+  "token.exchange.grant.enabled": "true",
+  "client.token.exchange.standard.enabled": "true"
+}
+```
+
+### Limitations
+Keycloak Standard V2 does NOT support:
+- ❌ User impersonation (`requested_subject` parameter)
+- ❌ Cross-client delegation (limited to same realm)
+
+These features require Legacy V1 with `--features=preview`
+
+### Alternative: Keycloak Legacy V1
+Keycloak Legacy Token Exchange (V1) WOULD support user impersonation, but:
+- ❌ Requires `--features=preview --features=token-exchange` flag
+- ❌ Not suitable for production
+- ❌ Deprecated and being phased out
+
+**Decision**: Not viable for production use.
+
+---
+
+## 2. Nextcloud OIDC App Token Exchange
+
+### Discovery Endpoint Analysis
+```json
+{
+  "grant_types_supported": [
+    "authorization_code",
+    "implicit"
+  ]
+}
+```
+
+### Findings
+❌ **Nextcloud OIDC app does NOT support**:
+- RFC 8693 token exchange
+- `client_credentials` grant
+- `refresh_token` grant (refresh tokens not issued)
+- User impersonation APIs
+
+The Nextcloud OIDC app is a basic OAuth 2.0 provider focused on:
+- Authorization code flow for user login
+- JWT tokens for API access
+- Scope-based authorization
+
+It is NOT designed for:
+- Service accounts
+- Token delegation
+- Background operations
+
+**Decision**: Not viable - missing required grant types.
+
+---
+
+## 3. Nextcloud Impersonate App
+
+### What It Provides
+✅ Admin users can impersonate other users via:
+- UI: Settings → Users → Impersonate button
+- API: `POST /apps/impersonate/user` with `userId` parameter
+
+### How It Works
+```php
+// From SettingsController.php
+public function impersonate(string $userId): JSONResponse {
+    // 1. Verify admin/delegated admin permissions
+    // 2. Check target user has logged in before
+    // 3. Set session: $this->userSession->setUser($impersonatee)
+    // 4. Return success
+}
+```
+
+### Requirements
+- ✅ Admin credentials
+- ✅ Session-based authentication (cookies)
+- ✅ CSRF token
+- ✅ Target user must have logged in at least once
+- ❌ Not compatible with encryption-enabled instances
+
+### Limitations for Background Workers
+❌ **Session-based, not stateless**:
+- Requires maintaining HTTP session/cookies
+- Not suitable for distributed workers
+- Can't use with bearer tokens
+- Requires re-authentication periodically
+
+❌ **Security concerns**:
+- Requires admin credentials stored on server
+- All impersonated actions logged as target user
+- Violates principle of least privilege
+
+**Decision**: Not suitable for background operations - session-based architecture incompatible with stateless OAuth/bearer token model.
+
+---
+
+## 4. What Actually Works
+
+### Option A: Admin Credentials (Current Implementation)
+✅ **BasicAuth mode with admin account**:
+```python
+client = NextcloudClient.from_env()  # Uses NEXTCLOUD_USERNAME/PASSWORD
+# Can access all APIs with admin permissions
+```
+
+**Pros**:
+- Simple, works immediately
+- Full access to all APIs
+
+**Cons**:
+- Requires admin credentials stored on server
+- No per-user permission scoping
+- Security risk if credentials leaked
+- Violates ADR-002 goals
+
+**Status**: Available but not recommended for production.
+
+### Option B: Service Account with Scoped Permissions
+✅ **Create dedicated service account**:
+1. Create `mcp-sync` user in Nextcloud
+2. Grant specific permissions (group memberships, shares)
+3. Use those credentials for background operations
+
+**Pros**:
+- Dedicated account, easier to audit
+- Can limit permissions via Nextcloud groups
+- Works with current BasicAuth implementation
+
+**Cons**:
+- Still requires credentials storage
+- Can't truly act "as" individual users
+- Limited by Nextcloud's permission model
+
+**Status**: Best available option without OAuth delegation.
+
+---
+
+## 5. Recommendations
+
+### Short Term (Immediate)
+**Use Service Account Pattern**:
+```python
+# Background worker configuration
+SYNC_ACCOUNT_USERNAME=mcp-sync
+SYNC_ACCOUNT_PASSWORD=<secure-password>
+
+# Create service account with limited permissions
+docker compose exec app php occ user:add mcp-sync
+docker compose exec app php occ group:adduser <appropriate-group> mcp-sync
+```
+
+**Benefits**:
+- Works with existing implementation
+- Better than admin credentials
+- Auditable
+
+### Medium Term (If OAuth Delegation Required)
+**Wait for proper standards support**:
+- Monitor Keycloak for Standard V2 improvements
+- Contribute to/request Nextcloud OIDC app enhancements
+- Consider alternative identity providers (e.g., Authelia, Authentik)
+
+### Long Term (Ideal Solution)
+**Implement proper OAuth delegation**:
+1. Use identity provider that supports RFC 8693 properly (e.g., Auth0, Okta)
+2. Or implement custom delegation endpoint in Nextcloud
+3. Or propose MCP protocol extension for refresh token sharing
+
+---
+
+## 6. Updated ADR-002 Status
+
+| Tier | Solution | Status | Viability |
+|------|----------|--------|-----------|
+| **Tier 0** | Admin BasicAuth | ✅ Implemented | ⚠️ Works but not recommended |
+| **Tier 1** | Offline Access (Refresh Tokens) | ⚠️ Infrastructure ready | ❌ MCP protocol limitation |
+| **Tier 2** | Token Exchange (RFC 8693) | ✅ **WORKING** | ✅ **Internal token exchange functional** |
+| **Tier 3** | Service Account (NEW) | ✅ Available | ✅ **RECOMMENDED for background ops** |
+
+---
+
+## 7. Implementation Status
+
+### What Was Built
+1. ✅ `RefreshTokenStorage` - SQLite + encryption (ready for future use)
+2. ✅ `KeycloakOAuthClient.get_service_account_token()` - Works
+3. ✅ `KeycloakOAuthClient.exchange_token_for_user()` - Implemented but non-functional
+4. ✅ Token exchange configuration - Keycloak realm updated
+5. ✅ Test scripts - Comprehensive testing completed
+
+### What to Use
+**For Background Operations**:
+```python
+# Use service account with BasicAuth
+from nextcloud_mcp_server.client import NextcloudClient
+
+# In background worker
+sync_client = NextcloudClient(
+    base_url=os.getenv("NEXTCLOUD_HOST"),
+    username=os.getenv("SYNC_ACCOUNT_USERNAME"),
+    password=os.getenv("SYNC_ACCOUNT_PASSWORD"),
+)
+
+# Perform operations
+notes = await sync_client.notes.search_notes("important")
+# Index to vector database, etc.
+```
+
+**For User Requests**:
+```python
+# Continue using OAuth bearer tokens
+# Per-request client creation as currently implemented
+client = get_client_from_context(ctx, nextcloud_host)
+```
+
+---
+
+## 8. Files Modified/Created
+
+### Implementation
+- `nextcloud_mcp_server/auth/keycloak_oauth.py` - Token exchange methods
+- `nextcloud_mcp_server/auth/refresh_token_storage.py` - Token storage (ready for future)
+- `nextcloud_mcp_server/app.py` - OAuth configuration updates
+- `keycloak/realm-export.json` - Token exchange enabled
+- `pyproject.toml` - Added aiosqlite dependency
+
+### Documentation
+- `docs/oauth-impersonation-findings.md` - This document
+- `docs/ADR-002-vector-sync-authentication.md` - Original architecture decision
+
+### Tests
+- `tests/manual/test_token_exchange.py` - Keycloak RFC 8693 testing
+- `tests/manual/test_nextcloud_impersonate.py` - Nextcloud impersonate API testing
+
+---
+
+## 9. Conclusion
+
+**Neither Keycloak nor Nextcloud currently provide viable OAuth-based user impersonation for background operations.**
+
+The infrastructure is ready (token storage, exchange methods), but provider limitations prevent use.
+
+**Recommended approach**: Use dedicated service account with appropriate Nextcloud permissions for background operations until proper OAuth delegation becomes available.
+
+The implemented code remains valuable:
+- Ready for future when providers add support
+- Demonstrates proper OAuth patterns
+- Test infrastructure for validation
+
+---
+
+## Appendix: Technical Details
+
+### Keycloak Configuration Applied
+```json
+{
+  "clientId": "nextcloud-mcp-server",
+  "serviceAccountsEnabled": true,
+  "attributes": {
+    "token.exchange.grant.enabled": "true"
+  }
+}
+```
+
+### Test Results - UPDATED (2025-11-02)
+```
+✅ Service account token acquisition: WORKS
+✅ Token exchange discovery: SUPPORTED
+✅ Token exchange configuration: ENABLED
+✅ Actual token exchange: WORKS (after adding client.token.exchange.standard.enabled)
+✅ Nextcloud API access: WORKS with exchanged tokens
+```
+
+**Resolution**: The realm-export.json was missing the `client.token.exchange.standard.enabled` attribute. After adding this attribute to keycloak/realm-export.json:128, token exchange works correctly on fresh Keycloak imports.
+
+### Nextcloud Impersonate Results
+```
+✓ App installation: SUCCESS
+✓ Admin can impersonate: YES (session-based)
+✗ Bearer token impersonate: NO (requires session cookies)
+✗ Stateless impersonate: NOT AVAILABLE
+```
+
+---
+
+## 10. Token Exchange Resolution (2025-11-02)
+
+### Problem
+Initial token exchange implementation was failing with:
+```
+"Standard token exchange is not enabled for the requested client"
+```
+
+### Root Cause
+The `realm-export.json` was missing a critical attribute for Keycloak 26.2+ Standard Token Exchange:
+- Had: `"token.exchange.grant.enabled": "true"` ✓
+- Missing: `"client.token.exchange.standard.enabled": "true"` ❌
+
+### Fix Applied
+Updated `keycloak/realm-export.json` at line 128 to include both attributes:
+```json
+"attributes": {
+  "pkce.code.challenge.method": "S256",
+  "use.refresh.tokens": "true",
+  "backchannel.logout.session.required": "true",
+  "backchannel.logout.url": "http://app:80/index.php/apps/user_oidc/backchannel-logout/keycloak",
+  "oauth2.device.authorization.grant.enabled": "false",
+  "oidc.ciba.grant.enabled": "false",
+  "client_credentials.use_refresh_token": "false",
+  "display.on.consent.screen": "false",
+  "token.exchange.grant.enabled": "true",
+  "client.token.exchange.standard.enabled": "true"  // ADDED
+}
+```
+
+### Verification
+After recreating Keycloak with fresh realm import:
+```bash
+$ docker compose down -v keycloak && docker compose up -d keycloak
+$ uv run python tests/manual/test_token_exchange.py
+✅ Token Exchange Test PASSED
+```
+
+### Current Status
+- ✅ RFC 8693 Token Exchange fully functional
+- ✅ Service account token acquisition works
+- ✅ Token exchange for internal tokens works
+- ✅ Exchanged tokens validate with Nextcloud APIs
+- ✅ Realm import automatically applies correct configuration
+- ⚠️ User impersonation still requires Keycloak Legacy V1
+
+### Files Modified
+- `keycloak/realm-export.json` - Added `client.token.exchange.standard.enabled` attribute
+- `docs/oauth-impersonation-findings.md` - Updated with resolution
+
+### Testing
+Run the complete token exchange flow:
+```bash
+uv run python tests/manual/test_token_exchange.py
+```

docs/oauth-setup.md

@@ -170,7 +170,7 @@ You have two options for managing OAuth clients:
 **How it works**:
 - MCP server automatically registers an OAuth client on first startup
 - Uses Nextcloud's dynamic client registration endpoint
-- Saves credentials to `.nextcloud_oauth_client.json`
+- Saves credentials to SQLite database
 - Reuses stored credentials on subsequent restarts
 - Re-registers automatically if credentials expire
 
@@ -253,9 +253,6 @@ NEXTCLOUD_PASSWORD=
 
 # Optional: MCP server URL (for OAuth callbacks)
 NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
-
-# Optional: Client storage path
-NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
 EOF
 ```
 
@@ -291,7 +288,6 @@ EOF
 | `NEXTCLOUD_OIDC_CLIENT_ID` | ⚠️ Mode B only | - | OAuth client ID |
 | `NEXTCLOUD_OIDC_CLIENT_SECRET` | ⚠️ Mode B only | - | OAuth client secret |
 | `NEXTCLOUD_MCP_SERVER_URL` | ⚠️ Optional | `http://localhost:8000` | MCP server URL for callbacks |
-| `NEXTCLOUD_OIDC_CLIENT_STORAGE` | ⚠️ Optional | `.nextcloud_oauth_client.json` | Client credentials storage path |
 | `NEXTCLOUD_USERNAME` | ❌ Must be empty | - | Leave empty for OAuth |
 | `NEXTCLOUD_PASSWORD` | ❌ Must be empty | - | Leave empty for OAuth |
 
@@ -334,7 +330,7 @@ INFO     OIDC discovery successful
 INFO     Attempting dynamic client registration...
 INFO     Dynamic client registration successful
 INFO     OAuth client ready: <client-id>...
-INFO     Saved OAuth client credentials to .nextcloud_oauth_client.json
+INFO     Saved OAuth client credentials to SQLite database
 INFO     OAuth initialization complete
 INFO     MCP server ready at http://127.0.0.1:8000
 ```
@@ -427,9 +423,9 @@ uv run nextcloud-mcp-server --oauth --log-level debug
 
 2. **Secure Credential Storage**
    ```bash
-   # Set restrictive permissions
-   chmod 600 .nextcloud_oauth_client.json
+   # Set restrictive permissions on environment file
    chmod 600 .env
+   # Database permissions are handled automatically
    ```
 
 3. **Use HTTPS for MCP Server**
@@ -474,7 +470,7 @@ services:
       NEXTCLOUD_OIDC_CLIENT_SECRET: ${NEXTCLOUD_OIDC_CLIENT_SECRET}
       NEXTCLOUD_MCP_SERVER_URL: http://your-server:8000
     volumes:
-      - ./oauth_client.json:/app/.nextcloud_oauth_client.json
+      - ./data:/app/data  # For SQLite database persistence
     command: ["--oauth", "--transport", "streamable-http"]
     restart: unless-stopped
 ```

docs/oauth-troubleshooting.md

@@ -14,9 +14,10 @@ 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) |
+| "Database error" on OAuth client storage | Database permissions issue | [Database Permission Error](#database-permission-error) |
 
 ## Configuration Issues
 
@@ -160,39 +161,38 @@ php occ config:app:set oidc expire_time --value "86400"  # 24 hours
 
 ---
 
-### File Permission Error
+### Database Permission Error
 
 **Error Message**:
 ```
-Permission denied when reading/writing .nextcloud_oauth_client.json
+Permission denied when accessing SQLite database
+Database is locked
 ```
 
-**Cause**: The server cannot access the OAuth client storage file.
+**Cause**: The server cannot access the SQLite database file.
 
 **Solution**:
 
 ```bash
-# Check file permissions
-ls -la .nextcloud_oauth_client.json
-
-# Fix file permissions (owner read/write only)
-chmod 600 .nextcloud_oauth_client.json
+# Check database directory permissions
+ls -la /app/data/
 
 # Ensure directory is writable
-chmod 755 $(dirname .nextcloud_oauth_client.json)
+chmod 755 /app/data
 
-# If file doesn't exist, ensure directory is writable
-mkdir -p $(dirname .nextcloud_oauth_client.json)
+# Check if database file exists and has correct permissions
+ls -la /app/data/tokens.db
+chmod 644 /app/data/tokens.db
+
+# If running in Docker, ensure volume is mounted correctly
+docker compose logs mcp-oauth | grep -i "database\|sqlite"
 ```
 
-For custom storage paths:
-```bash
-# Set custom path in .env
-NEXTCLOUD_OIDC_CLIENT_STORAGE=/path/to/custom/oauth_client.json
-
-# Ensure directory exists and is writable
-mkdir -p $(dirname /path/to/custom/oauth_client.json)
-chmod 755 $(dirname /path/to/custom/oauth_client.json)
+**For Docker deployments**:
+Ensure the data directory is properly mounted as a volume:
+```yaml
+volumes:
+  - ./data:/app/data  # Persistent storage for SQLite database
 ```
 
 ---
@@ -407,6 +407,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

@@ -16,64 +16,124 @@ While the core OAuth flow works, there are **pending upstream improvements** tha
 
 **Status**: 🟡 **Patch Required** (Pending Upstream)
 
-**Affected Component**: `user_oidc` app
+**Affected Component**: **Nextcloud core server** (`CORSMiddleware`)
 
 **Issue**: Bearer token authentication fails for app-specific APIs (Notes, Calendar, etc.) with `401 Unauthorized` errors, even though OCS APIs work correctly.
 
-**Root Cause**: The `CORSMiddleware` in Nextcloud logs out sessions created by Bearer token authentication when CSRF tokens are missing, which breaks API requests.
+**Root Cause**: The `CORSMiddleware` in Nextcloud core server logs out sessions when CSRF tokens are missing. Bearer token authentication creates a session (via `user_oidc` app), but doesn't include CSRF tokens (stateless authentication). The middleware detects the logged-in session without CSRF token and calls `session->logout()`, invalidating the request.
 
-**Solution**: Set the `app_api` session flag during Bearer token authentication to bypass CSRF checks.
+**Solution**: Allow Bearer token requests to bypass CORS/CSRF checks in `CORSMiddleware`, since Bearer tokens are stateless and don't require CSRF protection.
 
-**Upstream PR**: [nextcloud/user_oidc#1221](https://github.com/nextcloud/user_oidc/issues/1221)
+**Upstream PR**: [nextcloud/server#55878](https://github.com/nextcloud/server/pull/55878)
 
-**Workaround**: Manually apply the patch to `lib/User/Backend.php` in the `user_oidc` app
+**Workaround**: Manually apply the patch to `lib/private/AppFramework/Middleware/Security/CORSMiddleware.php` in Nextcloud core server
 
 **Impact**:
 - ✅ **Works**: OCS APIs (`/ocs/v2.php/cloud/capabilities`)
 - ❌ **Requires Patch**: App APIs (`/apps/notes/api/`, `/apps/calendar/`, etc.)
 
-**Files Modified**: `lib/User/Backend.php` in `user_oidc` app
+**Files Modified**: `lib/private/AppFramework/Middleware/Security/CORSMiddleware.php` in **Nextcloud core server**
 
 **Patch Summary**:
 ```php
-// Add before successful Bearer token authentication returns
-$this->session->set('app_api', true);
-```
-
-This is added at lines ~243, ~310, ~315, and ~337 in `Backend.php`.
-
----
-
-### 2. PKCE Support Advertisement in Discovery
-
-**Status**: 🟢 **PR Submitted** (Pending Review)
-
-**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.
-
-**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
-
-**Current Behavior**:
-- PKCE **functionally works** (the OIDC app accepts and validates PKCE)
-- PKCE just isn't **advertised** in discovery metadata
-
-**Recommended Fix**: Update `oidc` app to include:
-```json
-{
-  "code_challenge_methods_supported": ["S256"]
+// Allow Bearer token authentication for CORS requests
+// Bearer tokens are stateless and don't require CSRF protection
+$authorizationHeader = $this->request->getHeader('Authorization');
+if (!empty($authorizationHeader) && str_starts_with($authorizationHeader, 'Bearer ')) {
+    return;
 }
 ```
 
-**Workaround**: The MCP server implements PKCE validation and logs a warning if not advertised. Functionality still works.
+This is added before the CSRF check at line ~73 in `CORSMiddleware.php`.
 
-**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
+---
+
+### 2. JWT Token Support, Introspection, and Scope Validation
+
+**Status**: ✅ **Complete** (Merged Upstream)
+
+**Affected Component**: `oidc` app
+
+**Issue**: The OIDC app needed support for JWT tokens, token introspection, and enhanced scope validation for fine-grained authorization.
+
+**Resolution**: Complete JWT and scope validation support has been implemented and merged:
+
+**Upstream PR**: [H2CK/oidc#585](https://github.com/H2CK/oidc/pull/585) - ✅ **Merged**
+- **Changes**:
+  - JWT token generation and validation
+  - Token introspection endpoint (RFC 7662)
+  - Enhanced scope validation and parsing
+  - Custom scope support for Nextcloud apps
+- **Status**: Merged and available in v1.10.0+ of the `oidc` app
+
+---
+
+### 3. User Consent Management
+
+**Status**: ✅ **Complete** (Merged Upstream)
+
+**Affected Component**: `oidc` app
+
+**Issue**: The OIDC app needed proper user consent management for OAuth authorization flows.
+
+**Resolution**: Complete user consent management has been implemented and merged:
+
+**Upstream PR**: [H2CK/oidc#586](https://github.com/H2CK/oidc/pull/586) - ✅ **Merged**
+- **Changes**:
+  - User consent UI for OAuth authorization
+  - Consent expiration and cleanup
+  - Admin control for user consent settings
+  - Consent tracking and management
+- **Status**: Merged and available in v1.11.0+ of the `oidc` app
+
+---
+
+### 4. PKCE Support (RFC 7636)
+
+**Status**: ✅ **Complete** (Merged Upstream)
+
+**Affected Component**: `oidc` app
+
+**Issue**: The OIDC app lacked PKCE (Proof Key for Code Exchange) implementation per RFC 7636.
+
+**Resolution**: Full PKCE support has been implemented and merged upstream into the `oidc` app:
+
+**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
+
+**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", "plain"]
+}
+```
+
+**Database**:
+- New columns: `code_challenge` and `code_challenge_method` in `oc_oauth2_access_tokens`
+- Migration included for existing installations
+
+**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
 
 ---
 
@@ -81,24 +141,34 @@ 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 |
+| [server#55878](https://github.com/nextcloud/server/pull/55878) | Nextcloud core server | 🟡 Open | High | CORSMiddleware patch for Bearer tokens |
+| [H2CK/oidc#586](https://github.com/H2CK/oidc/pull/586) | `oidc` | ✅ Merged | Medium | ✅ User consent complete (v1.11.0+) |
+| [H2CK/oidc#585](https://github.com/H2CK/oidc/pull/585) | `oidc` | ✅ Merged | Medium | ✅ JWT tokens, introspection, scope validation (v1.10.0+) |
+| [H2CK/oidc#584](https://github.com/H2CK/oidc/pull/584) | `oidc` | ✅ Merged | ~~High~~ | ✅ PKCE support (RFC 7636) (v1.10.0+) |
 
 ## What Works Without Patches
 
 The following functionality works **out of the box** without any patches:
 
-✅ **OAuth Flow**:
-- OIDC discovery
+✅ **OAuth Flow** (requires `oidc` app v1.10.0+):
+- OIDC discovery with full PKCE support (RFC 7636)
 - 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
+- User consent management
 - Userinfo endpoint
 
+✅ **Token Features** (requires `oidc` app v1.10.0+):
+- JWT token generation and validation
+- Token introspection endpoint (RFC 7662)
+- Enhanced scope validation and parsing
+- Custom scope support for Nextcloud apps
+
 ✅ **MCP Server as Resource Server**:
 - Token validation via userinfo
 - Per-user client instances
 - Token caching
+- Scope-based authorization
 
 ✅ **Nextcloud OCS APIs**:
 - Capabilities endpoint
@@ -108,7 +178,7 @@ The following functionality works **out of the box** without any patches:
 
 The following functionality requires upstream patches:
 
-🟡 **App-Specific APIs** (Requires user_oidc#1221):
+🟡 **App-Specific APIs** (Requires Nextcloud core server CORSMiddleware patch):
 - Notes API (`/apps/notes/api/`)
 - Calendar API (CalDAV)
 - Contacts API (CardDAV)
@@ -116,9 +186,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
 
@@ -182,19 +252,23 @@ uv run pytest tests/client/test_oauth_playwright.py --browser firefox -v
 
 ## Monitoring Upstream Progress
 
-To track progress on these issues:
+To track progress on remaining issues:
 
-1. **Watch the upstream repositories**:
-   - [nextcloud/user_oidc](https://github.com/nextcloud/user_oidc)
-   - [nextcloud/oidc](https://github.com/nextcloud/oidc)
+1. **Watch the upstream repository**:
+   - [nextcloud/server](https://github.com/nextcloud/server)
 
-2. **Subscribe to specific issues**:
-   - [user_oidc#1221](https://github.com/nextcloud/user_oidc/issues/1221) - Bearer token support
+2. **Subscribe to the CORSMiddleware PR**:
+   - [server#55878](https://github.com/nextcloud/server/pull/55878) - CORSMiddleware Bearer token support
 
-3. **Check Nextcloud release notes** for mentions of:
+3. **Check Nextcloud server release notes** for mentions of:
    - Bearer token authentication improvements
-   - OIDC/OAuth enhancements
-   - AppAPI compatibility
+   - CORS middleware enhancements
+   - OAuth/OIDC API compatibility
+
+4. **Completed upstream work** (no monitoring needed):
+   - ✅ [H2CK/oidc#584](https://github.com/H2CK/oidc/pull/584) - PKCE support (v1.10.0+)
+   - ✅ [H2CK/oidc#585](https://github.com/H2CK/oidc/pull/585) - JWT, introspection, scopes (v1.10.0+)
+   - ✅ [H2CK/oidc#586](https://github.com/H2CK/oidc/pull/586) - User consent (v1.11.0+)
 
 ## Contributing
 
@@ -221,6 +295,6 @@ Want to help get these patches merged?
 
 ---
 
-**Last Updated**: 2025-10-14
+**Last Updated**: 2025-11-02
 
-**Next Review**: When PR #584 or issue #1221 has activity
+**Next Review**: When Nextcloud server CORSMiddleware PR has activity

docs/observability.md

@@ -0,0 +1,258 @@
+# Observability and Monitoring
+
+The Nextcloud MCP Server includes comprehensive observability features for production deployments:
+
+- **Prometheus metrics** for monitoring performance and health
+- **OpenTelemetry distributed tracing** for debugging request flows
+- **Structured JSON logging** with trace correlation
+- **Kubernetes integration** via ServiceMonitor and PrometheusRule
+
+## Quick Start
+
+### Local Development with Prometheus
+
+```bash
+# Enable metrics (enabled by default)
+export METRICS_ENABLED=true
+export METRICS_PORT=9090
+
+# Enable tracing (optional - tracing is enabled when OTEL_EXPORTER_OTLP_ENDPOINT is set)
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+
+# Start the server
+docker-compose up -d mcp
+```
+
+Access metrics at: `http://localhost:9090/metrics`
+
+### Kubernetes Deployment
+
+Metrics are automatically scraped if you have Prometheus Operator installed:
+
+```bash
+helm install nextcloud-mcp charts/nextcloud-mcp-server \
+  --set observability.metrics.enabled=true \
+  --set observability.tracing.enabled=true \
+  --set observability.tracing.endpoint=http://opentelemetry-collector:4317 \
+  --set serviceMonitor.enabled=true
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `METRICS_ENABLED` | `true` | Enable Prometheus metrics |
+| `METRICS_PORT` | `9090` | Port for metrics endpoint |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | - | OTLP gRPC endpoint (e.g., `http://otel-collector:4317`). Tracing is enabled when this is set. |
+| `OTEL_SERVICE_NAME` | `nextcloud-mcp-server` | Service name in traces |
+| `OTEL_TRACES_SAMPLER` | `always_on` | Trace sampling strategy |
+| `OTEL_TRACES_SAMPLER_ARG` | `1.0` | Sampling rate (0.0-1.0) |
+| `LOG_FORMAT` | `json` | Log format (`json` or `text`) |
+| `LOG_LEVEL` | `INFO` | Minimum log level |
+| `LOG_INCLUDE_TRACE_CONTEXT` | `true` | Include trace IDs in logs |
+
+### Helm Chart Configuration
+
+```yaml
+observability:
+  metrics:
+    enabled: true
+    port: 9090
+    path: /metrics
+
+  tracing:
+    enabled: true
+    endpoint: "http://opentelemetry-collector:4317"
+    samplingRate: 1.0
+
+  logging:
+    format: json
+    level: INFO
+    includeTraceContext: true
+
+serviceMonitor:
+  enabled: true
+  interval: 30s
+  scrapeTimeout: 10s
+```
+
+## Metrics
+
+### HTTP Server Metrics (RED)
+
+- `mcp_http_requests_total` - Total HTTP requests
+- `mcp_http_request_duration_seconds` - Request latency histogram
+- `mcp_http_requests_in_progress` - In-flight requests gauge
+
+### MCP Tool Metrics
+
+- `mcp_tool_calls_total` - Tool invocation count by status
+- `mcp_tool_duration_seconds` - Tool execution latency
+- `mcp_tool_errors_total` - Tool errors by type
+
+### Nextcloud API Metrics
+
+- `mcp_nextcloud_api_requests_total` - API calls by app and status
+- `mcp_nextcloud_api_duration_seconds` - API latency by app
+- `mcp_nextcloud_api_retries_total` - Retry count (429, timeout, etc.)
+
+### OAuth Flow Metrics
+
+- `mcp_oauth_token_validations_total` - Token validation count
+- `mcp_oauth_token_exchange_total` - Token exchange operations
+- `mcp_oauth_token_cache_hits_total` - Cache hit/miss rate
+- `mcp_oauth_refresh_token_operations_total` - Refresh token storage ops
+
+### Vector Sync Metrics (when enabled)
+
+- `mcp_vector_sync_documents_scanned_total` - Documents discovered
+- `mcp_vector_sync_documents_processed_total` - Processing results
+- `mcp_vector_sync_processing_duration_seconds` - Processing latency
+- `mcp_vector_sync_queue_size` - Current queue depth
+- `mcp_qdrant_operations_total` - Qdrant DB operations
+
+### Database Metrics
+
+- `mcp_db_operations_total` - DB operations (SQLite, Qdrant)
+- `mcp_db_operation_duration_seconds` - DB latency
+
+### Dependency Health
+
+- `mcp_dependency_health` - External dependency status (1=up, 0=down)
+- `mcp_dependency_check_duration_seconds` - Health check latency
+
+## Distributed Tracing
+
+### Span Hierarchy
+
+```
+HTTP POST /messages
+├── mcp.tool.nc_notes_create_note
+│   └── nextcloud.api.notes.POST
+│       └── httpx request (auto-instrumented)
+└── oauth.token.validate (if OAuth mode)
+    └── httpx request to IdP
+```
+
+### Span Attributes
+
+- **MCP tools**: `mcp.tool.name`, `mcp.tool.args` (sanitized)
+- **Nextcloud API**: `nextcloud.app`, `http.method`, `http.status_code`
+- **OAuth**: `oauth.operation`, `oauth.method`
+- **Vector sync**: `vector_sync.operation`, `vector_sync.document_count`
+
+### Trace Context in Logs
+
+When tracing is enabled, all logs include `trace_id` and `span_id`:
+
+```json
+{
+  "timestamp": "2025-01-09T12:34:56.789Z",
+  "level": "INFO",
+  "logger": "nextcloud_mcp_server.server.notes",
+  "message": "Note created successfully",
+  "trace_id": "a1b2c3d4e5f6...",
+  "span_id": "123456789abc...",
+  "note_id": 42
+}
+```
+
+## Dashboards
+
+### Prometheus Queries
+
+**Request Rate (req/s)**:
+```promql
+sum(rate(mcp_http_requests_total[5m])) by (method, endpoint)
+```
+
+**Error Rate (%)**:
+```promql
+sum(rate(mcp_http_requests_total{status_code=~"5.."}[5m]))
+  / sum(rate(mcp_http_requests_total[5m])) * 100
+```
+
+**P95 Latency**:
+```promql
+histogram_quantile(0.95,
+  sum(rate(mcp_http_request_duration_seconds_bucket[5m])) by (le, endpoint)
+)
+```
+
+**Top Tools by Volume**:
+```promql
+topk(10, sum(rate(mcp_tool_calls_total[5m])) by (tool_name))
+```
+
+**Nextcloud API Health**:
+```promql
+sum(rate(mcp_nextcloud_api_requests_total{status_code!~"2.."}[5m])) by (app)
+```
+
+## Alerts
+
+### Recommended Alert Rules
+
+**Critical**:
+- Server down for >5min
+- Error rate >5% for >5min
+- P95 latency >1s for >5min
+- Dependency down for >2min
+
+**Warning**:
+- Token validation errors >1% for >10min
+- Vector sync queue >100 for >15min
+- Qdrant slow (p95 >500ms) for >10min
+
+See `charts/nextcloud-mcp-server/templates/prometheusrule.yaml` for complete definitions.
+
+## Troubleshooting
+
+### Metrics Not Appearing
+
+1. Check metrics are enabled: `curl http://localhost:9090/metrics`
+2. Verify ServiceMonitor labels match Prometheus selector
+3. Check Prometheus target status: `http://prometheus:9090/targets`
+
+### Traces Not Appearing
+
+1. Verify OTLP endpoint is reachable: `curl http://otel-collector:4317`
+2. Check collector logs for errors
+3. Verify sampling rate is not 0.0
+4. Check trace backend (Jaeger/Tempo) connectivity
+
+### High Cardinality Metrics
+
+If you see cardinality warnings:
+- Middleware normalizes endpoints (e.g., `/user/123` → `/user/*`)
+- OAuth tokens are never included in metric labels
+- User IDs are not tracked (use tracing for per-user debugging)
+
+## Performance Impact
+
+- **Metrics**: <1% overhead (counters/histograms are very fast)
+- **Tracing**: ~2-5% overhead at 100% sampling
+- **JSON logging**: <1% overhead vs text logging
+
+**Recommendation**: Always enable metrics. Enable tracing in staging/production with 10-50% sampling.
+
+## Architecture
+
+The observability stack integrates at multiple layers:
+
+1. **HTTP Layer**: `ObservabilityMiddleware` tracks all HTTP requests
+2. **MCP Layer**: Tools use `@trace_mcp_tool` for span creation
+3. **Client Layer**: `BaseNextcloudClient` tracks all API calls
+4. **OAuth Layer**: Token operations are traced and metered
+5. **Background Tasks**: Vector sync operations emit metrics/traces
+
+All components use shared Prometheus `Registry` and OpenTelemetry `TracerProvider`.
+
+## References
+
+- [Prometheus Best Practices](https://prometheus.io/docs/practices/)
+- [OpenTelemetry Python SDK](https://opentelemetry.io/docs/languages/python/)
+- [Prometheus Operator](https://prometheus-operator.dev/)
+- [Grafana Dashboards](https://grafana.com/docs/grafana/latest/dashboards/)

docs/semantic-search-architecture.md

@@ -0,0 +1,921 @@
+# Semantic Search Architecture
+
+This document explains the architecture of the semantic search feature in the Nextcloud MCP Server, including background synchronization, vector search, and optional AI-generated answers via MCP sampling.
+
+> [!IMPORTANT]
+> **Status: Experimental**
+> - Disabled by default (`VECTOR_SYNC_ENABLED=false`)
+> - Currently supports **Notes app only** (multi-app architecture ready, additional apps planned)
+> - Requires additional infrastructure (Qdrant vector database + Ollama embedding service)
+> - RAG answer generation requires MCP client sampling support
+
+## Overview
+
+### What is Semantic Search?
+
+**Semantic search** finds information based on **meaning** rather than exact keyword matches. It uses vector embeddings to understand that "car" and "automobile" are similar, or that "bread recipe" matches "how to bake bread."
+
+**Traditional keyword search:**
+```
+Query: "machine learning"
+Matches: Only notes containing "machine learning" exactly
+Misses: Notes with "neural networks", "AI models", "deep learning"
+```
+
+**Semantic search:**
+```
+Query: "machine learning"
+Matches: Notes about machine learning, neural networks, AI, deep learning, etc.
+Understanding: Semantic similarity via vector embeddings
+```
+
+### Why It Matters
+
+Semantic search enables:
+- **Natural language queries** - Ask questions in plain language
+- **Conceptual discovery** - Find related content even with different terminology
+- **Cross-reference insights** - Connect ideas across your knowledge base
+- **AI-powered answers** - Generate summaries with citations (optional, requires MCP sampling)
+
+### Current Support
+
+- **Supported Apps**: Notes (fully implemented)
+- **Planned Apps**: Calendar events, Calendar tasks, Deck cards, Files (with text extraction), Contacts
+- **Architecture**: Multi-app plugin system ready, awaiting implementation
+
+## System Components
+
+```mermaid
+graph TB
+    subgraph "MCP Client"
+        Client[Claude Desktop, IDEs, etc.]
+    end
+
+    subgraph "Nextcloud MCP Server"
+        MCP[MCP Server]
+        Scanner[Background Scanner<br/>Hourly Change Detection]
+        Queue[Document Queue]
+        Processor[Embedding Processors<br/>Concurrent Workers]
+    end
+
+    subgraph "Infrastructure"
+        Qdrant[(Qdrant<br/>Vector Database)]
+        Ollama[Ollama<br/>Embedding Service]
+        NC[Nextcloud<br/>Notes API, CalDAV, etc.]
+    end
+
+    Client <-->|MCP Protocol| MCP
+    Scanner -->|Fetch Changes| NC
+    Scanner -->|Enqueue Documents| Queue
+    Queue -->|Process Batch| Processor
+    Processor -->|Generate Embeddings| Ollama
+    Processor -->|Store Vectors| Qdrant
+    MCP -->|Search Queries| Qdrant
+    MCP -->|Verify Access| NC
+```
+
+**Component Roles:**
+
+- **MCP Server**: Exposes semantic search tools (`nc_semantic_search`, `nc_semantic_search_answer`, `nc_get_vector_sync_status`)
+- **Background Scanner**: Discovers changed documents every hour using ETag-based change detection
+- **Document Queue**: Holds pending documents for embedding generation
+- **Embedding Processors**: Generate vector embeddings via Ollama (concurrent workers)
+- **Qdrant Vector Database**: Stores document vectors with metadata and user_id filtering
+- **Ollama Embedding Service**: Converts text to 768-dimensional vectors (default: `nomic-embed-text` model)
+- **Nextcloud APIs**: Source of truth for documents and access control verification
+
+## How It Works: Background Synchronization
+
+Background synchronization runs automatically when `VECTOR_SYNC_ENABLED=true`, discovering changes and indexing documents without user intervention.
+
+```mermaid
+sequenceDiagram
+    participant Timer
+    participant Scanner
+    participant NC as Nextcloud API
+    participant Queue
+    participant Processor
+    participant Ollama
+    participant Qdrant
+
+    Timer->>Scanner: Trigger (hourly)
+    Scanner->>NC: Fetch all notes<br/>(Notes API)
+    NC-->>Scanner: Notes with ETags
+    Scanner->>Qdrant: Check indexed documents
+    Qdrant-->>Scanner: Existing ETags
+    Scanner->>Scanner: Identify changes<br/>(new/modified/deleted)
+    Scanner->>Queue: Enqueue changed docs
+
+    loop Continuous Processing
+        Processor->>Queue: Fetch batch
+        Queue-->>Processor: Documents
+        Processor->>Ollama: Generate embeddings
+        Ollama-->>Processor: 768-dim vectors
+        Processor->>Qdrant: Upsert vectors<br/>(with user_id, doc_type)
+    end
+```
+
+### Scanner Behavior
+
+**Hourly Trigger:**
+- Runs every hour (configurable)
+- Fetches all notes from Nextcloud Notes API
+- Compares ETags with Qdrant's indexed state
+- Enqueues new/modified documents
+
+**Change Detection:**
+- **New documents**: No entry in Qdrant → enqueue for indexing
+- **Modified documents**: ETag mismatch → enqueue for re-indexing
+- **Deleted documents**: In Qdrant but not in Nextcloud → delete from Qdrant
+
+**Multi-App Plugin Architecture:**
+```python
+# Each app implements DocumentScanner interface
+class NotesScanner(DocumentScanner):
+    async def scan(self) -> list[Document]:
+        # Fetch notes, detect changes, return documents
+```
+
+Currently only `NotesScanner` is implemented. Future: `CalendarScanner`, `DeckScanner`, `FilesScanner`, etc.
+
+### Queue Processing
+
+**Document Queue:**
+- In-memory FIFO queue (not persistent across restarts)
+- Holds documents pending embedding generation
+- Batch processing for efficiency
+
+**Processor Pool:**
+- Concurrent workers using `anyio.TaskGroup`
+- Process documents in parallel (default: 4 workers)
+- Each worker: fetch document → generate embedding → store in Qdrant
+
+**Backpressure Handling:**
+- Queue size limits prevent memory exhaustion
+- Slow consumers (Ollama) naturally pace the system
+
+### Vector Storage
+
+**Qdrant Collection Schema:**
+```
+{
+  "id": "note_123",
+  "vector": [768 dimensions],
+  "payload": {
+    "user_id": "alice",
+    "doc_type": "note",
+    "doc_id": "123",
+    "title": "Machine Learning Notes",
+    "content": "Neural networks are...",
+    "etag": "abc123",
+    "last_modified": "2025-01-15T10:30:00Z"
+  }
+}
+```
+
+**Key Fields:**
+- `user_id`: Multi-tenancy filtering (each user's vectors isolated)
+- `doc_type`: App identifier ("note", "event", "card", etc.)
+- `etag`: Change detection for incremental updates
+- `chunk_index`: Position of this chunk within the document (0-indexed)
+- `total_chunks`: Total number of chunks for this document
+- `excerpt`: First 200 characters of chunk (for display)
+
+### Document Chunking Strategy
+
+Documents are chunked before embedding to handle content larger than the embedding model's context window and to improve search precision.
+
+**Configuration:**
+```dotenv
+DOCUMENT_CHUNK_SIZE=512       # Words per chunk (default)
+DOCUMENT_CHUNK_OVERLAP=50     # Overlapping words between chunks (default)
+```
+
+**Chunking Process:**
+1. **Text combination**: Document title + content (e.g., `"Note Title\n\nNote content..."`)
+2. **Word-based splitting**: Simple whitespace tokenization
+3. **Sliding window**: Create overlapping chunks
+4. **Individual embedding**: Each chunk gets its own vector
+5. **Separate storage**: Each chunk stored as distinct point in Qdrant
+
+**Example:**
+```
+Document (1000 words):
+→ Chunk 0: words 0-511
+→ Chunk 1: words 462-973 (overlaps by 50 words)
+→ Chunk 2: words 924-999 (last chunk, partial)
+
+Each chunk stored as separate vector with metadata:
+- chunk_index: 0, 1, 2
+- total_chunks: 3
+- excerpt: First 200 chars of each chunk
+```
+
+**Search Behavior:**
+- **Vector search** operates on chunks (not whole documents)
+- **Deduplication** collapses multiple matching chunks from same document
+- **Best match** returns highest-scoring chunk's excerpt
+- **Access verification** still performed at document level
+
+**Tuning Recommendations:**
+- **Small chunks (256-384 words)**: More precise, less context, more storage
+- **Large chunks (768-1024 words)**: More context, less precise, less storage
+- **Overlap (10-20% of chunk size)**: Preserves context across boundaries
+- **Match to embedding model**: Consider model's context window when sizing
+
+**Important**: Changing chunk size requires re-embedding all documents. Use the collection naming strategy to manage different chunking configurations.
+
+### Collection Naming and Model Switching
+
+**Auto-generated collection names:**
+- **Format:** `{deployment-id}-{model-name}`
+- **Deployment ID:** `OTEL_SERVICE_NAME` (if configured) or `hostname` (fallback)
+- **Model name:** `OLLAMA_EMBEDDING_MODEL`
+- **Example:** `"my-mcp-server-nomic-embed-text"`, `"mcp-container-all-minilm"`
+
+**Why model-based naming:**
+- Ensures each embedding model gets its own collection
+- Prevents dimension mismatches when switching models
+- Enables safe model experimentation (new model = new collection)
+- Supports multi-server deployments (different deployment IDs)
+
+**Switching embedding models:**
+
+Collections are **mutually exclusive** - vectors from one embedding model cannot be used with another. When you change the embedding model:
+
+1. **New collection is created** with the new model's dimensions
+2. **Full re-embedding occurs** - scanner processes all documents again
+3. **Old collection remains** - can be deleted manually if no longer needed
+4. **Dimension validation** - server fails fast if collection dimension doesn't match model
+
+**Example workflow:**
+```bash
+# Start with nomic-embed-text (768 dimensions)
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# Collection: "my-server-nomic-embed-text"
+# → Scanner indexes 1000 notes → 1000 vectors in collection
+
+# Switch to all-minilm (384 dimensions)
+OLLAMA_EMBEDDING_MODEL=all-minilm
+# Collection: "my-server-all-minilm"
+# → Scanner detects 0 indexed documents → re-embeds 1000 notes
+# → Old collection "my-server-nomic-embed-text" still exists in Qdrant
+```
+
+**Re-embedding performance:**
+- CPU-only: 1-5 notes/second
+- With GPU: 50-200 notes/second
+- 1000 notes: 3-16 minutes (CPU) or 5-20 seconds (GPU)
+
+**Multi-server deployments:**
+
+Multiple MCP servers can share one Qdrant instance safely:
+
+```bash
+# Server 1 (Production)
+OTEL_SERVICE_NAME=mcp-prod
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# → Collection: "mcp-prod-nomic-embed-text"
+
+# Server 2 (Staging with different model)
+OTEL_SERVICE_NAME=mcp-staging
+OLLAMA_EMBEDDING_MODEL=all-minilm
+# → Collection: "mcp-staging-all-minilm"
+```
+
+Each deployment gets its own collection - no naming collisions or dimension conflicts.
+
+## How It Works: Semantic Search
+
+Semantic search converts user queries into vectors and finds similar documents using cosine similarity.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant MCP as MCP Server
+    participant Ollama
+    participant Qdrant
+    participant NC as Nextcloud API
+
+    User->>MCP: nc_semantic_search("machine learning")
+    MCP->>MCP: Check OAuth scope<br/>(semantic:read)
+    MCP->>Ollama: Generate query embedding
+    Ollama-->>MCP: Query vector (768-dim)
+    MCP->>Qdrant: Search similar vectors<br/>(filter: user_id=alice)
+    Qdrant-->>MCP: Top K results<br/>(with similarity scores)
+
+    loop For each result
+        MCP->>NC: Verify access<br/>(fetch note by ID)
+        alt Access granted
+            NC-->>MCP: Note metadata
+        else Access denied (404/401)
+            MCP->>MCP: Filter out result
+        end
+    end
+
+    MCP-->>User: Search results<br/>(with scores, excerpts)
+```
+
+### Dual-Phase Authorization
+
+**Phase 1: OAuth Scope Check**
+- Verify user has `semantic:read` scope
+- Rejects unauthorized users immediately
+
+**Phase 2: Per-Document Verification**
+- For each search result, fetch document via app API (Notes, Calendar, etc.)
+- If fetch succeeds (200 OK), user has access
+- If fetch fails (404 Not Found, 401 Unauthorized), filter out result
+- **Security**: Prevents information leakage from vector search alone
+
+**Rationale:**
+- Vector database doesn't know about sharing, permissions changes, or deleted documents
+- App APIs are source of truth for access control
+- Verification ensures users only see documents they can access
+
+### Search Flow
+
+1. **Query Embedding**: Convert user query to 768-dimensional vector via Ollama
+2. **Vector Search**: Find top K similar vectors in Qdrant (cosine similarity)
+3. **User Filtering**: Qdrant pre-filters by `user_id` (multi-tenancy)
+4. **Access Verification**: Fetch each document via app API to verify current access
+5. **Result Ranking**: Return results sorted by similarity score
+6. **Response**: Include document excerpts, metadata, and similarity scores
+
+### Performance
+
+- **Query latency**: 50-200ms typical (embedding + vector search + verification)
+- **Accuracy**: Depends on embedding model quality (`nomic-embed-text` recommended)
+- **Scalability**: Qdrant handles millions of vectors efficiently
+
+## How It Works: RAG with MCP Sampling (Optional)
+
+The `nc_semantic_search_answer` tool generates AI-powered answers with citations using **MCP sampling** - requesting the MCP client's LLM to generate text.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant MCP as MCP Server
+    participant Client as MCP Client<br/>(Claude Desktop)
+    participant LLM as Client's LLM<br/>(Claude, GPT, etc.)
+
+    User->>MCP: nc_semantic_search_answer("What are my Q1 goals?")
+    MCP->>MCP: Semantic search<br/>(find relevant notes)
+    MCP->>MCP: Construct prompt<br/>(query + documents + instructions)
+    MCP->>Client: Sampling request<br/>(MCP Protocol)
+    Client->>User: Prompt for approval<br/>(optional, client-controlled)
+    User-->>Client: Approve
+    Client->>LLM: Generate answer<br/>(with context)
+    LLM-->>Client: Answer with citations
+    Client-->>MCP: Sampling response
+    MCP-->>User: Generated answer<br/>(with source documents)
+```
+
+### MCP Sampling Architecture
+
+**Why MCP Sampling?**
+- **No server-side LLM**: MCP server has no API keys, doesn't call LLMs directly
+- **Client controls everything**: Which model, who pays, user approval prompts
+- **Privacy**: Documents stay with the client's LLM provider, not a third-party
+- **Flexibility**: Works with any MCP client that supports sampling (Claude Desktop, future clients)
+
+**Prompt Construction:**
+```
+User Query: {query}
+
+Relevant Documents:
+1. Document: {title} (Note)
+   Content: {excerpt}
+
+2. Document: {title} (Note)
+   Content: {excerpt}
+
+Instructions:
+- Provide a comprehensive answer to the user's query
+- Use the documents above as context
+- Include citations: "According to Document 1 (title)..."
+- If documents don't contain enough information, say so
+```
+
+**Graceful Fallback:**
+```python
+try:
+    result = await ctx.session.create_message(...)
+    return answer_with_citations
+except Exception as e:
+    # Fallback: Return documents without generated answer
+    return SearchResponse(
+        generated_answer=f"[Sampling unavailable: {e}]",
+        sources=search_results
+    )
+```
+
+**Client Support:**
+- **Requires**: MCP client with sampling capability
+- **Known support**: Claude Desktop (as of Claude 3.5+)
+- **Graceful degradation**: Returns raw documents if sampling unavailable
+
+## Authentication & Security
+
+### OAuth Scopes
+
+**`semantic:read`** - Search permission
+- Allows using `nc_semantic_search` and `nc_semantic_search_answer` tools
+- Does NOT grant access to documents (verified via app APIs)
+- Required for any semantic search operation
+
+**`semantic:write`** - Sync control permission
+- Allows enabling/disabling background sync (`provision_vector_sync`, `deprovision_vector_sync`)
+- Controls whether user's documents are indexed
+- Currently not implemented in OAuth mode (BasicAuth only)
+
+### Dual-Phase Authorization Pattern
+
+**Phase 1: Scope Check** (semantic:read)
+- Verifies user authorized to search
+- Prevents unauthorized vector database access
+
+**Phase 2: Document Verification** (app-specific APIs)
+- For each search result, fetch via Notes API, CalDAV, etc.
+- If user can fetch → include in results
+- If user cannot fetch (404/401) → filter out
+- **Security**: Vector search cannot leak documents user shouldn't see
+
+**Example Scenario:**
+1. Alice creates note "Secret Project X"
+2. Background sync indexes note with `user_id=alice`
+3. Bob searches for "project"
+4. Vector search finds "Secret Project X" (vector similarity)
+5. Qdrant filters by `user_id=bob` → no match (Alice's note excluded)
+6. Even if Bob somehow got the doc_id, Phase 2 verification would fail (404 Not Found)
+
+### Offline Access for Background Sync
+
+**Why needed:**
+- Background scanner runs hourly without user interaction
+- Requires valid access tokens to fetch documents from Nextcloud APIs
+- User's session token expires after hours/days
+
+**OAuth Mode (ADR-004 Flow 2):**
+- User explicitly provisions offline access via `provision_nextcloud_access` tool
+- Server requests `offline_access` scope → receives refresh token
+- Refresh token stored securely (database, encrypted)
+- Background sync uses refresh tokens to obtain access tokens
+
+**BasicAuth Mode:**
+- Username/password stored in environment variables
+- Always available for background operations
+- Simpler but less secure (credentials never expire)
+
+## Deployment Modes
+
+### Authentication Modes
+
+| Mode | Security | Offline Access | Background Sync | Best For |
+|------|----------|----------------|-----------------|----------|
+| **BasicAuth** | Lower (credentials in env) | Always available | ✅ Works immediately | Single-user, development, testing |
+| **OAuth** | Higher (tokens, scopes) | User must provision | ⚠️ Not yet implemented | Multi-user, production |
+
+**BasicAuth:**
+- Set `NEXTCLOUD_USERNAME` and `NEXTCLOUD_PASSWORD`
+- Background sync works immediately when `VECTOR_SYNC_ENABLED=true`
+- Credentials stored in `.env` file (secure server access required)
+
+**OAuth:**
+- Client authenticates with `semantic:read` scope
+- User must explicitly provision offline access (future: `provision_vector_sync` tool)
+- Background sync only works for users who provisioned access
+- More secure: tokens expire, user controls access
+
+### Qdrant Deployment Modes
+
+| Mode | Configuration | Persistence | Scalability | Best For |
+|------|---------------|-------------|-------------|----------|
+| **In-Memory** (default) | `QDRANT_LOCATION=:memory:` | ❌ Lost on restart | Single instance | Testing, development |
+| **Persistent Local** | `QDRANT_LOCATION=/data/qdrant` | ✅ Survives restarts | Single instance | Small deployments |
+| **Network** | `QDRANT_URL=http://qdrant:6333` | ✅ Dedicated service | ✅ Horizontal scaling | Production |
+
+**In-Memory Mode:**
+```bash
+VECTOR_SYNC_ENABLED=true
+# QDRANT_LOCATION not set → defaults to :memory:
+```
+- Fastest startup
+- No disk I/O
+- **Warning**: All vectors lost when server restarts (must re-index)
+
+**Persistent Local Mode:**
+```bash
+VECTOR_SYNC_ENABLED=true
+QDRANT_LOCATION=/var/lib/qdrant
+```
+- Vectors survive restarts
+- Single server only (no distributed setup)
+- Disk I/O for durability
+
+**Network Mode (Recommended for Production):**
+```bash
+VECTOR_SYNC_ENABLED=true
+QDRANT_URL=http://qdrant:6333
+QDRANT_API_KEY=secret  # optional
+```
+- Dedicated Qdrant service (Docker, Kubernetes)
+- Horizontal scaling (multiple MCP servers → one Qdrant)
+- High availability options
+
+### Embedding Service Options
+
+| Service | Configuration | Cost | Performance | Best For |
+|---------|---------------|------|-------------|----------|
+| **Ollama** (recommended) | `OLLAMA_BASE_URL=http://ollama:11434` | Free (self-hosted) | Fast (local GPU) | Production, development |
+| **OpenAI** (future) | `OPENAI_API_KEY=sk-...` | Paid (API) | Fast (cloud) | Cloud deployments |
+| **Fallback** | No config | Free | Slow (random) | Testing only (not production) |
+
+**Ollama Setup (Recommended):**
+```bash
+# docker-compose.yml
+services:
+  ollama:
+    image: ollama/ollama
+    volumes:
+      - ollama-data:/root/.ollama
+    ports:
+      - "11434:11434"
+
+# Pull embedding model
+docker compose exec ollama ollama pull nomic-embed-text
+```
+
+**Environment Configuration:**
+```bash
+OLLAMA_BASE_URL=http://ollama:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # 768-dimensional vectors
+```
+
+**Model Options:**
+- `nomic-embed-text` (default): 768-dim, optimized for semantic search
+- `all-minilm`: Smaller, faster, slightly less accurate
+- `mxbai-embed-large`: Larger, more accurate, slower
+
+## Configuration Overview
+
+### Key Environment Variables
+
+**Enable Semantic Search:**
+```bash
+VECTOR_SYNC_ENABLED=true  # Default: false (opt-in)
+```
+
+**Qdrant Vector Database:**
+```bash
+# In-memory mode (default if VECTOR_SYNC_ENABLED=true)
+# QDRANT_LOCATION not set → uses :memory:
+
+# Persistent local mode
+QDRANT_LOCATION=/var/lib/qdrant
+
+# Network mode (production)
+QDRANT_URL=http://qdrant:6333
+QDRANT_API_KEY=secret  # optional
+```
+
+**Ollama Embedding Service:**
+```bash
+OLLAMA_BASE_URL=http://ollama:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Default
+```
+
+**Scanner Configuration:**
+```bash
+VECTOR_SYNC_INTERVAL=3600  # Scan interval in seconds (default: 1 hour)
+```
+
+### Resource Requirements
+
+**Qdrant:**
+- **Memory**: ~100-200 MB base + ~1 KB per vector (1M vectors ≈ 1 GB)
+- **Disk**: Persistent mode only, ~200 bytes per vector
+- **CPU**: Low (indexing) to moderate (search)
+
+**Ollama:**
+- **Memory**: 2-4 GB for `nomic-embed-text` model
+- **CPU**: High during embedding generation, idle otherwise
+- **GPU**: Optional but recommended (10-100x faster)
+
+**MCP Server:**
+- **Memory**: +50-100 MB for background sync workers
+- **CPU**: Moderate during scanning/processing, low otherwise
+
+### Trade-offs
+
+| Consideration | In-Memory Qdrant | Persistent Qdrant | Network Qdrant |
+|---------------|------------------|-------------------|----------------|
+| Setup complexity | ✅ Minimal | ✅ Easy | ⚠️ Requires separate service |
+| Durability | ❌ Lost on restart | ✅ Survives restarts | ✅ Survives restarts |
+| Scalability | ❌ Single instance | ❌ Single instance | ✅ Horizontal scaling |
+| Performance | ✅ Fastest | ✅ Fast | ⚠️ Network latency |
+
+## Operational Behavior
+
+### What Happens When VECTOR_SYNC_ENABLED=true
+
+**Immediate (Server Startup):**
+1. MCP server connects to Qdrant (creates collection if needed)
+2. MCP server connects to Ollama (verifies embedding model available)
+3. Background scanner starts (schedules hourly runs)
+4. Document queue and processors initialize
+
+**First Scan (Within 1 hour):**
+1. Scanner fetches all notes from Nextcloud
+2. Compares with Qdrant (likely empty on first run)
+3. Enqueues all notes for indexing
+4. Processors generate embeddings (may take minutes for large note collections)
+5. Vectors stored in Qdrant with user_id filtering
+
+**Hourly Thereafter:**
+1. Scanner fetches all notes
+2. Identifies new/modified/deleted notes (ETag comparison)
+3. Enqueues changes only
+4. Incremental updates processed
+
+### Performance Expectations
+
+**Embedding Generation:**
+- **Without GPU**: 1-5 notes/second (CPU-bound)
+- **With GPU**: 50-200 notes/second (highly parallel)
+- **Initial indexing**: 100 notes ≈ 20-100 seconds (CPU), 1-2 seconds (GPU)
+
+**Search Query:**
+- **Embedding generation**: 50-100ms
+- **Vector search**: 10-50ms (depends on collection size)
+- **Access verification**: 20-100ms per document (Nextcloud API calls)
+- **Total latency**: 100-300ms typical
+
+**Resource Usage:**
+- **Idle**: Minimal (background scanner sleeps)
+- **Scanning**: Moderate CPU (ETag checks, API calls)
+- **Processing**: High CPU/GPU (embedding generation)
+- **Searching**: Low to moderate (depends on query frequency)
+
+### Background Sync Behavior
+
+**Scanner Triggers:**
+- Hourly (configurable via `VECTOR_SYNC_INTERVAL`)
+- Manual trigger via `nc_trigger_vector_sync` (future)
+
+**Queue Processing:**
+- Continuous (workers always running)
+- Batch processing (fetch 10 documents at a time)
+- Concurrent workers (4 by default)
+
+**Error Handling:**
+- Individual document failures logged but don't stop scanning
+- Retries for transient errors (network timeouts, rate limits)
+- Failed documents skipped, re-attempted on next scan
+
+**What Gets Indexed:**
+- **Notes**: All notes accessible to the authenticated user
+- **Future**: Calendar events, tasks, deck cards, files with text extraction, contacts
+
+## Monitoring & Observability
+
+### MCP Tools
+
+**`nc_get_vector_sync_status`** - Check sync status
+```python
+{
+  "total_documents": 1234,
+  "indexed_documents": 1200,
+  "pending_documents": 34,
+  "sync_enabled": true,
+  "last_scan": "2025-01-15T14:30:00Z",
+  "status": "syncing"  # idle | syncing | error
+}
+```
+
+**Interpreting Status:**
+- `idle`: No pending work, last scan completed successfully
+- `syncing`: Currently processing documents
+- `error`: Last scan failed (check logs)
+
+### Logs to Check
+
+**Scanner Logs:**
+```
+[INFO] Vector sync scanner started (interval: 3600s)
+[INFO] Scanning notes: found 150 documents
+[INFO] Changes detected: 5 new, 2 modified, 1 deleted
+[INFO] Enqueued 7 documents for processing
+```
+
+**Processor Logs:**
+```
+[INFO] Processing document: note_123
+[DEBUG] Generated embedding (768 dimensions)
+[INFO] Stored vector in Qdrant: note_123
+```
+
+**Error Logs:**
+```
+[ERROR] Failed to generate embedding for note_123: Connection timeout
+[WARN] Qdrant connection lost, retrying...
+[ERROR] Ollama embedding failed: Model not found
+```
+
+**Log Locations:**
+- **Docker**: `docker compose logs mcp`
+- **Local**: stdout (redirect to file if needed)
+- **Kubernetes**: `kubectl logs -f deployment/nextcloud-mcp-server`
+
+### Metrics to Monitor
+
+**Indexing Progress:**
+- Total documents vs indexed documents
+- Pending queue size
+- Processing rate (docs/second)
+
+**Search Performance:**
+- Query latency (p50, p95, p99)
+- Results per query
+- Verification overhead (API calls per query)
+
+**Resource Usage:**
+- Qdrant memory/disk usage
+- Ollama CPU/GPU usage
+- MCP server memory
+
+For detailed observability setup, see [docs/observability.md](observability.md).
+
+## Troubleshooting from Architecture Perspective
+
+### Documents Not Appearing in Search
+
+**Diagnosis Flow:**
+1. Check sync status: `nc_get_vector_sync_status`
+   - `sync_enabled: false` → Enable with `VECTOR_SYNC_ENABLED=true`
+   - `status: error` → Check scanner logs for failures
+2. Check queue size:
+   - `pending_documents > 0` → Processing in progress, wait
+   - `pending_documents == 0` but `indexed_documents` low → Scan hasn't run yet (wait up to 1 hour)
+3. Check Qdrant:
+   - Connection errors in logs → Verify `QDRANT_URL` or `QDRANT_LOCATION`
+   - Collection empty → First scan hasn't completed
+4. Check Ollama:
+   - Embedding errors in logs → Verify `OLLAMA_BASE_URL`
+   - Model not found → Pull model: `ollama pull nomic-embed-text`
+
+**Common Causes:**
+- Sync disabled (default): Enable `VECTOR_SYNC_ENABLED=true`
+- Ollama not running: Start Ollama service
+- Qdrant not accessible: Check network/URL
+- First scan in progress: Wait up to 1 hour + processing time
+
+### Slow Search Performance
+
+**Diagnosis:**
+1. **Query embedding slow (>500ms)**:
+   - Ollama overloaded or CPU-bound
+   - Solution: Use GPU, upgrade CPU, or reduce concurrent requests
+2. **Vector search slow (>200ms)**:
+   - Large collection (millions of vectors)
+   - Solution: Use network Qdrant with SSDs, add indexing
+3. **Verification slow (>500ms)**:
+   - Many results to verify (10+ documents)
+   - Nextcloud API slow or overloaded
+   - Solution: Reduce `limit` parameter, optimize Nextcloud
+
+**Performance Tuning:**
+- Reduce search `limit` (default: 10 results)
+- Use network Qdrant for large collections
+- Enable Ollama GPU acceleration
+- Check Nextcloud API response times
+
+### Background Sync Stopped
+
+**Diagnosis:**
+1. Check logs for errors:
+   - Authentication failures (401/403) → Token expired (OAuth) or credentials invalid (BasicAuth)
+   - Connection timeouts → Network issues with Nextcloud/Qdrant/Ollama
+   - Rate limiting (429) → Reduce scan frequency
+2. Check `nc_get_vector_sync_status`:
+   - `status: error` → See logs for details
+   - `last_scan` timestamp old (>2 hours) → Scanner may have crashed
+3. Verify services:
+   - Qdrant accessible: `curl http://qdrant:6333/`
+   - Ollama accessible: `curl http://ollama:11434/api/tags`
+   - Nextcloud accessible: Check API health
+
+**OAuth Mode (Future):**
+- Offline access token expired → Re-provision via `provision_vector_sync`
+- User deprovisioned access → Sync stops intentionally
+
+### Out of Memory
+
+**Diagnosis:**
+1. Check Qdrant mode:
+   - In-memory mode with large collection → Switch to persistent or network mode
+2. Check embedding batch size:
+   - Too many documents processed simultaneously → Reduce worker count
+3. Check Ollama memory:
+   - Large models loaded → Use smaller embedding model
+
+**Solutions:**
+- Use persistent or network Qdrant (frees server memory)
+- Reduce concurrent processor workers
+- Use smaller embedding model (`all-minilm` instead of `nomic-embed-text`)
+- Increase server memory allocation
+
+## Limitations & Future Work
+
+### Current Limitations
+
+1. **Notes App Only**
+   - Architecture supports multiple apps (plugin system ready)
+   - Only `NotesScanner` and `NotesProcessor` implemented
+   - Future: Calendar, Deck, Files, Contacts
+
+2. **MCP Sampling Support**
+   - `nc_semantic_search_answer` requires client sampling capability
+   - Not all MCP clients support sampling yet
+   - Graceful fallback: Returns documents without generated answer
+
+3. **OAuth Background Sync**
+   - User-controlled background jobs not yet implemented
+   - Currently works in BasicAuth mode only
+   - Future: Users opt-in via `provision_vector_sync` tool
+
+4. **No Incremental Updates**
+   - Document changes trigger full re-embedding
+   - Cannot update just modified paragraphs
+   - Future: Paragraph-level chunking and incremental updates
+
+5. **No Query Caching**
+   - Each search generates new query embedding
+   - Repeated queries re-search Qdrant
+   - Future: Cache recent query embeddings and results
+
+6. **Single Embedding Model**
+   - Uses one model for all documents and queries
+   - Cannot customize per app or user
+   - Future: App-specific or user-selected models
+
+### Future Enhancements
+
+**Multi-App Support** (In Progress):
+- Scanner plugins for Calendar, Deck, Files, Contacts
+- Unified vector search across all apps
+- App-specific metadata in vector payloads
+
+**User-Controlled Sync (OAuth Mode)**:
+- `provision_vector_sync` and `deprovision_vector_sync` tools
+- Per-user background job scheduling
+- User dashboard for sync status and controls
+
+**Advanced Search Features**:
+- Hybrid search (vector + keyword combined)
+- Filtering by date range, app type, tags
+- Aggregations and faceted search
+- Search result explanations (why this matched)
+
+**Performance Optimizations**:
+- Query caching for repeated searches
+- Incremental document updates (paragraph-level)
+- Batch query processing
+- Qdrant HNSW indexing tuning
+
+**Embedding Improvements**:
+- Support for OpenAI embeddings (ada-002, text-embedding-3)
+- Multi-language embedding models
+- Fine-tuned models for Nextcloud content
+- Paragraph-level chunking for long documents
+
+## References
+
+### Architecture Decision Records (ADRs)
+
+- **[ADR-003: Vector Database Semantic Search](ADR-003-vector-database-semantic-search.md)** - Qdrant selection rationale, embedding strategy, hybrid search (superseded by ADR-007 but technical decisions remain valid)
+- **[ADR-007: Background Vector Sync Job Management](ADR-007-background-vector-sync-job-management.md)** - Current implementation, Scanner-Queue-Processor architecture, plugin system
+- **[ADR-008: MCP Sampling for Semantic Search](ADR-008-mcp-sampling-for-semantic-search.md)** - RAG with MCP sampling, client-server separation, prompt construction
+- **[ADR-009: Semantic Search OAuth Scope](ADR-009-semantic-search-oauth-scope.md)** - OAuth scope model, dual-phase authorization, security rationale
+
+### Configuration & Setup
+
+- **[Configuration Guide](configuration.md)** - Environment variables, Qdrant setup, Ollama setup, detailed configuration options
+- **[Installation Guide](installation.md)** - Deployment options (Docker, Kubernetes, local)
+- **[Running the Server](running.md)** - Starting the server, transport options, testing
+
+### Monitoring & Troubleshooting
+
+- **[Observability Guide](observability.md)** - Logging, metrics, tracing, debugging
+- **[Troubleshooting](troubleshooting.md)** - General issues and solutions
+
+### Related Documentation
+
+- **[OAuth Architecture](oauth-architecture.md)** - OAuth flows, scopes, token management
+- **[Comparison with Context Agent](comparison-context-agent.md)** - When to use Nextcloud MCP Server vs Context Agent
+
+---
+
+**Questions or Issues?**
+- [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues)
+- [Contribute improvements](https://github.com/cbcoutinho/nextcloud-mcp-server/pulls)

docs/testing-client-sessions-architecture.md

@@ -41,7 +41,7 @@ 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://127.0.0.1:8000/mcp", client_name="Basic MCP"
+            url="http://localhost:8000/mcp", client_name="Basic MCP"
         ):
             yield session
     except RuntimeError as e:
@@ -88,7 +88,7 @@ async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
 
     async def create_and_hold_session():
         """Runs in isolated task - creates session and keeps it alive."""
-        async with streamablehttp_client("http://127.0.0.1:8000/mcp") as (read_stream, write_stream, _):
+        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
@@ -141,7 +141,7 @@ async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
 @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://127.0.0.1:8000/mcp") as (read_stream, write_stream, _):
+    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
@@ -150,11 +150,11 @@ async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
 @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://127.0.0.1:8000/mcp") as (read1, write1, _):
+    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://127.0.0.1:8001/mcp") as (read2, write2, _):
+            async with streamablehttp_client("http://localhost:8001/mcp") as (read2, write2, _):
                 async with ClientSession(read2, write2) as session2:
                     await session2.initialize()
                     yield session1, session2
@@ -195,7 +195,7 @@ async def multi_mcp_clients() -> AsyncGenerator[tuple[ClientSession, ClientSessi
 # Fixtures work naturally with trio
 @pytest.fixture(scope="session")
 async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
-    async with streamablehttp_client("http://127.0.0.1:8000/mcp") as (read, write, _):
+    async with streamablehttp_client("http://localhost:8000/mcp") as (read, write, _):
         async with ClientSession(read, write) as session:
             await session.initialize()
             yield session

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

docs/troubleshooting.md

@@ -136,24 +136,27 @@ A patch for the `user_oidc` app is required to fix Bearer token support. See [oa
 
 ---
 
-### Issue: "Permission denied" when reading/writing OAuth client credentials file
+### Issue: "Permission denied" or "Database is locked" when accessing OAuth client storage
 
-**Cause:** The server cannot access the OAuth client storage file (default: `.nextcloud_oauth_client.json`).
+**Cause:** The server cannot access the SQLite database for OAuth client credentials storage.
 
 **Solution:**
 
 ```bash
-# Check file permissions
-ls -la .nextcloud_oauth_client.json
+# Check database directory permissions
+ls -la data/
 
-# Fix file permissions (should be 0600 - owner read/write only)
-chmod 600 .nextcloud_oauth_client.json
+# Ensure directory is writable
+chmod 755 data/
 
-# Ensure the directory is writable
-chmod 755 $(dirname .nextcloud_oauth_client.json)
+# Check if database file exists and has correct permissions
+ls -la data/tokens.db
+chmod 644 data/tokens.db
 
-# If the file doesn't exist, ensure the directory is writable so it can be created
-mkdir -p $(dirname .nextcloud_oauth_client.json)
+# For Docker deployments, ensure volume is mounted correctly:
+# docker-compose.yml should have:
+#   volumes:
+#     - ./data:/app/data
 ```
 
 ---

env.sample

@@ -8,12 +8,41 @@ NEXTCLOUD_HOST=
 # - Requires Nextcloud OIDC app installed and configured
 # - Admin must enable "Dynamic Client Registration" in OIDC app settings
 # - Leave NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD empty to use OAuth mode
+# - OAuth client credentials are stored encrypted in SQLite (TOKEN_STORAGE_DB)
 # - Optional: Pre-register client and provide credentials (otherwise auto-registers)
 NEXTCLOUD_OIDC_CLIENT_ID=
 NEXTCLOUD_OIDC_CLIENT_SECRET=
-NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
 NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
 
+# OAuth Storage Configuration (SQLite storage for OAuth clients and refresh tokens)
+# TOKEN_ENCRYPTION_KEY: Required for encrypting OAuth client secrets and refresh tokens
+# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+#TOKEN_ENCRYPTION_KEY=
+# TOKEN_STORAGE_DB: Path to SQLite database (default: /app/data/tokens.db)
+#TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# ===== ADR-004 PROGRESSIVE CONSENT CONFIGURATION =====
+# Enable Progressive Consent mode (dual OAuth flows)
+# When enabled: Flow 1 for client auth, Flow 2 for Nextcloud resource access
+# When disabled: Uses existing hybrid flow (backward compatible)
+
+# MCP Server OAuth Client Configuration
+# The MCP server's own OAuth client credentials for Flow 2
+# If not set, will use dynamic client registration
+#MCP_SERVER_CLIENT_ID=
+#MCP_SERVER_CLIENT_SECRET=
+
+# Allowed MCP Client IDs (comma-separated list)
+# Client IDs that are allowed to authenticate in Flow 1
+# Examples: claude-desktop,continue-dev,zed-editor
+#ALLOWED_MCP_CLIENTS=claude-desktop,continue-dev,zed-editor
+
+# Token cache configuration for Token Broker Service
+# Cache TTL in seconds (default: 300 = 5 minutes)
+#TOKEN_CACHE_TTL=300
+# Early refresh threshold in seconds (default: 30)
+#TOKEN_CACHE_EARLY_REFRESH=30
+
 # Option 2: Basic Authentication (LEGACY - Less Secure)
 # - Requires username and password
 # - Credentials stored in environment variables
@@ -21,3 +50,149 @@ 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
+
+# ============================================
+# Semantic Search & Vector Sync Configuration
+# ============================================
+# EXPERIMENTAL: Semantic search for Notes app (multi-app support planned)
+# Requires: Qdrant vector database + Ollama embedding service
+# Disabled by default
+
+# Enable background vector indexing
+VECTOR_SYNC_ENABLED=false
+
+# Document scan interval in seconds (default: 300 = 5 minutes)
+# How often to check for new/updated documents
+#VECTOR_SYNC_SCAN_INTERVAL=300
+
+# Concurrent indexing workers (default: 3)
+# Number of parallel workers for embedding generation
+#VECTOR_SYNC_PROCESSOR_WORKERS=3
+
+# Max queued documents (default: 10000)
+# Maximum documents waiting to be processed
+#VECTOR_SYNC_QUEUE_MAX_SIZE=10000
+
+# ============================================
+# Qdrant Vector Database Configuration
+# ============================================
+# Choose ONE of three modes:
+# 1. In-memory mode (default): Set neither QDRANT_URL nor QDRANT_LOCATION
+# 2. Persistent local: Set QDRANT_LOCATION=/path/to/data
+# 3. Network mode: Set QDRANT_URL=http://qdrant:6333
+
+# Network mode: URL to Qdrant service
+#QDRANT_URL=http://qdrant:6333
+
+# Local mode: Path to store vectors (use :memory: for in-memory)
+#QDRANT_LOCATION=:memory:
+
+# API key for network mode (optional)
+#QDRANT_API_KEY=
+
+# Collection name (optional - auto-generated if not set)
+# Auto-generation format: {deployment-id}-{model-name}
+# Allows safe model switching and multi-server deployments
+#QDRANT_COLLECTION=nextcloud_content
+
+# ============================================
+# Ollama Embedding Service Configuration
+# ============================================
+# Ollama endpoint for embeddings (if not set, uses SimpleEmbeddingProvider fallback)
+#OLLAMA_BASE_URL=http://ollama:11434
+
+# Embedding model to use (default: nomic-embed-text, 768 dimensions)
+# Changing this creates a new collection (requires re-embedding all documents)
+#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Verify SSL certificates (default: true)
+#OLLAMA_VERIFY_SSL=true
+
+# ============================================
+# Document Chunking Configuration
+# ============================================
+# Configure how documents are split before embedding
+
+# Words per chunk (default: 512)
+# Smaller chunks (256-384): More precise, less context, more storage
+# Larger chunks (768-1024): More context, less precise, less storage
+#DOCUMENT_CHUNK_SIZE=512
+
+# Overlapping words between chunks (default: 50)
+# Recommended: 10-20% of chunk size
+# Preserves context across chunk boundaries
+#DOCUMENT_CHUNK_OVERLAP=50

keycloak/realm-export.json

@@ -0,0 +1,852 @@
+{
+  "id": "nextcloud-mcp",
+  "realm": "nextcloud-mcp",
+  "notBefore": 0,
+  "defaultSignatureAlgorithm": "RS256",
+  "revokeRefreshToken": false,
+  "refreshTokenMaxReuse": 0,
+  "accessTokenLifespan": 300,
+  "accessTokenLifespanForImplicitFlow": 900,
+  "ssoSessionIdleTimeout": 1800,
+  "ssoSessionMaxLifespan": 36000,
+  "offlineSessionIdleTimeout": 2592000,
+  "offlineSessionMaxLifespanEnabled": false,
+  "offlineSessionMaxLifespan": 5184000,
+  "accessCodeLifespan": 60,
+  "accessCodeLifespanUserAction": 300,
+  "accessCodeLifespanLogin": 1800,
+  "enabled": true,
+  "sslRequired": "external",
+  "registrationAllowed": false,
+  "loginWithEmailAllowed": true,
+  "duplicateEmailsAllowed": false,
+  "resetPasswordAllowed": false,
+  "editUsernameAllowed": false,
+  "bruteForceProtected": false,
+  "attributes": {
+    "frontendUrl": "http://localhost:8888"
+  },
+  "roles": {
+    "realm": [
+      {
+        "name": "offline_access",
+        "description": "${role_offline-access}",
+        "composite": false,
+        "clientRole": false
+      },
+      {
+        "name": "uma_authorization",
+        "description": "${role_uma_authorization}",
+        "composite": false,
+        "clientRole": false
+      },
+      {
+        "name": "default-roles-nextcloud-mcp",
+        "description": "${role_default-roles}",
+        "composite": true,
+        "composites": {
+          "realm": [
+            "offline_access",
+            "uma_authorization"
+          ]
+        },
+        "clientRole": false
+      }
+    ]
+  },
+  "users": [
+    {
+      "username": "admin",
+      "enabled": true,
+      "email": "admin@example.com",
+      "emailVerified": true,
+      "firstName": "Admin",
+      "lastName": "User",
+      "credentials": [
+        {
+          "type": "password",
+          "value": "admin",
+          "temporary": false
+        }
+      ],
+      "realmRoles": [
+        "default-roles-nextcloud-mcp",
+        "offline_access"
+      ],
+      "attributes": {
+        "quota": [
+          "1073741824"
+        ]
+      }
+    },
+    {
+      "username": "test_read_only",
+      "enabled": true,
+      "email": "readonly@example.com",
+      "emailVerified": true,
+      "firstName": "Read",
+      "lastName": "Only",
+      "credentials": [
+        {
+          "type": "password",
+          "value": "test123",
+          "temporary": false
+        }
+      ],
+      "realmRoles": [
+        "default-roles-nextcloud-mcp",
+        "offline_access"
+      ],
+      "attributes": {
+        "quota": [
+          "1073741824"
+        ]
+      }
+    },
+    {
+      "username": "test_write_only",
+      "enabled": true,
+      "email": "writeonly@example.com",
+      "emailVerified": true,
+      "firstName": "Write",
+      "lastName": "Only",
+      "credentials": [
+        {
+          "type": "password",
+          "value": "test123",
+          "temporary": false
+        }
+      ],
+      "realmRoles": [
+        "default-roles-nextcloud-mcp",
+        "offline_access"
+      ],
+      "attributes": {
+        "quota": [
+          "1073741824"
+        ]
+      }
+    },
+    {
+      "username": "test_no_scopes",
+      "enabled": true,
+      "email": "noscopes@example.com",
+      "emailVerified": true,
+      "firstName": "No",
+      "lastName": "Scopes",
+      "credentials": [
+        {
+          "type": "password",
+          "value": "test123",
+          "temporary": false
+        }
+      ],
+      "realmRoles": [
+        "default-roles-nextcloud-mcp",
+        "offline_access"
+      ],
+      "attributes": {
+        "quota": [
+          "1073741824"
+        ]
+      }
+    },
+    {
+      "username": "service-account-nextcloud-mcp-server",
+      "enabled": true,
+      "serviceAccountClientId": "nextcloud-mcp-server",
+      "clientRoles": {
+        "realm-management": [
+          "impersonation"
+        ]
+      }
+    }
+  ],
+  "clients": [
+    {
+      "clientId": "nextcloud",
+      "name": "Nextcloud Resource Server",
+      "description": "Resource server for Nextcloud APIs - used by user_oidc app for bearer token validation and as token exchange target",
+      "enabled": true,
+      "clientAuthenticatorType": "client-secret",
+      "secret": "nextcloud-secret-change-in-production",
+      "redirectUris": [],
+      "webOrigins": [],
+      "bearerOnly": false,
+      "consentRequired": false,
+      "standardFlowEnabled": false,
+      "implicitFlowEnabled": false,
+      "directAccessGrantsEnabled": false,
+      "serviceAccountsEnabled": true,
+      "authorizationServicesEnabled": true,
+      "publicClient": false,
+      "protocol": "openid-connect",
+      "attributes": {
+        "display.on.consent.screen": "false",
+        "token.exchange.grant.enabled": "true",
+        "client.token.exchange.standard.enabled": "true",
+        "standard.token.exchange.enabled": "true"
+      },
+      "authorizationSettings": {
+        "allowRemoteResourceManagement": true,
+        "policyEnforcementMode": "ENFORCING",
+        "resources": [
+          {
+            "name": "token-exchange",
+            "type": "urn:keycloak:token-exchange",
+            "ownerManagedAccess": false,
+            "displayName": "Token Exchange",
+            "attributes": {},
+            "uris": [],
+            "scopes": [
+              {
+                "name": "token-exchange"
+              }
+            ]
+          }
+        ],
+        "policies": [
+          {
+            "name": "allow-nextcloud-mcp-server-to-exchange",
+            "description": "",
+            "type": "client",
+            "logic": "POSITIVE",
+            "decisionStrategy": "UNANIMOUS",
+            "config": {
+              "clients": "[\"nextcloud-mcp-server\",\"nextcloud\"]"
+            }
+          },
+          {
+            "name": "token-exchange-permission",
+            "description": "",
+            "type": "scope",
+            "logic": "POSITIVE",
+            "decisionStrategy": "AFFIRMATIVE",
+            "config": {
+              "resources": "[\"token-exchange\"]",
+              "scopes": "[\"token-exchange\"]",
+              "applyPolicies": "[\"allow-nextcloud-mcp-server-to-exchange\"]"
+            }
+          }
+        ],
+        "scopes": [
+          {
+            "name": "token-exchange",
+            "displayName": "Token Exchange"
+          }
+        ],
+        "decisionStrategy": "UNANIMOUS"
+      },
+      "fullScopeAllowed": true,
+      "nodeReRegistrationTimeout": -1
+    },
+    {
+      "clientId": "nextcloud-mcp-server",
+      "name": "Nextcloud MCP Server",
+      "enabled": true,
+      "clientAuthenticatorType": "client-secret",
+      "secret": "mcp-secret-change-in-production",
+      "redirectUris": [
+        "http://localhost:*",
+        "http://127.0.0.1:*",
+        "http://localhost:*/callback",
+        "http://127.0.0.1:*/callback"
+      ],
+      "webOrigins": [
+        "+"
+      ],
+      "bearerOnly": false,
+      "consentRequired": false,
+      "standardFlowEnabled": true,
+      "implicitFlowEnabled": false,
+      "directAccessGrantsEnabled": true,
+      "serviceAccountsEnabled": true,
+      "publicClient": false,
+      "frontchannelLogout": false,
+      "protocol": "openid-connect",
+      "attributes": {
+        "pkce.code.challenge.method": "S256",
+        "use.refresh.tokens": "true",
+        "backchannel.logout.session.required": "true",
+        "backchannel.logout.url": "http://app:80/index.php/apps/user_oidc/backchannel-logout/keycloak",
+        "oauth2.device.authorization.grant.enabled": "false",
+        "oidc.ciba.grant.enabled": "false",
+        "client_credentials.use_refresh_token": "false",
+        "display.on.consent.screen": "false",
+        "token.exchange.grant.enabled": "true",
+        "client.token.exchange.standard.enabled": "true",
+        "standard.token.exchange.enabled": "true"
+      },
+      "fullScopeAllowed": true,
+      "nodeReRegistrationTimeout": -1,
+      "protocolMappers": [
+        {
+          "name": "mcp-server-audience",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-audience-mapper",
+          "consentRequired": false,
+          "config": {
+            "included.client.audience": "nextcloud-mcp-server",
+            "access.token.claim": "true",
+            "id.token.claim": "false",
+            "introspection.token.claim": "true"
+          }
+        },
+        {
+          "name": "nextcloud-audience",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-audience-mapper",
+          "consentRequired": false,
+          "config": {
+            "included.client.audience": "nextcloud",
+            "access.token.claim": "true",
+            "id.token.claim": "false",
+            "introspection.token.claim": "true"
+          }
+        },
+        {
+          "name": "sub",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-property-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "true",
+            "user.attribute": "username",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "sub",
+            "jsonType.label": "String"
+          }
+        },
+        {
+          "name": "full name",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-full-name-mapper",
+          "consentRequired": false,
+          "config": {
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        },
+        {
+          "name": "email",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-property-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "true",
+            "user.attribute": "email",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "email",
+            "jsonType.label": "String"
+          }
+        },
+        {
+          "name": "preferred_username",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-property-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "true",
+            "user.attribute": "username",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "preferred_username",
+            "jsonType.label": "String"
+          }
+        },
+        {
+          "name": "quota",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-attribute-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "true",
+            "user.attribute": "quota",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "quota",
+            "jsonType.label": "String"
+          }
+        }
+      ],
+      "defaultClientScopes": [
+        "web-origins",
+        "profile",
+        "roles",
+        "email"
+      ],
+      "optionalClientScopes": [
+        "address",
+        "phone",
+        "offline_access",
+        "microprofile-jwt",
+        "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"
+      ]
+    }
+  ],
+  "clientScopes": [
+    {
+      "name": "offline_access",
+      "description": "OpenID Connect built-in scope: offline_access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "consent.screen.text": "${offlineAccessScopeConsentText}",
+        "display.on.consent.screen": "true"
+      }
+    },
+    {
+      "name": "profile",
+      "description": "OpenID Connect built-in scope: profile",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true"
+      },
+      "protocolMappers": [
+        {
+          "name": "full name",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-full-name-mapper",
+          "consentRequired": false,
+          "config": {
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        },
+        {
+          "name": "username",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-property-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "true",
+            "user.attribute": "username",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "preferred_username",
+            "jsonType.label": "String"
+          }
+        },
+        {
+          "name": "given name",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-property-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "true",
+            "user.attribute": "firstName",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "given_name",
+            "jsonType.label": "String"
+          }
+        },
+        {
+          "name": "family name",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-property-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "true",
+            "user.attribute": "lastName",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "family_name",
+            "jsonType.label": "String"
+          }
+        }
+      ]
+    },
+    {
+      "name": "email",
+      "description": "OpenID Connect built-in scope: email",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true"
+      },
+      "protocolMappers": [
+        {
+          "name": "email",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-property-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "true",
+            "user.attribute": "email",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "email",
+            "jsonType.label": "String"
+          }
+        },
+        {
+          "name": "email verified",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-property-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "true",
+            "user.attribute": "emailVerified",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "email_verified",
+            "jsonType.label": "boolean"
+          }
+        }
+      ]
+    },
+    {
+      "name": "roles",
+      "description": "OpenID Connect scope for add user roles to the access token",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "false",
+        "display.on.consent.screen": "true"
+      },
+      "protocolMappers": [
+        {
+          "name": "realm roles",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-realm-role-mapper",
+          "consentRequired": false,
+          "config": {
+            "user.attribute": "foo",
+            "access.token.claim": "true",
+            "claim.name": "realm_access.roles",
+            "jsonType.label": "String",
+            "multivalued": "true"
+          }
+        },
+        {
+          "name": "client roles",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-client-role-mapper",
+          "consentRequired": false,
+          "config": {
+            "user.attribute": "foo",
+            "access.token.claim": "true",
+            "claim.name": "resource_access.${client_id}.roles",
+            "jsonType.label": "String",
+            "multivalued": "true"
+          }
+        }
+      ]
+    },
+    {
+      "name": "web-origins",
+      "description": "OpenID Connect scope for add allowed web origins to the access token",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "false",
+        "display.on.consent.screen": "false"
+      },
+      "protocolMappers": [
+        {
+          "name": "allowed web origins",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-allowed-origins-mapper",
+          "consentRequired": false,
+          "config": {}
+        }
+      ]
+    },
+    {
+      "name": "notes:read",
+      "description": "Nextcloud Notes read access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Read your notes"
+      }
+    },
+    {
+      "name": "notes:write",
+      "description": "Nextcloud Notes write access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Create, update, and delete your notes"
+      }
+    },
+    {
+      "name": "calendar:read",
+      "description": "Nextcloud Calendar read access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Read your calendars and events"
+      }
+    },
+    {
+      "name": "calendar:write",
+      "description": "Nextcloud Calendar write access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Create, update, and delete calendars and events"
+      }
+    },
+    {
+      "name": "contacts:read",
+      "description": "Nextcloud Contacts read access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Read your contacts"
+      }
+    },
+    {
+      "name": "contacts:write",
+      "description": "Nextcloud Contacts write access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Create, update, and delete contacts"
+      }
+    },
+    {
+      "name": "cookbook:read",
+      "description": "Nextcloud Cookbook read access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Read your recipes"
+      }
+    },
+    {
+      "name": "cookbook:write",
+      "description": "Nextcloud Cookbook write access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Create, update, and delete recipes"
+      }
+    },
+    {
+      "name": "deck:read",
+      "description": "Nextcloud Deck read access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Read your boards and cards"
+      }
+    },
+    {
+      "name": "deck:write",
+      "description": "Nextcloud Deck write access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Create, update, and delete boards and cards"
+      }
+    },
+    {
+      "name": "tables:read",
+      "description": "Nextcloud Tables read access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Read your tables and rows"
+      }
+    },
+    {
+      "name": "tables:write",
+      "description": "Nextcloud Tables write access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Create, update, and delete tables and rows"
+      }
+    },
+    {
+      "name": "files:read",
+      "description": "Nextcloud Files read access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Read your files"
+      }
+    },
+    {
+      "name": "files:write",
+      "description": "Nextcloud Files write access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Upload, update, and delete files"
+      }
+    },
+    {
+      "name": "sharing:read",
+      "description": "Nextcloud Sharing read access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "View shared resources"
+      }
+    },
+    {
+      "name": "sharing:write",
+      "description": "Nextcloud Sharing write access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Create and manage shares"
+      }
+    },
+    {
+      "name": "todo:read",
+      "description": "Nextcloud Tasks/Todo read access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Read your tasks"
+      }
+    },
+    {
+      "name": "todo:write",
+      "description": "Nextcloud Tasks/Todo write access",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "true",
+        "display.on.consent.screen": "true",
+        "consent.screen.text": "Create, update, and delete tasks"
+      }
+    },
+    {
+      "name": "default-audience",
+      "protocol": "openid-connect",
+      "attributes": {
+        "include.in.token.scope": "false",
+        "display.on.consent.screen": "false",
+        "gui.order": "",
+        "consent.screen.text": ""
+      },
+      "protocolMappers": [
+        {
+          "name": "mcp-server-audience",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-audience-mapper",
+          "consentRequired": false,
+          "config": {
+            "included.client.audience": "nextcloud-mcp-server",
+            "access.token.claim": "true",
+            "id.token.claim": "false"
+          }
+        },
+        {
+          "name": "mcp-url-audience",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-audience-mapper",
+          "consentRequired": false,
+          "config": {
+            "included.custom.audience": "http://localhost:8002",
+            "access.token.claim": "true",
+            "id.token.claim": "false"
+          }
+        }
+      ]
+    }
+  ],
+  "components": {
+    "org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy": [
+      {
+        "name": "Trusted Hosts",
+        "providerId": "trusted-hosts",
+        "subType": "anonymous",
+        "subComponents": {},
+        "config": {
+          "trusted-hosts": [
+            "localhost",
+            "127.0.0.1",
+            "172.19.0.1"
+          ],
+          "host-sending-registration-request-must-match": [
+            "false"
+          ],
+          "client-uris-must-match": [
+            "true"
+          ]
+        }
+      },
+      {
+        "name": "Max Clients",
+        "providerId": "max-clients",
+        "subType": "anonymous",
+        "subComponents": {},
+        "config": {
+          "max-clients": [
+            "200"
+          ]
+        }
+      }
+    ]
+  },
+  "defaultDefaultClientScopes": [
+    "profile",
+    "email",
+    "roles",
+    "web-origins",
+    "default-audience"
+  ],
+  "defaultOptionalClientScopes": [
+    "offline_access",
+    "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"
+  ]
+}

nextcloud_mcp_server/auth/__init__.py

@@ -1,14 +1,34 @@
 """OAuth authentication components for Nextcloud MCP server."""
 
 from .bearer_auth import BearerAuth
-from .client_registration import load_or_register_client, register_client
+from .client_registration import ensure_oauth_client, register_client
 from .context_helper import get_client_from_context
-from .token_verifier import NextcloudTokenVerifier
+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 .unified_verifier import UnifiedTokenVerifier
 
 __all__ = [
     "BearerAuth",
-    "NextcloudTokenVerifier",
+    "UnifiedTokenVerifier",
     "register_client",
-    "load_or_register_client",
+    "ensure_oauth_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/browser_oauth_routes.py

@@ -0,0 +1,420 @@
+"""Browser-based OAuth login routes for admin UI.
+
+Separate from MCP OAuth flow - these routes establish browser sessions
+for accessing admin UI endpoints like /app.
+"""
+
+import hashlib
+import logging
+import os
+import secrets
+from base64 import urlsafe_b64encode
+from urllib.parse import urlencode
+
+import httpx
+import jwt
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, JSONResponse, RedirectResponse
+
+from nextcloud_mcp_server.auth.userinfo_routes import (
+    _get_userinfo_endpoint,
+    _query_idp_userinfo,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
+    """Browser OAuth login endpoint - redirects to IdP for authentication.
+
+    This is separate from the MCP OAuth flow (/oauth/authorize).
+    Creates a browser session with refresh token for admin UI access.
+
+    Query parameters:
+        next: Optional URL to redirect to after login (default: /user/page)
+
+    Returns:
+        302 redirect to IdP authorization endpoint
+    """
+    oauth_ctx = request.app.state.oauth_context
+    if not oauth_ctx:
+        # BasicAuth mode - no login needed, redirect to app
+        return RedirectResponse("/app", status_code=302)
+
+    storage = oauth_ctx["storage"]
+    oauth_client = oauth_ctx["oauth_client"]
+    oauth_config = oauth_ctx["config"]
+
+    # Debug: Log oauth_config contents
+    logger.info(f"oauth_login called - oauth_config keys: {oauth_config.keys()}")
+    logger.info(f"oauth_login called - client_id: {oauth_config.get('client_id')}")
+    logger.info(f"oauth_login called - oauth_client: {oauth_client is not None}")
+
+    # Generate state for CSRF protection
+    state = secrets.token_urlsafe(32)
+
+    # Build OAuth authorization URL
+    mcp_server_url = oauth_config["mcp_server_url"]
+    callback_uri = f"{mcp_server_url}/oauth/callback"
+
+    # Request only basic OIDC scopes for browser session
+    # Note: Nextcloud app scopes (notes:read, etc.) are for MCP client access tokens,
+    # not for the MCP server's own browser authentication
+    scopes = "openid profile email offline_access"
+
+    # Generate PKCE values for ALL modes (both external and integrated IdP require PKCE)
+    code_verifier = secrets.token_urlsafe(32)
+    digest = hashlib.sha256(code_verifier.encode()).digest()
+    code_challenge = urlsafe_b64encode(digest).decode().rstrip("=")
+
+    # Store code_verifier in session for retrieval during callback (using state as key)
+    await storage.store_oauth_session(
+        session_id=state,  # Use state as session ID
+        client_id="browser-ui",
+        client_redirect_uri="/app",
+        state=state,
+        code_challenge=code_challenge,
+        code_challenge_method="S256",
+        mcp_authorization_code=code_verifier,  # Store code_verifier here temporarily
+        flow_type="browser",
+        ttl_seconds=600,  # 10 minutes
+    )
+
+    if oauth_client:
+        # External IdP mode (Keycloak)
+        if not oauth_client.authorization_endpoint:
+            await oauth_client.discover()
+
+        idp_params = {
+            "client_id": oauth_client.client_id,
+            "redirect_uri": callback_uri,
+            "response_type": "code",
+            "scope": scopes,
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "prompt": "consent",  # Ensure refresh token
+        }
+
+        auth_url = f"{oauth_client.authorization_endpoint}?{urlencode(idp_params)}"
+        logger.info(f"Redirecting to external IdP login: {auth_url.split('?')[0]}")
+    else:
+        # Integrated mode (Nextcloud OIDC)
+        discovery_url = oauth_config.get("discovery_url")
+        if not discovery_url:
+            return JSONResponse(
+                {
+                    "error": "server_error",
+                    "error_description": "OAuth discovery URL not configured",
+                },
+                status_code=500,
+            )
+
+        # Fetch authorization endpoint
+        async with httpx.AsyncClient() as http_client:
+            response = await http_client.get(discovery_url)
+            response.raise_for_status()
+            discovery = response.json()
+            authorization_endpoint = discovery["authorization_endpoint"]
+
+        # Replace internal Docker hostname with public URL
+        public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+        if public_issuer:
+            from urllib.parse import urlparse as parse_url
+
+            internal_parsed = parse_url(oauth_config["nextcloud_host"])
+            auth_parsed = parse_url(authorization_endpoint)
+
+            if auth_parsed.hostname == internal_parsed.hostname:
+                public_parsed = parse_url(public_issuer)
+                authorization_endpoint = (
+                    f"{public_parsed.scheme}://{public_parsed.netloc}{auth_parsed.path}"
+                )
+
+        idp_params = {
+            "client_id": oauth_config["client_id"],
+            "redirect_uri": callback_uri,
+            "response_type": "code",
+            "scope": scopes,
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "prompt": "consent",  # Ensure refresh token
+        }
+
+        # Debug: Log full parameters
+        logger.info(f"Building Nextcloud OIDC auth URL with params: {idp_params}")
+
+        auth_url = f"{authorization_endpoint}?{urlencode(idp_params)}"
+        logger.info(f"Redirecting to Nextcloud OIDC login: {auth_url}")
+
+    return RedirectResponse(auth_url, status_code=302)
+
+
+async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLResponse:
+    """Browser OAuth callback - IdP redirects here after authentication.
+
+    Exchanges authorization code for tokens, stores refresh token,
+    sets session cookie, and redirects to original destination.
+
+    Query parameters:
+        code: Authorization code from IdP
+        state: State parameter
+        error: Error code (if authorization failed)
+
+    Returns:
+        302 redirect to next URL with session cookie
+    """
+    # Check for errors
+    error = request.query_params.get("error")
+    if error:
+        error_description = request.query_params.get(
+            "error_description", "Authorization failed"
+        )
+        logger.error(f"OAuth login error: {error} - {error_description}")
+        login_url = str(request.url_for("oauth_login"))
+        return HTMLResponse(
+            f"""
+            <!DOCTYPE html>
+            <html>
+            <head><title>Login Failed</title></head>
+            <body>
+                <h1>Login Failed</h1>
+                <p>Error: {error}</p>
+                <p>{error_description}</p>
+                <p><a href="{login_url}">Try again</a></p>
+            </body>
+            </html>
+            """,
+            status_code=400,
+        )
+
+    # Extract code and state
+    code = request.query_params.get("code")
+    state = request.query_params.get("state")
+
+    if not code or not state:
+        return HTMLResponse(
+            """
+            <!DOCTYPE html>
+            <html>
+            <head><title>Invalid Request</title></head>
+            <body>
+                <h1>Invalid Request</h1>
+                <p>Missing code or state parameter</p>
+            </body>
+            </html>
+            """,
+            status_code=400,
+        )
+
+    # Get OAuth context
+    oauth_ctx = request.app.state.oauth_context
+    storage = oauth_ctx["storage"]
+    oauth_client = oauth_ctx["oauth_client"]
+    oauth_config = oauth_ctx["config"]
+
+    # Retrieve code_verifier from session storage (PKCE required for all modes)
+    code_verifier = ""
+    oauth_session = await storage.get_oauth_session(state)
+    if oauth_session:
+        # code_verifier was stored in mcp_authorization_code field
+        code_verifier = oauth_session.get("mcp_authorization_code", "")
+        # Clean up the temporary session
+        # Note: We don't have delete_oauth_session method, but it will expire after TTL
+
+    # Exchange authorization code for tokens
+    mcp_server_url = oauth_config["mcp_server_url"]
+    callback_uri = f"{mcp_server_url}/oauth/callback"
+
+    try:
+        if oauth_client:
+            # External IdP mode (Keycloak)
+            # Use PKCE if we have a code_verifier
+            if not oauth_client.token_endpoint:
+                await oauth_client.discover()
+
+            token_params = {
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": callback_uri,
+                "client_id": oauth_client.client_id,
+                "client_secret": oauth_client.client_secret,
+            }
+
+            # Add code_verifier if we have one (PKCE)
+            if code_verifier:
+                token_params["code_verifier"] = code_verifier
+
+            async with httpx.AsyncClient() as http_client:
+                response = await http_client.post(
+                    oauth_client.token_endpoint,
+                    data=token_params,
+                )
+                response.raise_for_status()
+                token_data = response.json()
+        else:
+            # Integrated mode (Nextcloud OIDC)
+            discovery_url = oauth_config.get("discovery_url")
+            async with httpx.AsyncClient() as http_client:
+                response = await http_client.get(discovery_url)
+                response.raise_for_status()
+                discovery = response.json()
+                token_endpoint = discovery["token_endpoint"]
+
+            token_params = {
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": callback_uri,
+                "client_id": oauth_config["client_id"],
+                "client_secret": oauth_config["client_secret"],
+            }
+
+            # Add code_verifier for PKCE (required by Nextcloud OIDC)
+            if code_verifier:
+                token_params["code_verifier"] = code_verifier
+
+            async with httpx.AsyncClient() as http_client:
+                response = await http_client.post(
+                    token_endpoint,
+                    data=token_params,
+                )
+                response.raise_for_status()
+                token_data = response.json()
+
+    except httpx.HTTPStatusError as e:
+        error_body = (
+            e.response.text if hasattr(e.response, "text") else str(e.response.content)
+        )
+        logger.error(
+            f"Token exchange failed: HTTP {e.response.status_code} - {error_body}"
+        )
+        return HTMLResponse(
+            f"""
+            <!DOCTYPE html>
+            <html>
+            <head><title>Login Failed</title></head>
+            <body>
+                <h1>Login Failed</h1>
+                <p>Failed to exchange authorization code for tokens</p>
+                <p>HTTP {e.response.status_code}: {error_body}</p>
+            </body>
+            </html>
+            """,
+            status_code=500,
+        )
+    except Exception as e:
+        logger.error(f"Token exchange failed: {e}")
+        return HTMLResponse(
+            f"""
+            <!DOCTYPE html>
+            <html>
+            <head><title>Login Failed</title></head>
+            <body>
+                <h1>Login Failed</h1>
+                <p>Failed to exchange authorization code for tokens</p>
+                <p>Error: {e}</p>
+            </body>
+            </html>
+            """,
+            status_code=500,
+        )
+
+    refresh_token = token_data.get("refresh_token")
+    id_token = token_data.get("id_token")
+
+    logger.info(f"Token exchange response keys: {token_data.keys()}")
+    logger.info(f"Refresh token present: {refresh_token is not None}")
+    logger.info(f"ID token present: {id_token is not None}")
+
+    # Decode ID token to get user info
+    try:
+        userinfo = jwt.decode(id_token, options={"verify_signature": False})
+        user_id = userinfo.get("sub")
+        username = userinfo.get("preferred_username") or userinfo.get("email")
+        logger.info(f"Browser login successful: {username} (sub={user_id})")
+    except Exception as e:
+        logger.warning(f"Failed to decode ID token: {e}")
+        user_id = f"user-{secrets.token_hex(8)}"
+        username = "unknown"
+
+    # Store refresh token (for background jobs ONLY)
+    if refresh_token:
+        logger.info(f"Storing refresh token for user_id: {user_id}")
+        logger.info(f"  State parameter (provisioning_client_id): {state[:16]}...")
+        await storage.store_refresh_token(
+            user_id=user_id,
+            refresh_token=refresh_token,
+            expires_at=None,
+            flow_type="browser",  # Browser-based login flow
+            provisioning_client_id=state,  # Store state for unified session lookup
+        )
+        logger.info(f"✓ Refresh token stored successfully for user_id: {user_id}")
+        logger.info(
+            f"  Token can now be found via provisioning_client_id={state[:16]}..."
+        )
+    else:
+        logger.warning("No refresh token in token response - cannot store session")
+
+    # Query and cache user profile (for browser UI display)
+    access_token = token_data.get("access_token")
+    if access_token:
+        try:
+            # Get the OAuth context to determine correct userinfo endpoint
+            oauth_ctx = getattr(request.app.state, "oauth_context", {})
+            userinfo_endpoint = await _get_userinfo_endpoint(oauth_ctx)
+
+            if userinfo_endpoint:
+                # Query userinfo endpoint with fresh access token
+                profile_data = await _query_idp_userinfo(
+                    access_token, userinfo_endpoint
+                )
+
+                if profile_data:
+                    # Cache profile for browser UI (no token needed to display)
+                    await storage.store_user_profile(user_id, profile_data)
+                    logger.info(f"✓ User profile cached for {user_id}")
+                else:
+                    logger.warning(f"Failed to query userinfo endpoint for {user_id}")
+            else:
+                logger.warning("Could not determine userinfo endpoint")
+        except Exception as e:
+            logger.error(f"Error caching user profile: {e}")
+            # Continue anyway - profile cache is optional for browser UI
+
+    # Create response and set session cookie
+    response = RedirectResponse("/app", status_code=302)
+    response.set_cookie(
+        key="mcp_session",
+        value=user_id,
+        max_age=86400 * 30,  # 30 days
+        httponly=True,
+        secure=False,  # Set to True in production with HTTPS
+        samesite="lax",
+    )
+
+    logger.info(f"Session cookie set for user: {username}")
+    return response
+
+
+async def oauth_logout(request: Request) -> RedirectResponse:
+    """Browser OAuth logout - clears session cookie.
+
+    Query parameters:
+        next: Optional URL to redirect to after logout (default: /oauth/login)
+
+    Returns:
+        302 redirect with cleared session cookie
+    """
+    next_url = request.query_params.get("next", "/oauth/login")
+
+    # TODO: Optionally revoke refresh token from storage
+    # session_id = request.cookies.get("mcp_session")
+    # if session_id:
+    #     await storage.delete_refresh_token(session_id)
+
+    response = RedirectResponse(next_url, status_code=302)
+    response.delete_cookie("mcp_session")
+
+    logger.info("User logged out, session cookie cleared")
+    return response

nextcloud_mcp_server/auth/client_registration.py

@@ -1,19 +1,20 @@
 """Dynamic client registration for Nextcloud OIDC."""
 
-import json
+import datetime as dt
 import logging
-import os
 import time
-from pathlib import Path
 from typing import Any
 
+import anyio
 import httpx
 
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
 logger = logging.getLogger(__name__)
 
 
 class ClientInfo:
-    """Client registration information."""
+    """Client registration information with RFC 7592 support."""
 
     def __init__(
         self,
@@ -22,12 +23,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 +46,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 +68,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,16 +79,23 @@ async def register_client(
     client_name: str = "Nextcloud MCP Server",
     redirect_uris: list[str] | None = None,
     scopes: str = "openid profile email",
+    token_type: str | None = "Bearer",
+    resource_url: str | None = None,
 ) -> ClientInfo:
     """
-    Register a new OAuth client with Nextcloud OIDC using dynamic client registration.
+    Register a new OAuth client using RFC 7591 Dynamic Client Registration.
+
+    This function supports both Nextcloud OIDC and standard OIDC providers like Keycloak.
 
     Args:
-        nextcloud_url: Base URL of the Nextcloud instance
+        nextcloud_url: Base URL of the OIDC provider
         registration_endpoint: Full URL to the registration endpoint
         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 (default: "Bearer", supports "JWT" for Nextcloud).
+                    Set to None to omit this field (required for Keycloak and other standard providers).
+        resource_url: OAuth 2.0 Protected Resource URL (RFC 9728) - used for token introspection authorization
 
     Returns:
         ClientInfo with registration details
@@ -84,6 +103,11 @@ async def register_client(
     Raises:
         httpx.HTTPStatusError: If registration fails
         ValueError: If response is invalid
+
+    Note:
+        The token_type parameter is a Nextcloud-specific extension and is not part of RFC 7591.
+        Standard OIDC providers like Keycloak do not accept this field and will return a 400 error
+        if it's included. Set token_type=None when registering with Keycloak or other standard providers.
     """
     if redirect_uris is None:
         redirect_uris = ["http://localhost:8000/oauth/callback"]
@@ -97,6 +121,14 @@ async def register_client(
         "scope": scopes,
     }
 
+    # Add token_type if provided (Nextcloud-specific, not RFC 7591 standard)
+    if token_type is not None:
+        client_metadata["token_type"] = token_type
+
+    # Add resource_url if provided (RFC 9728)
+    if resource_url:
+        client_metadata["resource_url"] = resource_url
+
     logger.info(f"Registering OAuth client with Nextcloud: {client_name}")
     logger.debug(f"Registration endpoint: {registration_endpoint}")
 
@@ -113,11 +145,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 +173,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:
@@ -139,94 +186,160 @@ async def register_client(
             raise ValueError(f"Invalid registration response: missing {e}")
 
 
-def load_client_from_file(storage_path: Path) -> ClientInfo | None:
+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:
     """
-    Load client credentials from storage file.
+    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:
-        storage_path: Path to the JSON file containing client credentials
+        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:
-        ClientInfo if file exists and is valid, None otherwise
+        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)
     """
-    if not storage_path.exists():
-        logger.debug(f"Client storage file not found: {storage_path}")
-        return None
 
-    try:
-        with open(storage_path, "r") as f:
-            data = json.load(f)
+    # Determine deletion endpoint
+    if registration_client_uri:
+        deletion_endpoint = registration_client_uri
+    else:
+        deletion_endpoint = f"{nextcloud_url}/apps/oidc/register/{client_id}"
 
-        client_info = ClientInfo.from_dict(data)
+    logger.info(f"Deleting OAuth client: {client_id[:16]}...")
+    logger.debug(f"Deletion endpoint: {deletion_endpoint}")
 
-        if client_info.is_expired:
-            logger.warning(
-                f"Stored client has expired (expired at {client_info.client_secret_expires_at})"
-            )
-            return None
+    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
 
-        logger.info(f"Loaded client from storage: {client_info.client_id[:16]}...")
-        if client_info.expires_soon:
-            logger.warning("Client expires soon (within 5 minutes)")
+                # 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
 
-        return client_info
+            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
 
-    except (json.JSONDecodeError, KeyError, ValueError) as e:
-        logger.error(f"Failed to load client from file: {e}")
-        return None
+        # Should not reach here, but return False if we do
+        return False
 
 
-def save_client_to_file(client_info: ClientInfo, storage_path: Path):
-    """
-    Save client credentials to storage file.
-
-    Args:
-        client_info: Client information to save
-        storage_path: Path to save the JSON file
-
-    Raises:
-        OSError: If file cannot be written
-    """
-    try:
-        # Create directory if it doesn't exist
-        storage_path.parent.mkdir(parents=True, exist_ok=True)
-
-        # Write client info
-        with open(storage_path, "w") as f:
-            json.dump(client_info.to_dict(), f, indent=2)
-
-        # Set restrictive permissions (owner read/write only)
-        os.chmod(storage_path, 0o600)
-
-        logger.info(f"Saved client credentials to {storage_path}")
-
-    except OSError as e:
-        logger.error(f"Failed to save client credentials: {e}")
-        raise
-
-
-async def load_or_register_client(
+async def ensure_oauth_client(
     nextcloud_url: str,
     registration_endpoint: str,
-    storage_path: str | Path,
+    storage: RefreshTokenStorage,
     client_name: str = "Nextcloud MCP Server",
     redirect_uris: list[str] | None = None,
+    scopes: str = "openid profile email",
+    token_type: str = "Bearer",
+    resource_url: str | None = None,
 ) -> ClientInfo:
     """
-    Load client from storage or register a new one if not found/expired.
+    Ensure OAuth client exists in SQLite storage.
 
     This function:
-    1. Checks for existing client credentials in storage
+    1. Checks for existing client credentials in SQLite storage
     2. Validates the credentials are not expired
     3. Registers a new client if needed (no stored credentials or expired)
-    4. Saves the new client credentials
+    4. Saves the new client credentials to SQLite
 
     Args:
         nextcloud_url: Base URL of the Nextcloud instance
         registration_endpoint: Full URL to the registration endpoint
-        storage_path: Path to store client credentials
+        storage: RefreshTokenStorage instance for SQLite storage
         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")
+        resource_url: OAuth 2.0 Protected Resource URL (RFC 9728) - used for token introspection authorization
 
     Returns:
         ClientInfo with valid credentials
@@ -235,23 +348,37 @@ async def load_or_register_client(
         httpx.HTTPStatusError: If registration fails
         ValueError: If response is invalid
     """
-    storage_path = Path(storage_path)
-
-    # Try to load existing client
-    client_info = load_client_from_file(storage_path)
-    if client_info:
-        return client_info
+    # Try to load existing client from SQLite
+    client_data = await storage.get_oauth_client()
+    if client_data:
+        logger.info(
+            f"Loaded OAuth client from SQLite: {client_data['client_id'][:16]}..."
+        )
+        return ClientInfo.from_dict(client_data)
 
     # Register new client
     logger.info("Registering new OAuth client...")
+    if resource_url:
+        logger.info(f"  with resource_url: {resource_url}")
     client_info = await register_client(
         nextcloud_url=nextcloud_url,
         registration_endpoint=registration_endpoint,
         client_name=client_name,
         redirect_uris=redirect_uris,
+        scopes=scopes,
+        token_type=token_type,
+        resource_url=resource_url,
     )
 
-    # Save to storage
-    save_client_to_file(client_info, storage_path)
+    # Save to SQLite storage
+    await storage.store_oauth_client(
+        client_id=client_info.client_id,
+        client_secret=client_info.client_secret,
+        client_id_issued_at=client_info.client_id_issued_at,
+        client_secret_expires_at=client_info.client_secret_expires_at,
+        redirect_uris=client_info.redirect_uris,
+        registration_access_token=client_info.registration_access_token,
+        registration_client_uri=client_info.registration_client_uri,
+    )
 
     return client_info

nextcloud_mcp_server/auth/client_registry.py

@@ -0,0 +1,239 @@
+"""
+MCP Client Registry for ADR-004 Progressive Consent Architecture.
+
+This module manages the registry of allowed MCP clients that can authenticate
+via Flow 1. In production, this would integrate with Dynamic Client Registration
+(DCR) or a database of pre-registered clients.
+"""
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MCPClientInfo:
+    """Information about a registered MCP client."""
+
+    client_id: str
+    name: str
+    redirect_uris: List[str]
+    allowed_scopes: List[str]
+    is_public: bool = True  # Native clients are public (no client_secret)
+    metadata: Optional[Dict] = None
+
+
+class ClientRegistry:
+    """
+    Registry for MCP clients allowed to authenticate via Flow 1.
+
+    In production, this would:
+    1. Support Dynamic Client Registration (DCR) per RFC 7591
+    2. Integrate with IdP client registry
+    3. Store client metadata in database
+    4. Support client updates and revocation
+    """
+
+    def __init__(self, allow_dynamic_registration: bool = False):
+        """
+        Initialize the client registry.
+
+        Args:
+            allow_dynamic_registration: Whether to allow DCR for new clients
+        """
+        self.allow_dynamic_registration = allow_dynamic_registration
+        self._clients: Dict[str, MCPClientInfo] = {}
+        self._load_static_clients()
+
+    def _load_static_clients(self):
+        """Load statically configured clients from environment."""
+        # Load from ALLOWED_MCP_CLIENTS environment variable
+        allowed_clients = os.getenv("ALLOWED_MCP_CLIENTS", "").strip()
+
+        if allowed_clients:
+            # Parse comma-separated list
+            for client_id in allowed_clients.split(","):
+                client_id = client_id.strip()
+                if client_id:
+                    # Create basic client info
+                    # In production, would load full metadata from database
+                    self._clients[client_id] = MCPClientInfo(
+                        client_id=client_id,
+                        name=self._get_client_name(client_id),
+                        redirect_uris=["http://localhost:*", "http://127.0.0.1:*"],
+                        allowed_scopes=["openid", "profile", "email", "mcp-server:api"],
+                        is_public=True,
+                    )
+                    logger.info(f"Registered static client: {client_id}")
+
+        # Add well-known clients if not explicitly configured
+        if not self._clients:
+            self._add_well_known_clients()
+
+    def _get_client_name(self, client_id: str) -> str:
+        """Get human-readable name for client_id."""
+        known_names = {
+            "claude-desktop": "Claude Desktop",
+            "continue-dev": "Continue IDE Extension",
+            "zed-editor": "Zed Editor",
+            "vscode-mcp": "VS Code MCP Extension",
+            "test-mcp-client": "Test MCP Client",
+        }
+        return known_names.get(client_id, client_id.replace("-", " ").title())
+
+    def _add_well_known_clients(self):
+        """Add well-known MCP clients for testing and development."""
+        well_known = [
+            MCPClientInfo(
+                client_id="claude-desktop",
+                name="Claude Desktop",
+                redirect_uris=["http://localhost:*", "http://127.0.0.1:*"],
+                allowed_scopes=["openid", "profile", "email", "mcp-server:api"],
+                is_public=True,
+                metadata={"vendor": "Anthropic"},
+            ),
+            MCPClientInfo(
+                client_id="test-mcp-client",
+                name="Test MCP Client",
+                redirect_uris=["http://localhost:*", "http://127.0.0.1:*"],
+                allowed_scopes=["openid", "profile", "email", "mcp-server:api"],
+                is_public=True,
+                metadata={"purpose": "testing"},
+            ),
+        ]
+
+        for client in well_known:
+            self._clients[client.client_id] = client
+            logger.info(f"Registered well-known client: {client.client_id}")
+
+    def validate_client(
+        self,
+        client_id: str,
+        redirect_uri: Optional[str] = None,
+        scopes: Optional[List[str]] = None,
+    ) -> tuple[bool, Optional[str]]:
+        """
+        Validate a client_id and optionally its redirect_uri and scopes.
+
+        Args:
+            client_id: The client identifier to validate
+            redirect_uri: Optional redirect URI to validate
+            scopes: Optional list of scopes to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # Check if client exists
+        client = self._clients.get(client_id)
+        if not client:
+            if self.allow_dynamic_registration:
+                # In production, would attempt DCR here
+                logger.info(f"Unknown client {client_id}, would attempt DCR")
+                return True, None
+            else:
+                return False, f"Unknown client_id: {client_id}"
+
+        # Validate redirect_uri if provided
+        if redirect_uri:
+            if not self._validate_redirect_uri(client, redirect_uri):
+                return False, f"Invalid redirect_uri for client {client_id}"
+
+        # Validate scopes if provided
+        if scopes:
+            invalid_scopes = set(scopes) - set(client.allowed_scopes)
+            if invalid_scopes:
+                return False, f"Invalid scopes for client {client_id}: {invalid_scopes}"
+
+        return True, None
+
+    def _validate_redirect_uri(self, client: MCPClientInfo, redirect_uri: str) -> bool:
+        """
+        Validate redirect_uri against client's registered URIs.
+
+        Args:
+            client: The client info
+            redirect_uri: The URI to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        # Parse the redirect URI
+        from urllib.parse import urlparse
+
+        parsed = urlparse(redirect_uri)
+
+        # Check against registered patterns
+        for pattern in client.redirect_uris:
+            if "*" in pattern:
+                # Handle wildcard port (localhost:*)
+                pattern_base = pattern.replace(":*", "")
+                if redirect_uri.startswith(pattern_base + ":"):
+                    # Validate it's localhost with a port
+                    if parsed.hostname in ["localhost", "127.0.0.1"]:
+                        return True
+            elif redirect_uri == pattern:
+                return True
+
+        return False
+
+    def register_client(self, client_info: MCPClientInfo) -> bool:
+        """
+        Register a new MCP client (DCR support).
+
+        Args:
+            client_info: Client information to register
+
+        Returns:
+            True if registered successfully
+        """
+        if not self.allow_dynamic_registration:
+            logger.warning(f"DCR disabled, cannot register {client_info.client_id}")
+            return False
+
+        if client_info.client_id in self._clients:
+            logger.warning(f"Client {client_info.client_id} already registered")
+            return False
+
+        self._clients[client_info.client_id] = client_info
+        logger.info(f"Dynamically registered client: {client_info.client_id}")
+
+        # In production, would persist to database
+        return True
+
+    def get_client(self, client_id: str) -> Optional[MCPClientInfo]:
+        """
+        Get client information.
+
+        Args:
+            client_id: The client identifier
+
+        Returns:
+            Client info if found, None otherwise
+        """
+        return self._clients.get(client_id)
+
+    def list_clients(self) -> List[MCPClientInfo]:
+        """
+        List all registered clients.
+
+        Returns:
+            List of client information
+        """
+        return list(self._clients.values())
+
+
+# Global registry instance
+_registry: Optional[ClientRegistry] = None
+
+
+def get_client_registry() -> ClientRegistry:
+    """Get the global client registry instance."""
+    global _registry
+    if _registry is None:
+        # Check if DCR is enabled
+        allow_dcr = os.getenv("ENABLE_DCR", "false").lower() == "true"
+        _registry = ClientRegistry(allow_dynamic_registration=allow_dcr)
+    return _registry

nextcloud_mcp_server/auth/context_helper.py

@@ -1,43 +1,55 @@
-"""Helper functions for extracting OAuth context from MCP requests."""
+"""Helper functions for extracting OAuth context from MCP requests.
 
+ADR-005 compliant implementation with token exchange caching.
+"""
+
+import hashlib
 import logging
+import time
 
 from mcp.server.auth.provider import AccessToken
 from mcp.server.fastmcp import Context
 
 from ..client import NextcloudClient
+from ..config import get_settings
+from ..observability.metrics import (
+    oauth_token_cache_hits_total,
+    oauth_token_exchange_total,
+)
+from .token_exchange import exchange_token_for_audience
 
 logger = logging.getLogger(__name__)
 
+# Token exchange cache: token_hash -> (exchanged_token, expiry_timestamp)
+_exchange_cache: dict[str, tuple[str, float]] = {}
+
 
 def get_client_from_context(ctx: Context, base_url: str) -> NextcloudClient:
     """
-    Extract authenticated user context from MCP request and create NextcloudClient.
+    Create NextcloudClient for multi-audience mode (no exchange needed).
 
-    This function retrieves the OAuth access token from the MCP context,
-    extracts the username from the token's resource field (where we stored it
-    during token verification), and creates a NextcloudClient with bearer auth.
+    ADR-005 Mode 1: Use multi-audience tokens directly.
+    The UnifiedTokenVerifier validated MCP audience per RFC 7519.
+    Nextcloud will independently validate its own audience.
 
     Args:
         ctx: MCP request context containing session info
         base_url: Nextcloud base URL
 
     Returns:
-        NextcloudClient configured with bearer token auth
+        NextcloudClient configured with multi-audience token
 
     Raises:
         AttributeError: If context doesn't contain expected OAuth session data
         ValueError: If username cannot be extracted from token
     """
     try:
-        # In Starlette with FastMCP OAuth, the authenticated user info is stored in request.user
-        # The FastMCP auth middleware sets request.user to an AuthenticatedUser object
-        # which contains the access_token
+        # Extract validated access token from MCP context
         if hasattr(ctx.request_context.request, "user") and hasattr(
             ctx.request_context.request.user, "access_token"
         ):
             access_token: AccessToken = ctx.request_context.request.user.access_token
-            logger.debug("Retrieved access token from request.user for OAuth request")
+            logger.debug("Retrieved multi-audience token from request.user")
         else:
             logger.error(
                 "OAuth authentication failed: No access token found in request"
@@ -45,16 +57,20 @@ def get_client_from_context(ctx: Context, base_url: str) -> NextcloudClient:
             raise AttributeError("No access token found in OAuth request context")
 
         # Extract username from resource field (RFC 8707)
-        # We stored the username here during token verification
+        # UnifiedTokenVerifier stored the username here during validation
         username = access_token.resource
 
         if not username:
             logger.error("No username found in access token resource field")
             raise ValueError("Username not available in OAuth token context")
 
-        logger.debug(f"Creating OAuth NextcloudClient for user: {username}")
+        logger.debug(
+            f"Creating NextcloudClient for user {username} with multi-audience token "
+            f"(no exchange needed)"
+        )
 
-        # Create client with bearer token
+        # Token was validated to have MCP audience
+        # Nextcloud will validate its own audience independently
         return NextcloudClient.from_token(
             base_url=base_url, token=access_token.token, username=username
         )
@@ -63,3 +79,131 @@ def get_client_from_context(ctx: Context, base_url: str) -> NextcloudClient:
         logger.error(f"Failed to extract OAuth context: {e}")
         logger.error("This may indicate the server is not running in OAuth mode")
         raise
+
+
+async def get_session_client_from_context(
+    ctx: Context, base_url: str
+) -> NextcloudClient:
+    """
+    Create NextcloudClient using RFC 8693 token exchange with caching.
+
+    ADR-005 Mode 2: Exchange MCP token for Nextcloud token via RFC 8693.
+
+    This implements the token exchange pattern where:
+    1. Extract MCP token from context (validated by UnifiedTokenVerifier)
+    2. Check cache for existing exchanged token
+    3. If not cached or expired, exchange via RFC 8693
+    4. Cache the exchanged token to minimize exchange frequency
+    5. Create client with exchanged token
+
+    CRITICAL: This is where token exchange happens, NOT in the verifier.
+    The verifier already validated the MCP audience; now we exchange for Nextcloud.
+
+    Note: Nextcloud doesn't support OAuth scopes natively. Scopes are enforced
+    by the MCP server via @require_scopes decorator, not by the IdP. Therefore,
+    we don't pass scopes to the token exchange - the MCP server already validated
+    permissions before calling this function.
+
+    Args:
+        ctx: MCP request context containing session info
+        base_url: Nextcloud base URL
+
+    Returns:
+        NextcloudClient configured with ephemeral exchanged token
+
+    Raises:
+        AttributeError: If context doesn't contain expected OAuth session data
+        RuntimeError: If token exchange fails
+    """
+    settings = get_settings()
+
+    try:
+        # Extract MCP token from context
+        if hasattr(ctx.request_context.request, "user") and hasattr(
+            ctx.request_context.request.user, "access_token"
+        ):
+            access_token: AccessToken = ctx.request_context.request.user.access_token
+            mcp_token = access_token.token
+            username = access_token.resource  # Username from UnifiedTokenVerifier
+            logger.debug(f"Retrieved MCP token for user: {username}")
+        else:
+            logger.error("No MCP token found in request context")
+            raise AttributeError("No access token found in OAuth request context")
+
+        if not username:
+            logger.error("No username found in access token resource field")
+            raise ValueError("Username not available in OAuth token context")
+
+        # Check cache for existing exchanged token
+        cache_key = hashlib.sha256(mcp_token.encode()).hexdigest()
+        if cache_key in _exchange_cache:
+            cached_token, expiry = _exchange_cache[cache_key]
+            if time.time() < expiry:
+                logger.debug(
+                    f"Using cached exchanged token (expires in {expiry - time.time():.1f}s)"
+                )
+                oauth_token_cache_hits_total.labels(hit="true").inc()
+                return NextcloudClient.from_token(
+                    base_url=base_url, token=cached_token, username=username
+                )
+            else:
+                logger.debug("Cached token expired, removing from cache")
+                del _exchange_cache[cache_key]
+
+        oauth_token_cache_hits_total.labels(hit="false").inc()
+
+        # Perform RFC 8693 token exchange
+        logger.info(f"Exchanging MCP token for Nextcloud API token (user: {username})")
+
+        try:
+            # Exchange for Nextcloud resource URI audience
+            exchanged_token, expires_in = await exchange_token_for_audience(
+                subject_token=mcp_token,
+                requested_audience=settings.nextcloud_resource_uri or "nextcloud",
+                requested_scopes=None,  # Nextcloud doesn't support scopes
+            )
+            oauth_token_exchange_total.labels(status="success").inc()
+
+            logger.info(f"Token exchange successful. Token expires in {expires_in}s")
+        except Exception:
+            oauth_token_exchange_total.labels(status="error").inc()
+            raise
+
+        # Cache the exchanged token
+        # Use the minimum of exchange TTL and configured cache TTL
+        cache_ttl = min(expires_in, settings.token_exchange_cache_ttl)
+        _exchange_cache[cache_key] = (exchanged_token, time.time() + cache_ttl)
+        logger.debug(f"Cached exchanged token for {cache_ttl}s")
+
+        # Clean up expired cache entries
+        _cleanup_exchange_cache()
+
+        # Create client with exchanged token
+        return NextcloudClient.from_token(
+            base_url=base_url, token=exchanged_token, username=username
+        )
+
+    except AttributeError as e:
+        logger.error(f"Failed to extract OAuth context: {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Token exchange failed: {e}")
+        raise RuntimeError(f"Token exchange required but failed: {e}") from e
+
+
+def _cleanup_exchange_cache():
+    """Remove expired entries from the token exchange cache."""
+    global _exchange_cache
+    now = time.time()
+    expired_keys = [k for k, (_, expiry) in _exchange_cache.items() if expiry <= now]
+    for key in expired_keys:
+        del _exchange_cache[key]
+    if expired_keys:
+        logger.debug(f"Cleaned up {len(expired_keys)} expired cache entries")
+
+
+def clear_exchange_cache():
+    """Clear the entire token exchange cache. Useful for testing."""
+    global _exchange_cache
+    _exchange_cache.clear()
+    logger.debug("Token exchange cache cleared")

nextcloud_mcp_server/auth/keycloak_oauth.py

@@ -0,0 +1,583 @@
+"""
+Keycloak OAuth 2.0 / OIDC Client
+
+Handles OAuth flows with Keycloak as the identity provider, including:
+- OIDC Discovery
+- Authorization Code Flow with PKCE
+- Token refresh using refresh tokens (ADR-002 Tier 1)
+- Integration with RefreshTokenStorage
+"""
+
+import hashlib
+import logging
+import os
+import secrets
+from typing import Optional
+from urllib.parse import urlencode, urlparse
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class KeycloakOAuthClient:
+    """OAuth 2.0 client for Keycloak integration"""
+
+    def __init__(
+        self,
+        keycloak_url: str,
+        realm: str,
+        client_id: str,
+        client_secret: str,
+        redirect_uri: str,
+        scopes: Optional[list[str]] = None,
+    ):
+        """
+        Initialize Keycloak OAuth client.
+
+        Args:
+            keycloak_url: Base URL of Keycloak (e.g., http://keycloak:8080)
+            realm: Keycloak realm name
+            client_id: OAuth client ID
+            client_secret: OAuth client secret
+            redirect_uri: OAuth redirect URI
+            scopes: List of scopes to request (default: openid, profile, email, offline_access)
+        """
+        self.keycloak_url = keycloak_url.rstrip("/")
+        self.realm = realm
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.redirect_uri = redirect_uri
+        self.scopes = scopes or ["openid", "profile", "email", "offline_access"]
+
+        # Discovered endpoints (populated by discover())
+        self.authorization_endpoint: Optional[str] = None
+        self.token_endpoint: Optional[str] = None
+        self.userinfo_endpoint: Optional[str] = None
+        self.jwks_uri: Optional[str] = None
+        self.end_session_endpoint: Optional[str] = None
+
+        self._http_client: Optional[httpx.AsyncClient] = None
+
+    @classmethod
+    def from_env(cls) -> "KeycloakOAuthClient":
+        """
+        Create client from environment variables.
+
+        Environment variables:
+            KEYCLOAK_URL: Keycloak base URL
+            KEYCLOAK_REALM: Realm name
+            KEYCLOAK_CLIENT_ID: Client ID
+            KEYCLOAK_CLIENT_SECRET: Client secret
+            NEXTCLOUD_MCP_SERVER_URL: MCP server URL (for redirect URI)
+
+        Returns:
+            KeycloakOAuthClient instance
+
+        Raises:
+            ValueError: If required environment variables are missing
+        """
+        keycloak_url = os.getenv("KEYCLOAK_URL")
+        realm = os.getenv("KEYCLOAK_REALM")
+        client_id = os.getenv("KEYCLOAK_CLIENT_ID")
+        client_secret = os.getenv("KEYCLOAK_CLIENT_SECRET")
+        server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
+
+        if not all([keycloak_url, realm, client_id, client_secret]):
+            raise ValueError(
+                "Missing required environment variables: "
+                "KEYCLOAK_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET"
+            )
+
+        # Parse server URL to construct redirect URI
+        # Note: This is for OAuth client initialization, not used for actual redirects
+        # since this client is used for backend token operations (exchange, refresh)
+        parsed_url = urlparse(server_url)
+        redirect_uri = f"{parsed_url.scheme}://{parsed_url.netloc}/oauth/callback"
+
+        return cls(
+            keycloak_url=keycloak_url,
+            realm=realm,
+            client_id=client_id,
+            client_secret=client_secret,
+            redirect_uri=redirect_uri,
+        )
+
+    async def _get_http_client(self) -> httpx.AsyncClient:
+        """Get or create HTTP client"""
+        if self._http_client is None:
+            self._http_client = httpx.AsyncClient(timeout=30.0)
+        return self._http_client
+
+    async def close(self) -> None:
+        """Close HTTP client"""
+        if self._http_client:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    async def discover(self) -> None:
+        """
+        Perform OIDC discovery to get endpoint URLs.
+
+        Raises:
+            httpx.HTTPError: If discovery fails
+        """
+        discovery_url = (
+            f"{self.keycloak_url}/realms/{self.realm}/.well-known/openid-configuration"
+        )
+
+        logger.info(f"Discovering Keycloak endpoints at {discovery_url}")
+
+        client = await self._get_http_client()
+        response = await client.get(discovery_url)
+        response.raise_for_status()
+
+        discovery_data = response.json()
+
+        self.authorization_endpoint = discovery_data["authorization_endpoint"]
+        self.token_endpoint = discovery_data["token_endpoint"]
+        self.userinfo_endpoint = discovery_data["userinfo_endpoint"]
+        self.jwks_uri = discovery_data.get("jwks_uri")
+        self.end_session_endpoint = discovery_data.get("end_session_endpoint")
+
+        logger.info(
+            f"✓ Discovered Keycloak endpoints:\n"
+            f"  Authorization: {self.authorization_endpoint}\n"
+            f"  Token: {self.token_endpoint}\n"
+            f"  Userinfo: {self.userinfo_endpoint}\n"
+            f"  JWKS: {self.jwks_uri}"
+        )
+
+    def generate_pkce_challenge(self) -> tuple[str, str]:
+        """
+        Generate PKCE code verifier and challenge.
+
+        Returns:
+            Tuple of (code_verifier, code_challenge)
+        """
+        import base64
+
+        # Generate code verifier (43-128 characters)
+        code_verifier = secrets.token_urlsafe(32)
+
+        # Generate code challenge using S256 method (base64url-encoded SHA256)
+        digest = hashlib.sha256(code_verifier.encode()).digest()
+        code_challenge = base64.urlsafe_b64encode(digest).decode().rstrip("=")
+
+        return code_verifier, code_challenge
+
+    async def get_authorization_url(
+        self,
+        state: str,
+        code_challenge: str,
+        extra_params: Optional[dict[str, str]] = None,
+    ) -> str:
+        """
+        Build authorization URL for OAuth flow.
+
+        Args:
+            state: CSRF protection state parameter
+            code_challenge: PKCE code challenge
+            extra_params: Additional query parameters
+
+        Returns:
+            Authorization URL
+
+        Raises:
+            RuntimeError: If discover() hasn't been called
+        """
+        if not self.authorization_endpoint:
+            await self.discover()
+
+        if not self.authorization_endpoint:
+            raise RuntimeError("Authorization endpoint not discovered")
+
+        params = {
+            "client_id": self.client_id,
+            "response_type": "code",
+            "redirect_uri": self.redirect_uri,
+            "scope": " ".join(self.scopes),
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+        }
+
+        if extra_params:
+            params.update(extra_params)
+
+        return f"{self.authorization_endpoint}?{urlencode(params)}"
+
+    async def exchange_authorization_code(
+        self,
+        code: str,
+        code_verifier: str,
+    ) -> dict:
+        """
+        Exchange authorization code for tokens.
+
+        Args:
+            code: Authorization code from OAuth callback
+            code_verifier: PKCE code verifier
+
+        Returns:
+            Token response dictionary with keys:
+                - access_token: Access token
+                - refresh_token: Refresh token (if offline_access scope requested)
+                - id_token: ID token (JWT)
+                - expires_in: Access token lifetime in seconds
+                - refresh_expires_in: Refresh token lifetime in seconds (optional)
+                - token_type: Token type (Bearer)
+
+        Raises:
+            httpx.HTTPError: If token exchange fails
+        """
+        if not self.token_endpoint:
+            await self.discover()
+
+        if not self.token_endpoint:
+            raise RuntimeError("Token endpoint not discovered")
+
+        logger.debug(
+            f"Exchanging authorization code for tokens at {self.token_endpoint}"
+        )
+
+        client = await self._get_http_client()
+        response = await client.post(
+            self.token_endpoint,
+            data={
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": self.redirect_uri,
+                "code_verifier": code_verifier,
+            },
+            auth=(self.client_id, self.client_secret),
+        )
+
+        response.raise_for_status()
+        token_data = response.json()
+
+        logger.info("✓ Successfully exchanged authorization code for tokens")
+
+        if "refresh_token" in token_data:
+            logger.info("  Received refresh token (offline_access granted)")
+
+        return token_data
+
+    async def refresh_access_token(self, refresh_token: str) -> dict:
+        """
+        Refresh access token using refresh token.
+
+        Args:
+            refresh_token: Refresh token
+
+        Returns:
+            Token response dictionary (same format as exchange_authorization_code)
+
+        Raises:
+            httpx.HTTPError: If token refresh fails
+        """
+        if not self.token_endpoint:
+            await self.discover()
+
+        if not self.token_endpoint:
+            raise RuntimeError("Token endpoint not discovered")
+
+        logger.debug("Refreshing access token")
+
+        client = await self._get_http_client()
+        response = await client.post(
+            self.token_endpoint,
+            data={
+                "grant_type": "refresh_token",
+                "refresh_token": refresh_token,
+            },
+            auth=(self.client_id, self.client_secret),
+        )
+
+        response.raise_for_status()
+        token_data = response.json()
+
+        logger.debug("✓ Successfully refreshed access token")
+
+        return token_data
+
+    async def get_userinfo(self, access_token: str) -> dict:
+        """
+        Get user information using access token.
+
+        Args:
+            access_token: Access token
+
+        Returns:
+            Userinfo response dictionary with claims like:
+                - sub: Subject (user ID)
+                - name: Full name
+                - preferred_username: Username
+                - email: Email address
+                - email_verified: Email verification status
+
+        Raises:
+            httpx.HTTPError: If userinfo request fails
+        """
+        if not self.userinfo_endpoint:
+            await self.discover()
+
+        if not self.userinfo_endpoint:
+            raise RuntimeError("Userinfo endpoint not discovered")
+
+        logger.debug("Fetching user info")
+
+        client = await self._get_http_client()
+        response = await client.get(
+            self.userinfo_endpoint,
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+
+        response.raise_for_status()
+        userinfo = response.json()
+
+        logger.debug(f"✓ Retrieved user info for subject: {userinfo.get('sub')}")
+
+        return userinfo
+
+    async def get_service_account_token(self, scopes: list[str] | None = None) -> dict:
+        """
+        Get a service account token using client_credentials grant.
+
+        ⚠️ **WARNING: DO NOT USE FOR DIRECT API ACCESS IN OAUTH MODE** ⚠️
+
+        This method creates a service account user in Nextcloud which VIOLATES
+        OAuth "act on-behalf-of" principles. Using this token directly for API
+        access will:
+        - Create a Nextcloud user: `service-account-{client_id}`
+        - Attribute all actions to service account instead of real user
+        - Break audit trail and user attribution
+        - Create stateful server identity in Nextcloud
+        - Violate OAuth security model
+
+        **Valid Use Case**: ONLY as subject_token for RFC 8693 token exchange
+        (ADR-002 Tier 2) where it's immediately exchanged for a user token.
+
+        **Invalid Use Case**: Direct API access with this token (ADR-002 rejected
+        this as "Tier 1" - see docs/ADR-002-vector-sync-authentication.md).
+
+        **Alternative**: Use token exchange (impersonation/delegation) for
+        background operations, or use BasicAuth mode if truly need service account.
+
+        This requires the client to have serviceAccountsEnabled=true in provider.
+
+        Args:
+            scopes: Optional list of scopes to request (default: openid profile email)
+
+        Returns:
+            Token response dictionary with:
+                - access_token: Service account access token
+                - token_type: Bearer
+                - expires_in: Token lifetime in seconds
+                - scope: Granted scopes
+
+        Raises:
+            httpx.HTTPError: If token request fails
+
+        See Also:
+            - ADR-002 "Will Not Implement" section for detailed critique
+            - exchange_token_for_user() for proper token exchange usage
+        """
+        if not self.token_endpoint:
+            await self.discover()
+
+        if not self.token_endpoint:
+            raise RuntimeError("Token endpoint not discovered")
+
+        # Default scopes
+        if scopes is None:
+            scopes = ["openid", "profile", "email"]
+
+        scope_str = " ".join(scopes)
+
+        logger.info(f"Requesting service account token with scopes: {scope_str}")
+
+        client = await self._get_http_client()
+        response = await client.post(
+            self.token_endpoint,
+            data={
+                "grant_type": "client_credentials",
+                "scope": scope_str,
+            },
+            auth=(self.client_id, self.client_secret),
+        )
+
+        response.raise_for_status()
+        token_data = response.json()
+
+        logger.info("✓ Service account token acquired")
+
+        return token_data
+
+    async def exchange_token_for_user(
+        self,
+        subject_token: str,
+        target_user_id: str | None = None,
+        audience: str | None = None,
+        scopes: list[str] | None = None,
+    ) -> dict:
+        """
+        Exchange a token for a user-scoped token using RFC 8693 Token Exchange.
+
+        This allows the MCP server (with a service account token) to obtain
+        user-scoped access tokens for background operations without needing
+        refresh tokens.
+
+        Args:
+            subject_token: The token being exchanged (service account or user token)
+            target_user_id: Optional user ID to impersonate/exchange for
+            audience: Optional target audience (client ID)
+            scopes: Optional list of scopes for the new token
+
+        Returns:
+            Token response dictionary with:
+                - access_token: User-scoped access token
+                - issued_token_type: urn:ietf:params:oauth:token-type:access_token
+                - token_type: Bearer
+                - expires_in: Token lifetime in seconds
+
+        Raises:
+            httpx.HTTPError: If token exchange fails (403 if not authorized)
+
+        Example:
+            # Get service account token
+            service_token = await client.get_service_account_token()
+
+            # Exchange for user-scoped token
+            user_token = await client.exchange_token_for_user(
+                subject_token=service_token["access_token"],
+                target_user_id="admin",  # Username or sub claim
+                audience="nextcloud",
+                scopes=["notes:read", "files:read"]
+            )
+
+        Note:
+            This implements BOTH ADR-002 tiers:
+
+            **Tier 2 (Delegation - Recommended)**: When target_user_id is None
+            - Uses Keycloak Standard V2 (production-ready)
+            - Service account maintains its identity (sub claim unchanged)
+            - No special permissions required
+
+            **Tier 1 (Impersonation - Advanced)**: When target_user_id is provided
+            - Requires Keycloak Legacy V1 (--features=preview)
+            - Subject claim changes to target user
+            - Requires impersonation role granted via Keycloak CLI:
+              ```
+              kcadm.sh add-roles -r <realm> \
+                --uusername service-account-<client-id> \
+                --cclientid realm-management \
+                --rolename impersonation
+              ```
+
+            Both tiers require:
+            - Client has token.exchange.grant.enabled=true
+            - Client has serviceAccountsEnabled=true
+        """
+        if not self.token_endpoint:
+            await self.discover()
+
+        if not self.token_endpoint:
+            raise RuntimeError("Token endpoint not discovered")
+
+        # Build token exchange request
+        data = {
+            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+            "subject_token": subject_token,
+            "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
+            "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
+        }
+
+        # Add optional parameters
+        if audience:
+            data["audience"] = audience
+
+        if scopes:
+            data["scope"] = " ".join(scopes)
+
+        if target_user_id:
+            # Tier 1: Impersonation (Legacy V1)
+            # Use requested_subject for user impersonation
+            data["requested_subject"] = target_user_id
+            logger.info(
+                f"Exchanging token with impersonation (Tier 1): target_user={target_user_id}"
+            )
+        else:
+            # Tier 2: Delegation (Standard V2)
+            logger.info(
+                "Exchanging token with delegation (Tier 2): service account identity preserved"
+            )
+
+        client = await self._get_http_client()
+        response = await client.post(
+            self.token_endpoint,
+            data=data,
+            auth=(self.client_id, self.client_secret),
+        )
+
+        if response.status_code != 200:
+            error_data = (
+                response.json()
+                if response.headers.get("content-type", "").startswith(
+                    "application/json"
+                )
+                else {"error": "unknown"}
+            )
+            logger.error(f"Token exchange failed: {response.status_code}")
+            logger.error(f"Error response: {error_data}")
+
+        response.raise_for_status()
+        token_data = response.json()
+
+        logger.info(
+            f"✓ Token exchange successful, issued_token_type: {token_data.get('issued_token_type')}"
+        )
+
+        return token_data
+
+    async def check_token_exchange_support(self) -> bool:
+        """
+        Check if Keycloak supports RFC 8693 token exchange.
+
+        Returns:
+            True if token exchange is supported
+
+        Note:
+            This is ADR-002 Tier 2. Most Keycloak installations don't
+            have token exchange enabled by default.
+        """
+        if not self.token_endpoint:
+            await self.discover()
+
+        # Try to get discovery document and check for token exchange grant
+        discovery_url = (
+            f"{self.keycloak_url}/realms/{self.realm}/.well-known/openid-configuration"
+        )
+
+        try:
+            client = await self._get_http_client()
+            response = await client.get(discovery_url)
+            response.raise_for_status()
+            discovery_data = response.json()
+
+            grant_types = discovery_data.get("grant_types_supported", [])
+            supported = "urn:ietf:params:oauth:grant-type:token-exchange" in grant_types
+
+            if supported:
+                logger.info("✓ Token exchange (RFC 8693) is supported")
+            else:
+                logger.info("Token exchange (RFC 8693) is not supported")
+
+            return supported
+
+        except Exception as e:
+            logger.warning(f"Failed to check token exchange support: {e}")
+            return False
+
+
+__all__ = ["KeycloakOAuthClient"]

nextcloud_mcp_server/auth/oauth_routes.py

@@ -0,0 +1,640 @@
+"""
+OAuth 2.0 Login Routes for ADR-004 (Offline Access Architecture)
+
+Implements dual OAuth flows with optional offline access provisioning:
+
+Flow 1: Client Authentication - MCP client authenticates directly to IdP
+- Client requests: Nextcloud MCP resource scopes (notes:*, calendar:*, etc.)
+- Token audience (aud): "mcp-server"
+- No server interception - IdP redirects directly to client
+- Client receives resource-scoped token for MCP session
+
+Flow 2: Resource Provisioning - MCP server gets delegated Nextcloud access
+- Triggered by user calling provision_nextcloud_access tool
+- Server requests: openid, profile, email scopes, offline_access
+- Separate login flow outside MCP session, results in browser login for user
+- Token audience (aud): "nextcloud", redirect/callback to mcp server
+- Server receives refresh token for offline access
+- Client never sees this token
+
+"""
+
+import hashlib
+import logging
+import os
+import secrets
+from base64 import urlsafe_b64encode
+from urllib.parse import urlencode
+
+import httpx
+import jwt
+from starlette.requests import Request
+from starlette.responses import JSONResponse, RedirectResponse
+
+from nextcloud_mcp_server.auth.client_registry import get_client_registry
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+logger = logging.getLogger(__name__)
+
+
+async def oauth_authorize(request: Request) -> RedirectResponse | JSONResponse:
+    """
+    OAuth authorization endpoint for Flow 1: Client Authentication.
+
+    The client authenticates directly to the IdP with its own client_id.
+    The server validates the client is authorized but does NOT intercept the callback.
+    IdP redirects directly back to the client's redirect_uri.
+
+    Query parameters:
+        response_type: Must be "code"
+        client_id: MCP client identifier (required)
+        redirect_uri: Client's localhost redirect URI (required)
+        scope: Requested scopes (optional, defaults to "openid profile email")
+        state: CSRF protection state (required)
+        code_challenge: PKCE code challenge from client (required)
+        code_challenge_method: PKCE method, must be "S256" (required)
+
+    Returns:
+        302 redirect to IdP authorization endpoint
+    """
+    # Extract parameters
+    response_type = request.query_params.get("response_type")
+    client_id = request.query_params.get("client_id")
+    redirect_uri = request.query_params.get("redirect_uri")
+    state = request.query_params.get("state")
+    code_challenge = request.query_params.get("code_challenge")
+    code_challenge_method = request.query_params.get("code_challenge_method", "S256")
+
+    # Validate required parameters
+    if response_type != "code":
+        return JSONResponse(
+            {
+                "error": "unsupported_response_type",
+                "error_description": "Only 'code' response_type is supported",
+            },
+            status_code=400,
+        )
+
+    if not redirect_uri:
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": "redirect_uri is required",
+            },
+            status_code=400,
+        )
+
+    # Validate redirect_uri is localhost (RFC 8252 for native clients)
+    if not redirect_uri.startswith(("http://localhost:", "http://127.0.0.1:")):
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": "redirect_uri must be localhost for native clients",
+            },
+            status_code=400,
+        )
+
+    if not state:
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": "state parameter is required for CSRF protection",
+            },
+            status_code=400,
+        )
+
+    if not code_challenge:
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": "code_challenge is required (PKCE)",
+            },
+            status_code=400,
+        )
+
+    if code_challenge_method != "S256":
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": "code_challenge_method must be S256",
+            },
+            status_code=400,
+        )
+
+    # Validate client_id (required for Flow 1)
+    if not client_id:
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": "client_id is required",
+            },
+            status_code=400,
+        )
+
+    # Validate client using registry
+    registry = get_client_registry()
+    is_valid, error_msg = registry.validate_client(
+        client_id=client_id,
+        redirect_uri=redirect_uri,
+        scopes=request.query_params.get("scope", "").split()
+        if request.query_params.get("scope")
+        else None,
+    )
+
+    if not is_valid:
+        logger.warning(f"Client validation failed: {error_msg}")
+        return JSONResponse(
+            {
+                "error": "unauthorized_client",
+                "error_description": error_msg,
+            },
+            status_code=401,
+        )
+
+    # Get OAuth context from app state
+    oauth_ctx = request.app.state.oauth_context
+    if not oauth_ctx:
+        return JSONResponse(
+            {
+                "error": "server_error",
+                "error_description": "OAuth not configured on server",
+            },
+            status_code=500,
+        )
+
+    oauth_client = oauth_ctx["oauth_client"]
+    oauth_config = oauth_ctx["config"]
+
+    # Flow 1: Client authenticates directly to IdP WITHOUT server interception
+    # CRITICAL: This is a direct pass-through to IdP
+    # The IdP will redirect directly back to the client's callback
+    # The MCP server does NOT see the IdP authorization code!
+
+    logger.info(
+        f"Starting Flow 1 - no server session needed, "
+        f"client will handle IdP response directly at {redirect_uri}"
+    )
+
+    # Use client's redirect_uri for DIRECT callback (bypasses server)
+    callback_uri = redirect_uri
+
+    # Request resource scopes for MCP tools access
+    # The token will have aud: "mcp-server" claim
+    # Build scopes from NEXTCLOUD_OIDC_SCOPES config
+    default_scopes = "openid profile email"
+    resource_scopes = oauth_config.get("scopes", "")
+    scopes = f"{default_scopes} {resource_scopes}".strip()
+
+    # Pass through client's state directly
+    idp_state = state
+
+    # Use client's own client_id (client must be pre-registered at IdP)
+    idp_client_id = client_id
+
+    logger.info("Flow 1: Direct client auth to IdP")
+    logger.info(f"  Client ID: {client_id}")
+    logger.info(f"  Client will receive IdP code directly at: {callback_uri}")
+    logger.info(f"  Scopes: {scopes} (resource access for MCP tools)")
+
+    # Get authorization endpoint from OAuth client
+    if oauth_client:
+        # External IdP mode (Keycloak) - use oauth_client
+        auth_url = await oauth_client.get_authorization_url(
+            state=idp_state,
+            code_challenge="",  # Server doesn't use PKCE with IdP
+        )
+        logger.info(f"Redirecting to external IdP: {auth_url.split('?')[0]}")
+    else:
+        # Integrated mode (Nextcloud OIDC) - build URL directly
+        discovery_url = oauth_config.get("discovery_url")
+        if not discovery_url:
+            return JSONResponse(
+                {
+                    "error": "server_error",
+                    "error_description": "OAuth discovery URL not configured",
+                },
+                status_code=500,
+            )
+
+        # Fetch authorization endpoint from discovery
+        async with httpx.AsyncClient() as http_client:
+            response = await http_client.get(discovery_url)
+            response.raise_for_status()
+            discovery = response.json()
+            authorization_endpoint = discovery["authorization_endpoint"]
+
+        # IMPORTANT: Replace internal Docker hostname with public URL for browser access
+        # The discovery endpoint returns http://app/apps/oidc/authorize (internal)
+        # But browsers need http://localhost:8080/apps/oidc/authorize (public)
+        from urllib.parse import urlparse as parse_url
+
+        public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+        if public_issuer:
+            # Parse internal and authorization endpoint to compare hostnames
+            internal_parsed = parse_url(oauth_config["nextcloud_host"])
+            auth_parsed = parse_url(authorization_endpoint)
+
+            # Check if authorization endpoint uses internal hostname
+            if auth_parsed.hostname == internal_parsed.hostname:
+                # Replace internal hostname+port with public URL
+                # Keep the path from authorization_endpoint
+                public_parsed = parse_url(public_issuer)
+                authorization_endpoint = (
+                    f"{public_parsed.scheme}://{public_parsed.netloc}{auth_parsed.path}"
+                )
+                if auth_parsed.query:
+                    authorization_endpoint += f"?{auth_parsed.query}"
+                logger.info(
+                    f"Rewrote authorization endpoint for browser access: {authorization_endpoint}"
+                )
+
+        idp_params = {
+            "client_id": idp_client_id,
+            "redirect_uri": callback_uri,
+            "response_type": "code",
+            "scope": scopes,
+            "state": idp_state,
+            "prompt": "consent",  # Ensure refresh token
+            "resource": f"{oauth_config['mcp_server_url']}/mcp",  # MCP server audience
+        }
+
+        auth_url = f"{authorization_endpoint}?{urlencode(idp_params)}"
+        logger.info(f"Redirecting to Nextcloud OIDC: {auth_url.split('?')[0]}")
+
+    return RedirectResponse(auth_url, status_code=302)
+
+
+async def oauth_authorize_nextcloud(
+    request: Request,
+) -> RedirectResponse | JSONResponse:
+    """
+    OAuth authorization endpoint for Flow 2: Resource Provisioning.
+
+    This endpoint is used by the provision_nextcloud_access MCP tool
+    to initiate delegated resource access to Nextcloud. Requires a separate
+    login flow outside of the MCP session.
+
+    Query parameters:
+        state: Session state for tracking
+
+    Returns:
+        302 redirect to IdP authorization endpoint
+    """
+    state = request.query_params.get("state")
+    if not state:
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": "state parameter is required",
+            },
+            status_code=400,
+        )
+
+    # Get OAuth context
+    oauth_ctx = request.app.state.oauth_context
+    if not oauth_ctx:
+        return JSONResponse(
+            {
+                "error": "server_error",
+                "error_description": "OAuth not configured on server",
+            },
+            status_code=500,
+        )
+
+    oauth_config = oauth_ctx["config"]
+
+    # Get MCP server's OAuth client credentials
+    mcp_server_client_id = os.getenv(
+        "MCP_SERVER_CLIENT_ID", oauth_config.get("client_id")
+    )
+    if not mcp_server_client_id:
+        return JSONResponse(
+            {
+                "error": "server_error",
+                "error_description": "MCP server OAuth client not configured",
+            },
+            status_code=500,
+        )
+
+    mcp_server_url = oauth_config["mcp_server_url"]
+    callback_uri = f"{mcp_server_url}/oauth/callback"
+
+    # Flow 2: Server only needs identity + offline access (no resource scopes)
+    # Resource scopes are requested by client in Flow 1
+    scopes = "openid profile email offline_access"
+
+    # Generate PKCE values (required by Nextcloud OIDC)
+    code_verifier = secrets.token_urlsafe(32)
+    digest = hashlib.sha256(code_verifier.encode()).digest()
+    code_challenge = urlsafe_b64encode(digest).decode().rstrip("=")
+
+    # Store code_verifier in session for retrieval during callback
+    storage = oauth_ctx["storage"]
+    await storage.store_oauth_session(
+        session_id=state,
+        client_id=mcp_server_client_id,
+        client_redirect_uri=callback_uri,
+        state=state,
+        code_challenge=code_challenge,
+        code_challenge_method="S256",
+        mcp_authorization_code=code_verifier,  # Store code_verifier here temporarily
+        flow_type="flow2",
+        ttl_seconds=600,  # 10 minutes
+    )
+
+    # Get authorization endpoint
+    discovery_url = oauth_config.get("discovery_url")
+    if not discovery_url:
+        return JSONResponse(
+            {
+                "error": "server_error",
+                "error_description": "OAuth discovery URL not configured",
+            },
+            status_code=500,
+        )
+
+    async with httpx.AsyncClient() as http_client:
+        response = await http_client.get(discovery_url)
+        response.raise_for_status()
+        discovery = response.json()
+        authorization_endpoint = discovery["authorization_endpoint"]
+
+    # Fix internal hostname for browser access
+    public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+    if public_issuer:
+        from urllib.parse import urlparse as parse_url
+
+        internal_parsed = parse_url(oauth_config["nextcloud_host"])
+        auth_parsed = parse_url(authorization_endpoint)
+
+        if auth_parsed.hostname == internal_parsed.hostname:
+            public_parsed = parse_url(public_issuer)
+            authorization_endpoint = (
+                f"{public_parsed.scheme}://{public_parsed.netloc}{auth_parsed.path}"
+            )
+
+    # Build authorization URL
+    idp_params = {
+        "client_id": mcp_server_client_id,
+        "redirect_uri": callback_uri,
+        "response_type": "code",
+        "scope": scopes,
+        "state": state,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+        "prompt": "consent",  # Force consent to show resource access
+        "access_type": "offline",  # Request refresh token
+        "resource": oauth_config["nextcloud_resource_uri"],  # Nextcloud audience
+    }
+
+    auth_url = f"{authorization_endpoint}?{urlencode(idp_params)}"
+    logger.info("Flow 2: Redirecting to IdP for resource provisioning")
+
+    return RedirectResponse(auth_url, status_code=302)
+
+
+async def oauth_callback_nextcloud(request: Request):
+    """
+    OAuth callback endpoint for Flow 2: Resource Provisioning.
+
+    The IdP redirects here after user grants delegated resource access.
+    Server stores the master refresh token for offline access.
+
+    Query parameters:
+        code: Authorization code from IdP
+        state: State parameter (session identifier)
+        error: Error code (if authorization failed)
+
+    Returns:
+        JSON response or HTML success page
+    """
+    # Check for errors from IdP
+    error = request.query_params.get("error")
+    if error:
+        error_description = request.query_params.get(
+            "error_description", "Authorization failed"
+        )
+        logger.error(f"Flow 2 authorization error: {error} - {error_description}")
+        return JSONResponse(
+            {
+                "error": error,
+                "error_description": error_description,
+            },
+            status_code=400,
+        )
+
+    code = request.query_params.get("code")
+    state = request.query_params.get("state")
+
+    if not code or not state:
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": "code and state parameters are required",
+            },
+            status_code=400,
+        )
+
+    # Get OAuth context
+    oauth_ctx = request.app.state.oauth_context
+    storage: RefreshTokenStorage = oauth_ctx["storage"]
+    oauth_config = oauth_ctx["config"]
+
+    # Retrieve code_verifier from session storage (PKCE required by Nextcloud OIDC)
+    code_verifier = ""
+    oauth_session = await storage.get_oauth_session(state)
+    if oauth_session:
+        # code_verifier was stored in mcp_authorization_code field
+        code_verifier = oauth_session.get("mcp_authorization_code", "")
+        logger.info(
+            f"Retrieved code_verifier for Flow 2 callback (state={state[:16]}...)"
+        )
+
+    # Exchange code for tokens
+    mcp_server_client_id = os.getenv(
+        "MCP_SERVER_CLIENT_ID", oauth_config.get("client_id")
+    )
+    mcp_server_client_secret = os.getenv(
+        "MCP_SERVER_CLIENT_SECRET", oauth_config.get("client_secret")
+    )
+    mcp_server_url = oauth_config["mcp_server_url"]
+    callback_uri = f"{mcp_server_url}/oauth/callback"
+
+    discovery_url = oauth_config.get("discovery_url")
+    async with httpx.AsyncClient() as http_client:
+        response = await http_client.get(discovery_url)
+        response.raise_for_status()
+        discovery = response.json()
+        token_endpoint = discovery["token_endpoint"]
+
+    # Build token exchange params
+    token_params = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": callback_uri,
+        "client_id": mcp_server_client_id,
+        "client_secret": mcp_server_client_secret,
+    }
+
+    # Add code_verifier for PKCE (required by Nextcloud OIDC)
+    if code_verifier:
+        token_params["code_verifier"] = code_verifier
+
+    # Exchange code for tokens
+    async with httpx.AsyncClient() as http_client:
+        response = await http_client.post(
+            token_endpoint,
+            data=token_params,
+        )
+        response.raise_for_status()
+        token_data = response.json()
+
+    refresh_token = token_data.get("refresh_token")
+    id_token = token_data.get("id_token")
+
+    # Decode ID token to get user info
+    logger.info("=" * 60)
+    logger.info("oauth_callback_nextcloud: Extracting user_id from ID token")
+    logger.info("=" * 60)
+    try:
+        userinfo = jwt.decode(id_token, options={"verify_signature": False})
+        user_id = userinfo.get("sub")
+        username = userinfo.get("preferred_username") or userinfo.get("email")
+        logger.info("  ✓ ID token decode SUCCESSFUL")
+        logger.info(f"  Extracted user_id: {user_id}")
+        logger.info(f"  Username: {username}")
+        logger.info(f"  ID token payload keys: {list(userinfo.keys())}")
+        logger.info(f"Flow 2: User {username} provisioned resource access")
+    except Exception as e:
+        logger.error(f"  ✗ ID token decode FAILED: {type(e).__name__}: {e}")
+        user_id = "unknown"
+        logger.error(f"  Using fallback user_id: {user_id}")
+
+    # Store master refresh token for Flow 2
+    if refresh_token:
+        # Parse granted scopes from token response
+        granted_scopes = (
+            token_data.get("scope", "").split() if token_data.get("scope") else None
+        )
+
+        logger.info("Storing refresh token:")
+        logger.info(f"  user_id: {user_id}")
+        logger.info("  flow_type: flow2")
+        logger.info("  token_audience: nextcloud")
+        logger.info(f"  provisioning_client_id: {state[:16]}...")
+        logger.info(f"  scopes: {granted_scopes}")
+
+        await storage.store_refresh_token(
+            user_id=user_id,
+            refresh_token=refresh_token,
+            flow_type="flow2",
+            token_audience="nextcloud",
+            provisioning_client_id=state,  # Store which client initiated provisioning
+            scopes=granted_scopes,
+            expires_at=None,  # Refresh tokens typically don't expire
+        )
+        logger.info(f"✓ Stored Flow 2 master refresh token for user {user_id}")
+        logger.info("=" * 60)
+
+    # Return success HTML page
+    success_html = """
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>Nextcloud Access Provisioned</title>
+        <style>
+            body { font-family: Arial, sans-serif; text-align: center; margin-top: 50px; }
+            .success { color: green; }
+            .info { margin-top: 20px; color: #666; }
+        </style>
+    </head>
+    <body>
+        <h1 class="success">✓ Nextcloud Access Provisioned</h1>
+        <p>The MCP server now has offline access to your Nextcloud resources.</p>
+        <p class="info">You can close this window and return to your MCP client.</p>
+    </body>
+    </html>
+    """
+
+    from starlette.responses import HTMLResponse
+
+    return HTMLResponse(content=success_html, status_code=200)
+
+
+async def oauth_callback(request: Request):
+    """
+    Unified OAuth callback endpoint supporting multiple flows.
+
+    This endpoint consolidates all OAuth callback handling into a single URL.
+    The flow type is determined by looking up the OAuth session using the
+    state parameter.
+
+    This simplifies IdP configuration by requiring only one callback URL
+    to be registered: /oauth/callback
+
+    Query parameters:
+        code: Authorization code from IdP
+        state: CSRF protection state (also used to lookup flow type)
+        error: Error code (if authorization failed)
+
+    Returns:
+        Response from the appropriate flow handler
+    """
+    # Get state parameter to lookup OAuth session
+    state = request.query_params.get("state")
+    if not state:
+        logger.warning("Unified callback called without state parameter")
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": "state parameter is required",
+            },
+            status_code=400,
+        )
+
+    # Lookup OAuth session to determine flow type
+    oauth_ctx = request.app.state.oauth_context
+    if not oauth_ctx:
+        logger.error("OAuth context not available")
+        return JSONResponse(
+            {
+                "error": "server_error",
+                "error_description": "OAuth not configured on server",
+            },
+            status_code=500,
+        )
+
+    storage = oauth_ctx["storage"]
+    oauth_session = await storage.get_oauth_session(state)
+
+    # Determine flow type from session, default to "browser" for backwards compatibility
+    flow_type = (
+        oauth_session.get("flow_type", "browser") if oauth_session else "browser"
+    )
+
+    logger.info(f"Unified callback: flow_type={flow_type} (from session lookup)")
+
+    if flow_type == "flow2":
+        # Flow 2: Resource Provisioning - MCP server gets delegated Nextcloud access
+        logger.info("Routing to Flow 2 (resource provisioning)")
+        return await oauth_callback_nextcloud(request)
+
+    elif flow_type == "browser":
+        # Browser UI Login - establish browser session for /user/page access
+        logger.info("Routing to browser login flow")
+        from nextcloud_mcp_server.auth.browser_oauth_routes import (
+            oauth_login_callback,
+        )
+
+        return await oauth_login_callback(request)
+
+    else:
+        # Unknown flow type
+        logger.warning(f"Unknown flow_type in OAuth session: {flow_type}")
+        return JSONResponse(
+            {
+                "error": "invalid_request",
+                "error_description": f"Unknown flow type: {flow_type}",
+            },
+            status_code=400,
+        )

nextcloud_mcp_server/auth/permissions.py

@@ -0,0 +1,54 @@
+"""Permission checking utilities for Nextcloud admin operations."""
+
+import logging
+
+from httpx import AsyncClient
+from starlette.requests import Request
+
+from nextcloud_mcp_server.client.users import UsersClient
+
+logger = logging.getLogger(__name__)
+
+
+async def is_nextcloud_admin(request: Request, http_client: AsyncClient) -> bool:
+    """Check if the authenticated user is a Nextcloud administrator.
+
+    This function extracts the username from the session/request context
+    and checks if the user is a member of the "admin" group in Nextcloud.
+
+    Args:
+        request: Starlette request object with authenticated user
+        http_client: Authenticated HTTP client for Nextcloud API calls
+
+    Returns:
+        True if user is admin, False otherwise
+
+    Example:
+        ```python
+        if await is_nextcloud_admin(request, http_client):
+            # Show admin-only features
+            pass
+        ```
+    """
+    try:
+        # Extract username from authenticated session
+        username = request.user.display_name
+        if not username:
+            logger.warning("No username found in authenticated session")
+            return False
+
+        # Query Nextcloud for user's group memberships
+        users_client = UsersClient(http_client, username)
+        user_groups = await users_client.get_user_groups(username)
+
+        # Check if user is in the admin group
+        is_admin = "admin" in user_groups
+        logger.debug(
+            f"Admin check for user '{username}': {is_admin} (groups: {user_groups})"
+        )
+
+        return is_admin
+
+    except Exception as e:
+        logger.error(f"Error checking admin permissions: {e}", exc_info=True)
+        return False

nextcloud_mcp_server/auth/provisioning_decorator.py

@@ -0,0 +1,194 @@
+"""
+Provisioning decorator for ADR-004 (Offline Access Architecture).
+
+This decorator ensures users have completed Flow 2 (Resource Provisioning)
+before accessing Nextcloud resources when offline access is enabled.
+"""
+
+import functools
+import logging
+from typing import Callable
+
+from mcp.server.fastmcp import Context
+from mcp.shared.exceptions import McpError
+from mcp.types import ErrorData
+
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+logger = logging.getLogger(__name__)
+
+
+def require_provisioning(func: Callable) -> Callable:
+    """
+    Decorator that checks if user has provisioned Nextcloud access (Flow 2).
+
+    This decorator:
+    1. Extracts user_id from the MCP token (Flow 1)
+    2. Checks if user has completed Flow 2 provisioning
+    3. Returns helpful error message if not provisioned
+    4. Allows access if provisioned
+
+    Usage:
+        @mcp.tool()
+        @require_provisioning
+        async def list_notes(ctx: Context):
+            # Tool implementation
+            pass
+    """
+
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        # Extract context from arguments
+        ctx = None
+        for arg in args:
+            if isinstance(arg, Context):
+                ctx = arg
+                break
+        if not ctx:
+            ctx = kwargs.get("ctx")
+
+        if not ctx:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message="Context not found - cannot verify provisioning",
+                )
+            )
+
+        # Check if we're in BasicAuth mode - if so, skip provisioning check
+        # In BasicAuth mode, there's no OAuth and no provisioning needed
+        lifespan_ctx = ctx.request_context.lifespan_context
+        if hasattr(lifespan_ctx, "client"):
+            # BasicAuth mode - no provisioning needed, just proceed
+            logger.debug("BasicAuth mode detected - skipping provisioning check")
+            return await func(*args, **kwargs)
+
+        # Check if we're in token exchange mode - if so, skip provisioning check
+        # In token exchange mode, tokens are exchanged per-request (no stored refresh tokens)
+        from nextcloud_mcp_server.config import get_settings
+
+        settings = get_settings()
+        if hasattr(lifespan_ctx, "nextcloud_host") and settings.enable_token_exchange:
+            # Token exchange mode - per-request exchange, no provisioning needed
+            logger.debug("Token exchange mode detected - skipping provisioning check")
+            return await func(*args, **kwargs)
+
+        # Offline access mode - check if user has completed Flow 2 provisioning
+        # Get user_id from authorization token
+        user_id = None
+        if hasattr(ctx, "authorization") and ctx.authorization:
+            try:
+                import jwt
+
+                token = ctx.authorization.token
+                payload = jwt.decode(token, options={"verify_signature": False})
+                user_id = payload.get("sub")
+                logger.debug(f"Checking provisioning for user: {user_id}")
+            except Exception as e:
+                logger.warning(f"Failed to extract user_id from token: {e}")
+
+        if not user_id:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message="Cannot determine user identity for provisioning check",
+                )
+            )
+
+        # Check provisioning status
+        storage = RefreshTokenStorage.from_env()
+        await storage.initialize()
+
+        refresh_data = await storage.get_refresh_token(user_id)
+
+        if not refresh_data:
+            # User has not completed Flow 2 - provide helpful error
+            logger.info(
+                f"User {user_id} attempted to use Nextcloud tool without provisioning"
+            )
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=(
+                        "Nextcloud access not provisioned. "
+                        "Please run the 'provision_nextcloud_access' tool first to authorize "
+                        "the MCP server to access Nextcloud on your behalf. "
+                        "This is a one-time setup required for security."
+                    ),
+                )
+            )
+
+        logger.debug(
+            f"User {user_id} has provisioned access - proceeding with tool execution"
+        )
+
+        # User has provisioned - allow access
+        return await func(*args, **kwargs)
+
+    return wrapper
+
+
+def require_provisioning_or_suggest(func: Callable) -> Callable:
+    """
+    Softer version that suggests provisioning but doesn't block.
+
+    This decorator:
+    1. Checks provisioning status
+    2. Logs a warning if not provisioned
+    3. Still allows the function to proceed
+    4. Can be used for read-only operations that might work without explicit provisioning
+
+    Usage:
+        @mcp.tool()
+        @require_provisioning_or_suggest
+        async def list_tools(ctx: Context):
+            # Tool implementation
+            pass
+    """
+
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        # Extract context from arguments
+        ctx = None
+        for arg in args:
+            if isinstance(arg, Context):
+                ctx = arg
+                break
+        if not ctx:
+            ctx = kwargs.get("ctx")
+
+        if ctx:
+            # Try to check provisioning status
+            try:
+                # Get user_id from authorization token
+                user_id = None
+                if hasattr(ctx, "authorization") and ctx.authorization:
+                    import jwt
+
+                    token = ctx.authorization.token
+                    payload = jwt.decode(token, options={"verify_signature": False})
+                    user_id = payload.get("sub")
+
+                if user_id:
+                    # Check provisioning status
+                    storage = RefreshTokenStorage.from_env()
+                    await storage.initialize()
+
+                    refresh_data = await storage.get_refresh_token(user_id)
+
+                    if not refresh_data:
+                        logger.info(
+                            f"User {user_id} has not provisioned Nextcloud access. "
+                            "Some features may not work. Consider running "
+                            "'provision_nextcloud_access' tool."
+                        )
+                    else:
+                        logger.debug(f"User {user_id} has provisioned access")
+
+            except Exception as e:
+                logger.debug(f"Could not check provisioning status: {e}")
+
+        # Always proceed with the function
+        return await func(*args, **kwargs)
+
+    return wrapper

nextcloud_mcp_server/auth/scope_authorization.py

@@ -0,0 +1,416 @@
+"""Scope-based authorization for MCP tools."""
+
+import logging
+import os
+from functools import wraps
+from typing import Any, 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)}"
+        )
+
+
+class ProvisioningRequiredError(ScopeAuthorizationError):
+    """Raised when Nextcloud resource access requires provisioning (Flow 2).
+
+    In Progressive Consent mode, users must explicitly provision Nextcloud
+    access using the provision_nextcloud_access MCP tool.
+    """
+
+    def __init__(self, message: str | None = None):
+        super().__init__(
+            message
+            or (
+                "Nextcloud resource access not provisioned. "
+                "Please run the 'provision_nextcloud_access' tool to grant access."
+            )
+        )
+
+
+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) -> Callable:
+        # Store scope requirements as function metadata for dynamic filtering
+        func._required_scopes = list(required_scopes)  # type: ignore[attr-defined]
+
+        # Get function name for logging (works for any callable)
+        func_name = getattr(func, "__name__", repr(func))
+
+        # Find which parameter receives the Context (FastMCP injects it by name)
+        context_param_name = find_context_parameter(func)
+
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # 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 offline access is enabled
+            enable_offline_access = (
+                os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
+            )
+
+            # In offline access mode, check if Nextcloud scopes require provisioning
+            if enable_offline_access:
+                # Check if any required scopes are Nextcloud-specific
+                nextcloud_scopes = [
+                    s
+                    for s in required_scopes
+                    if any(
+                        s.startswith(prefix)
+                        for prefix in [
+                            "notes:",
+                            "calendar:",
+                            "contacts:",
+                            "files:",
+                            "tables:",
+                            "deck:",
+                        ]
+                    )
+                ]
+
+                if nextcloud_scopes:
+                    # Check if user has completed Flow 2 provisioning
+                    # This would be indicated by having a stored refresh token
+                    # In production, we'd check the token broker or storage
+                    # For now, we check if the token has the required scopes
+                    # (Flow 1 tokens won't have Nextcloud scopes)
+                    has_nextcloud_scopes = any(
+                        s.startswith(prefix)
+                        for s in token_scopes
+                        for prefix in [
+                            "notes:",
+                            "calendar:",
+                            "contacts:",
+                            "files:",
+                            "tables:",
+                            "deck:",
+                        ]
+                    )
+
+                    if not has_nextcloud_scopes:
+                        error_msg = (
+                            f"Access denied to {func_name}: "
+                            f"Nextcloud resource access not provisioned. "
+                            f"Please run the 'provision_nextcloud_access' tool first."
+                        )
+                        logger.warning(error_msg)
+                        raise ProvisioningRequiredError(error_msg)
+
+            # 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/session_backend.py

@@ -0,0 +1,96 @@
+"""Session-based authentication backend for Starlette routes.
+
+Provides browser-based authentication for admin UI routes, separate from
+MCP's OAuth authentication flow.
+"""
+
+import logging
+import os
+
+from starlette.authentication import (
+    AuthCredentials,
+    AuthenticationBackend,
+    SimpleUser,
+)
+from starlette.requests import HTTPConnection
+
+logger = logging.getLogger(__name__)
+
+
+class SessionAuthBackend(AuthenticationBackend):
+    """Authentication backend using signed session cookies.
+
+    For BasicAuth mode: Always authenticates as the configured user.
+    For OAuth mode: Checks for valid session cookie with stored refresh token.
+    """
+
+    def __init__(self, oauth_enabled: bool = False):
+        """Initialize session authentication backend.
+
+        Args:
+            oauth_enabled: Whether OAuth mode is enabled
+        """
+        self.oauth_enabled = oauth_enabled
+
+    async def authenticate(
+        self, conn: HTTPConnection
+    ) -> tuple[AuthCredentials, SimpleUser] | None:
+        """Authenticate the request based on session cookie or BasicAuth mode.
+
+        This backend is only applied to browser routes (/user/*) via a separate
+        Starlette app mount. FastMCP routes use their own OAuth Bearer token
+        authentication.
+
+        Args:
+            conn: HTTP connection
+
+        Returns:
+            Tuple of (credentials, user) if authenticated, None otherwise
+        """
+        # BasicAuth mode: Always authenticated as the configured user
+        if not self.oauth_enabled:
+            username = os.getenv("NEXTCLOUD_USERNAME", "admin")
+            return AuthCredentials(["authenticated", "admin"]), SimpleUser(username)
+
+        # OAuth mode: Check for session cookie
+        session_id = conn.cookies.get("mcp_session")
+        logger.info(
+            f"Session authentication check - cookie present: {session_id is not None}, path: {conn.url.path}"
+        )
+        if not session_id:
+            logger.info("No session cookie found - redirecting to login")
+            return None
+
+        logger.info(f"Found session cookie: {session_id[:16]}...")
+
+        # Get OAuth context from app state
+        oauth_context = getattr(conn.app.state, "oauth_context", None)
+        if not oauth_context:
+            logger.warning("OAuth context not available in app state")
+            return None
+
+        # Validate session
+        storage = oauth_context.get("storage")
+        if not storage:
+            logger.warning("OAuth storage not available")
+            return None
+
+        try:
+            # Check if user has refresh token (indicates logged-in session)
+            logger.info(f"Looking up refresh token for session: {session_id[:16]}...")
+            token_data = await storage.get_refresh_token(session_id)
+            if not token_data:
+                logger.warning(
+                    f"No refresh token found for session {session_id[:16]}..."
+                )
+                return None
+
+            # Session is valid - use session_id (which is user_id from ID token) as username
+            username = session_id
+            logger.info(f"✓ Session authenticated successfully: {username[:16]}...")
+
+            return AuthCredentials(["authenticated"]), SimpleUser(username)
+
+        except Exception as e:
+            logger.warning(f"Session validation error: {e}")
+            return None

nextcloud_mcp_server/auth/token_broker.py

@@ -0,0 +1,588 @@
+"""
+Token Broker Service for ADR-004 Progressive Consent Architecture.
+
+This service manages the lifecycle of Nextcloud access tokens, implementing
+the dual OAuth flow pattern where:
+1. MCP clients authenticate to MCP server with aud:"mcp-server" tokens
+2. MCP server uses stored refresh tokens to obtain aud:"nextcloud" tokens
+
+The Token Broker provides:
+- Automatic token refresh when expired
+- Short-lived token caching (5-minute TTL)
+- Master refresh token rotation
+- Audience-specific token validation
+- Session vs background token separation (RFC 8693)
+"""
+
+import asyncio
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Dict, Optional, Tuple
+
+import httpx
+import jwt
+from cryptography.fernet import Fernet
+
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+from nextcloud_mcp_server.auth.token_exchange import exchange_token_for_delegation
+
+logger = logging.getLogger(__name__)
+
+
+class TokenCache:
+    """In-memory cache for short-lived Nextcloud access tokens."""
+
+    def __init__(self, ttl_seconds: int = 300, early_refresh_seconds: int = 30):
+        """
+        Initialize the token cache.
+
+        Args:
+            ttl_seconds: Default TTL for cached tokens (5 minutes default)
+            early_refresh_seconds: How many seconds before expiry to trigger early refresh (30s default)
+        """
+        self._cache: Dict[str, Tuple[str, datetime]] = {}
+        self._ttl = timedelta(seconds=ttl_seconds)
+        self._early_refresh = timedelta(seconds=early_refresh_seconds)
+        self._lock = asyncio.Lock()
+
+    async def get(self, user_id: str) -> Optional[str]:
+        """Get cached token if valid."""
+        async with self._lock:
+            if user_id not in self._cache:
+                return None
+
+            token, expiry = self._cache[user_id]
+            now = datetime.now(timezone.utc)
+
+            # Check if token has expired
+            if now >= expiry:
+                del self._cache[user_id]
+                logger.debug(f"Cached token expired for user {user_id}")
+                return None
+
+            # Check if token will expire soon (refresh early)
+            if now >= expiry - self._early_refresh:
+                logger.debug(f"Cached token expiring soon for user {user_id}")
+                return None
+
+            logger.debug(f"Using cached token for user {user_id}")
+            return token
+
+    async def set(self, user_id: str, token: str, expires_in: int | None = None):
+        """Store token in cache."""
+        async with self._lock:
+            # Use provided expiry or default TTL
+            if expires_in:
+                expiry = datetime.now(timezone.utc) + timedelta(seconds=expires_in)
+            else:
+                expiry = datetime.now(timezone.utc) + self._ttl
+
+            self._cache[user_id] = (token, expiry)
+            logger.debug(f"Cached token for user {user_id} until {expiry}")
+
+    async def invalidate(self, user_id: str):
+        """Remove token from cache."""
+        async with self._lock:
+            if user_id in self._cache:
+                del self._cache[user_id]
+                logger.debug(f"Invalidated cached token for user {user_id}")
+
+
+class TokenBrokerService:
+    """
+    Manages token lifecycle for the Progressive Consent architecture.
+
+    This service handles:
+    - Getting or refreshing Nextcloud access tokens
+    - Managing a short-lived token cache
+    - Refreshing master refresh tokens periodically
+    - Validating token audiences
+    """
+
+    def __init__(
+        self,
+        storage: RefreshTokenStorage,
+        oidc_discovery_url: str,
+        nextcloud_host: str,
+        encryption_key: str,
+        cache_ttl: int = 300,
+        cache_early_refresh: int = 30,
+    ):
+        """
+        Initialize the Token Broker Service.
+
+        Args:
+            storage: Database storage for refresh tokens
+            oidc_discovery_url: OIDC provider discovery URL
+            nextcloud_host: Nextcloud server URL
+            encryption_key: Fernet key for token encryption
+            cache_ttl: Cache TTL in seconds (default: 5 minutes)
+            cache_early_refresh: Early refresh threshold in seconds (default: 30 seconds)
+        """
+        self.storage = storage
+        self.oidc_discovery_url = oidc_discovery_url
+        self.nextcloud_host = nextcloud_host
+        self.fernet = Fernet(
+            encryption_key.encode()
+            if isinstance(encryption_key, str)
+            else encryption_key
+        )
+        self.cache = TokenCache(cache_ttl, cache_early_refresh)
+        self._oidc_config = None
+        self._http_client = None
+
+    async def _get_http_client(self) -> httpx.AsyncClient:
+        """Get or create HTTP client."""
+        if self._http_client is None:
+            self._http_client = httpx.AsyncClient(
+                timeout=httpx.Timeout(30.0), follow_redirects=True
+            )
+        return self._http_client
+
+    async def _get_oidc_config(self) -> dict:
+        """Get OIDC configuration from discovery endpoint."""
+        if self._oidc_config is None:
+            client = await self._get_http_client()
+            response = await client.get(self.oidc_discovery_url)
+            response.raise_for_status()
+            self._oidc_config = response.json()
+        return self._oidc_config
+
+    async def get_nextcloud_token(self, user_id: str) -> Optional[str]:
+        """
+        Get a valid Nextcloud access token for the user.
+
+        DEPRECATED: This method uses the old pattern of stored refresh tokens
+        for all operations. Use get_session_token() or get_background_token()
+        instead for proper session/background separation.
+
+        This method:
+        1. Checks the cache for a valid token
+        2. If not cached, checks for stored refresh token
+        3. If refresh token exists, obtains new access token
+        4. Caches the new token for future requests
+
+        Args:
+            user_id: The user identifier
+
+        Returns:
+            Valid Nextcloud access token or None if not provisioned
+        """
+        # Check cache first
+        cached_token = await self.cache.get(user_id)
+        if cached_token:
+            return cached_token
+
+        # Get stored refresh token
+        refresh_data = await self.storage.get_refresh_token(user_id)
+        if not refresh_data:
+            logger.info(f"No refresh token found for user {user_id}")
+            return None
+
+        try:
+            # Decrypt refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()
+
+            # Exchange refresh token for new access token
+            access_token, expires_in = await self._refresh_access_token(refresh_token)
+
+            # Cache the new token
+            await self.cache.set(user_id, access_token, expires_in)
+
+            return access_token
+
+        except Exception as e:
+            logger.error(f"Failed to get Nextcloud token for user {user_id}: {e}")
+            # Invalidate cache on error
+            await self.cache.invalidate(user_id)
+            return None
+
+    async def get_session_token(
+        self,
+        flow1_token: str,
+        required_scopes: list[str],
+        requested_audience: str = "nextcloud",
+    ) -> Optional[str]:
+        """
+        Get ephemeral token for MCP session operations (on-demand).
+
+        This implements the correct Progressive Consent pattern where:
+        1. Client provides Flow 1 token (aud: "mcp-server")
+        2. Server exchanges it for ephemeral Nextcloud token
+        3. Token is NOT stored, only used for current operation
+
+        Key properties:
+        - On-demand generation during tool execution
+        - Ephemeral (not stored, discarded after use)
+        - Limited scopes (only what tool needs)
+        - Short-lived (5 minutes)
+
+        Args:
+            flow1_token: The MCP session token (aud: "mcp-server")
+            required_scopes: Minimal scopes needed for this operation
+            requested_audience: Target audience (usually "nextcloud")
+
+        Returns:
+            Ephemeral Nextcloud access token or None if exchange fails
+        """
+        try:
+            # Perform RFC 8693 token exchange
+            delegated_token, expires_in = await exchange_token_for_delegation(
+                flow1_token=flow1_token,
+                requested_scopes=required_scopes,
+                requested_audience=requested_audience,
+            )
+
+            # NOTE: We intentionally do NOT cache session tokens
+            # They are ephemeral and should be discarded after use
+            logger.info(
+                f"Generated ephemeral session token with scopes: {required_scopes}, "
+                f"expires in {expires_in}s"
+            )
+
+            return delegated_token
+
+        except Exception as e:
+            logger.error(f"Failed to get session token: {e}")
+            return None
+
+    async def get_background_token(
+        self, user_id: str, required_scopes: list[str]
+    ) -> Optional[str]:
+        """
+        Get token for background job operations (uses stored refresh token).
+
+        This is for background/offline operations that run without user interaction.
+        Uses the stored refresh token from Flow 2 provisioning.
+
+        Key properties:
+        - Uses stored refresh token from Flow 2
+        - Different scopes than session tokens
+        - Longer-lived for background operations
+        - Can be cached for efficiency
+
+        Args:
+            user_id: The user identifier
+            required_scopes: Scopes needed for background operation
+
+        Returns:
+            Nextcloud access token for background operations or None if not provisioned
+        """
+        # Check cache first (background tokens can be cached)
+        cache_key = f"{user_id}:background:{','.join(sorted(required_scopes))}"
+        cached_token = await self.cache.get(cache_key)
+        if cached_token:
+            return cached_token
+
+        # Get stored refresh token
+        refresh_data = await self.storage.get_refresh_token(user_id)
+        if not refresh_data:
+            logger.info(f"No refresh token found for user {user_id}")
+            return None
+
+        try:
+            # Decrypt refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()
+
+            # Get token with specific scopes for background operation
+            access_token, expires_in = await self._refresh_access_token_with_scopes(
+                refresh_token, required_scopes
+            )
+
+            # Cache the background token
+            await self.cache.set(cache_key, access_token, expires_in)
+
+            logger.info(
+                f"Generated background token for user {user_id} with scopes: {required_scopes}"
+            )
+
+            return access_token
+
+        except Exception as e:
+            logger.error(f"Failed to get background token for user {user_id}: {e}")
+            await self.cache.invalidate(cache_key)
+            return None
+
+    async def _refresh_access_token(self, refresh_token: str) -> Tuple[str, int]:
+        """
+        Exchange refresh token for new access token.
+
+        DEPRECATED: Use _refresh_access_token_with_scopes() for scope-specific requests.
+
+        Args:
+            refresh_token: The refresh token
+
+        Returns:
+            Tuple of (access_token, expires_in_seconds)
+        """
+        config = await self._get_oidc_config()
+        token_endpoint = config["token_endpoint"]
+
+        client = await self._get_http_client()
+
+        # Request new access token using refresh token
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "scope": "openid profile email notes:read notes:write calendar:read calendar:write",
+        }
+
+        response = await client.post(
+            token_endpoint,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+
+        if response.status_code != 200:
+            logger.error(
+                f"Token refresh failed: {response.status_code} - {response.text}"
+            )
+            raise Exception(f"Token refresh failed: {response.status_code}")
+
+        token_data = response.json()
+        access_token = token_data["access_token"]
+        expires_in = token_data.get("expires_in", 3600)  # Default 1 hour
+
+        # Validate audience
+        await self._validate_token_audience(access_token, "nextcloud")
+
+        logger.info(f"Refreshed access token (expires in {expires_in}s)")
+        return access_token, expires_in
+
+    async def _refresh_access_token_with_scopes(
+        self, refresh_token: str, required_scopes: list[str]
+    ) -> Tuple[str, int]:
+        """
+        Exchange refresh token for new access token with specific scopes.
+
+        This method implements scope downscoping for least privilege.
+
+        Args:
+            refresh_token: The refresh token
+            required_scopes: Minimal scopes needed for this operation
+
+        Returns:
+            Tuple of (access_token, expires_in_seconds)
+        """
+        config = await self._get_oidc_config()
+        token_endpoint = config["token_endpoint"]
+
+        client = await self._get_http_client()
+
+        # Always include basic OpenID scopes
+        scopes = list(set(["openid", "profile", "email"] + required_scopes))
+
+        # Request new access token with specific scopes
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "scope": " ".join(scopes),
+        }
+
+        response = await client.post(
+            token_endpoint,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+
+        if response.status_code != 200:
+            logger.error(
+                f"Token refresh with scopes failed: {response.status_code} - {response.text}"
+            )
+            raise Exception(f"Token refresh failed: {response.status_code}")
+
+        token_data = response.json()
+        access_token = token_data["access_token"]
+        expires_in = token_data.get("expires_in", 3600)  # Default 1 hour
+
+        # Validate audience
+        await self._validate_token_audience(access_token, "nextcloud")
+
+        logger.info(
+            f"Refreshed access token with scopes {scopes} (expires in {expires_in}s)"
+        )
+        return access_token, expires_in
+
+    async def _validate_token_audience(self, token: str, expected_audience: str):
+        """
+        Validate that token has correct audience claim.
+
+        Args:
+            token: JWT token to validate
+            expected_audience: Expected audience value
+
+        Raises:
+            ValueError: If audience doesn't match
+        """
+        try:
+            # Decode without verification to check claims
+            # In production, should verify signature
+            claims = jwt.decode(token, options={"verify_signature": False})
+
+            audience = claims.get("aud", [])
+            if isinstance(audience, str):
+                audience = [audience]
+
+            if expected_audience not in audience:
+                raise ValueError(
+                    f"Token audience {audience} doesn't include {expected_audience}"
+                )
+
+        except jwt.DecodeError as e:
+            # Token might be opaque, skip validation
+            logger.debug(f"Cannot decode token for audience validation: {e}")
+
+    async def refresh_master_token(self, user_id: str) -> bool:
+        """
+        Refresh the master refresh token (periodic rotation).
+
+        This should be called periodically (e.g., daily) to rotate
+        refresh tokens for security.
+
+        Args:
+            user_id: The user identifier
+
+        Returns:
+            True if refresh successful, False otherwise
+        """
+        refresh_data = await self.storage.get_refresh_token(user_id)
+        if not refresh_data:
+            logger.warning(f"No refresh token to rotate for user {user_id}")
+            return False
+
+        try:
+            # Decrypt current refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            current_refresh_token = self.fernet.decrypt(
+                encrypted_token.encode()
+            ).decode()
+
+            # Get OIDC configuration
+            config = await self._get_oidc_config()
+            token_endpoint = config["token_endpoint"]
+
+            client = await self._get_http_client()
+
+            # Request new refresh token
+            data = {
+                "grant_type": "refresh_token",
+                "refresh_token": current_refresh_token,
+                "scope": "openid profile email offline_access notes:read notes:write calendar:read calendar:write",
+            }
+
+            response = await client.post(
+                token_endpoint,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            if response.status_code != 200:
+                logger.error(f"Master token refresh failed: {response.status_code}")
+                return False
+
+            token_data = response.json()
+            new_refresh_token = token_data.get("refresh_token")
+
+            if new_refresh_token and new_refresh_token != current_refresh_token:
+                # Encrypt and store new refresh token
+                encrypted_new = self.fernet.encrypt(new_refresh_token.encode()).decode()
+                await self.storage.store_refresh_token(
+                    user_id=user_id,
+                    refresh_token=encrypted_new,
+                    expires_at=datetime.now(timezone.utc)
+                    + timedelta(days=90),  # 90-day expiry
+                )
+                logger.info(f"Rotated master refresh token for user {user_id}")
+
+                # Invalidate cached access token
+                await self.cache.invalidate(user_id)
+                return True
+
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to refresh master token for user {user_id}: {e}")
+            return False
+
+    async def has_nextcloud_provisioning(self, user_id: str) -> bool:
+        """
+        Check if user has provisioned Nextcloud access (Flow 2).
+
+        Args:
+            user_id: The user identifier
+
+        Returns:
+            True if user has stored refresh token, False otherwise
+        """
+        refresh_data = await self.storage.get_refresh_token(user_id)
+        return refresh_data is not None
+
+    async def revoke_nextcloud_access(self, user_id: str) -> bool:
+        """
+        Revoke stored Nextcloud access for a user.
+
+        This removes stored refresh tokens and clears cache.
+
+        Args:
+            user_id: The user identifier
+
+        Returns:
+            True if revocation successful
+        """
+        try:
+            # Get refresh token for revocation at IdP
+            refresh_data = await self.storage.get_refresh_token(user_id)
+            if refresh_data:
+                try:
+                    # Attempt to revoke at IdP
+                    encrypted_token = refresh_data["refresh_token"]
+                    refresh_token = self.fernet.decrypt(
+                        encrypted_token.encode()
+                    ).decode()
+                    await self._revoke_token_at_idp(refresh_token)
+                except Exception as e:
+                    logger.warning(f"Failed to revoke at IdP: {e}")
+
+            # Remove from storage
+            await self.storage.delete_refresh_token(user_id)
+
+            # Clear cache
+            await self.cache.invalidate(user_id)
+
+            logger.info(f"Revoked Nextcloud access for user {user_id}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to revoke access for user {user_id}: {e}")
+            return False
+
+    async def _revoke_token_at_idp(self, token: str):
+        """Revoke token at the IdP if revocation endpoint exists."""
+        config = await self._get_oidc_config()
+        revocation_endpoint = config.get("revocation_endpoint")
+
+        if not revocation_endpoint:
+            logger.debug("No revocation endpoint available")
+            return
+
+        client = await self._get_http_client()
+
+        data = {"token": token, "token_type_hint": "refresh_token"}
+
+        response = await client.post(
+            revocation_endpoint,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+
+        if response.status_code == 200:
+            logger.info("Token revoked at IdP")
+        else:
+            logger.warning(f"Token revocation returned {response.status_code}")
+
+    async def close(self):
+        """Clean up resources."""
+        if self._http_client:
+            await self._http_client.aclose()

nextcloud_mcp_server/auth/token_exchange.py

@@ -0,0 +1,595 @@
+"""RFC 8693 Token Exchange implementation for ADR-004 Progressive Consent.
+
+This module implements the token exchange pattern to convert Flow 1 MCP tokens
+(aud: "mcp-server") into ephemeral delegated Nextcloud tokens (aud: "nextcloud")
+for session operations.
+
+Key Properties:
+- On-demand generation during tool execution
+- Ephemeral tokens (NOT stored, discarded after use)
+- Limited scopes (only what tool needs)
+- Short-lived (5 minutes default)
+"""
+
+import logging
+import time
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import urljoin
+
+import httpx
+import jwt
+
+from ..config import get_settings
+from .storage import RefreshTokenStorage
+
+logger = logging.getLogger(__name__)
+
+
+class TokenExchangeService:
+    """Implements RFC 8693 OAuth 2.0 Token Exchange."""
+
+    # RFC 8693 Grant Type
+    TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange"
+
+    # RFC 8693 Token Type Identifiers
+    TOKEN_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token"
+    TOKEN_TYPE_JWT = "urn:ietf:params:oauth:token-type:jwt"
+    TOKEN_TYPE_ID_TOKEN = "urn:ietf:params:oauth:token-type:id_token"
+
+    def __init__(
+        self,
+        oidc_discovery_url: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        nextcloud_host: Optional[str] = None,
+    ):
+        """Initialize token exchange service.
+
+        Args:
+            oidc_discovery_url: OIDC discovery endpoint URL
+            client_id: OAuth client ID for token exchange
+            client_secret: OAuth client secret
+            nextcloud_host: Nextcloud instance URL
+        """
+        settings = get_settings()
+        self.oidc_discovery_url = oidc_discovery_url or settings.oidc_discovery_url
+        self.client_id = client_id or settings.oidc_client_id
+        self.client_secret = client_secret or settings.oidc_client_secret
+        self.nextcloud_host = nextcloud_host or settings.nextcloud_host
+
+        self._token_endpoint: Optional[str] = None
+        self._jwks_uri: Optional[str] = None
+        self._discovery_cache: Optional[Dict[str, Any]] = None
+        self._discovery_cache_time: float = 0
+        self._discovery_cache_ttl: float = 3600  # 1 hour
+
+        # Storage for Progressive Consent (refresh tokens) - only needed for delegation
+        # NOT needed for pure RFC 8693 exchange (MCP tools)
+        self.storage: Optional[RefreshTokenStorage] = None
+
+        # Create HTTP client
+        self.http_client = httpx.AsyncClient(
+            timeout=30.0,
+            follow_redirects=True,
+        )
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        if self.storage:
+            await self.storage.initialize()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+
+    async def close(self):
+        """Close HTTP client and storage."""
+        await self.http_client.aclose()
+        # RefreshTokenStorage doesn't have a close method
+
+    async def _ensure_storage(self):
+        """Lazily initialize storage for Progressive Consent operations.
+
+        Only needed for delegation operations that use refresh tokens.
+        NOT needed for pure RFC 8693 exchange (MCP tools).
+        """
+        if self.storage is None:
+            self.storage = RefreshTokenStorage.from_env()
+            await self.storage.initialize()
+
+    async def _discover_endpoints(self) -> Dict[str, Any]:
+        """Discover OIDC endpoints from discovery URL.
+
+        Returns:
+            Discovery document containing endpoint URLs
+        """
+        # Check cache
+        if (
+            self._discovery_cache
+            and (time.time() - self._discovery_cache_time) < self._discovery_cache_ttl
+        ):
+            return self._discovery_cache
+
+        if not self.oidc_discovery_url:
+            # Fallback to Nextcloud OIDC if no discovery URL
+            self.oidc_discovery_url = urljoin(
+                self.nextcloud_host,  # type: ignore[arg-type]
+                "/.well-known/openid-configuration",
+            )
+
+        try:
+            response = await self.http_client.get(self.oidc_discovery_url)
+            response.raise_for_status()
+
+            self._discovery_cache = response.json()
+            self._discovery_cache_time = time.time()
+
+            # Cache frequently used endpoints
+            self._token_endpoint = self._discovery_cache.get("token_endpoint")
+            self._jwks_uri = self._discovery_cache.get("jwks_uri")
+
+            return self._discovery_cache
+
+        except Exception as e:
+            logger.error(f"Failed to discover OIDC endpoints: {e}")
+            raise
+
+    async def exchange_token_for_delegation(
+        self,
+        flow1_token: str,
+        requested_scopes: list[str],
+        requested_audience: str = "nextcloud",
+    ) -> Tuple[str, int]:
+        """Exchange Flow 1 MCP token for delegated Nextcloud token.
+
+        This implements RFC 8693 Token Exchange for on-behalf-of delegation.
+
+        Args:
+            flow1_token: The MCP session token (aud: "mcp-server")
+            requested_scopes: Scopes needed for this operation
+            requested_audience: Target audience (usually "nextcloud")
+
+        Returns:
+            Tuple of (delegated_token, expires_in)
+
+        Raises:
+            ValueError: If token validation fails
+            RuntimeError: If provisioning not completed or exchange fails
+        """
+        # 1. Validate Flow 1 token audience
+        await self._validate_flow1_token(flow1_token)
+
+        # 2. Extract user ID from token
+        user_id = self._extract_user_id(flow1_token)
+
+        # 3. Check user has provisioned Nextcloud access (Flow 2)
+        if not await self._check_provisioning(user_id):
+            raise RuntimeError(
+                "Nextcloud access not provisioned. "
+                "User must complete Flow 2 provisioning first."
+            )
+
+        # 4. Get stored refresh token for user (from Flow 2)
+        refresh_token = await self._get_user_refresh_token(user_id)
+        if not refresh_token:
+            raise RuntimeError(
+                "No refresh token found. User must complete provisioning."
+            )
+
+        # 5. Perform token exchange with IdP
+        delegated_token, expires_in = await self._perform_token_exchange(
+            subject_token=flow1_token,
+            refresh_token=refresh_token,
+            requested_scopes=requested_scopes,
+            requested_audience=requested_audience,
+        )
+
+        # 6. Log the exchange for audit trail
+        logger.info(
+            f"Token exchange completed for user {user_id}: "
+            f"scopes={requested_scopes}, audience={requested_audience}, "
+            f"expires_in={expires_in}s"
+        )
+
+        return delegated_token, expires_in
+
+    async def exchange_token_for_audience(
+        self,
+        subject_token: str,
+        requested_audience: str = "nextcloud",
+        requested_scopes: list[str] | None = None,
+    ) -> Tuple[str, int]:
+        """
+        Pure RFC 8693 token exchange (no refresh tokens required).
+
+        This implements stateless per-request token exchange where:
+        1. Client token has aud: <client-id> (e.g., "nextcloud-mcp-server")
+        2. Exchange for token with aud: "nextcloud" (for API access)
+        3. NO refresh tokens or provisioning required
+
+        Use case: All MCP tool calls (request-time operations).
+        NOT for background jobs (which use refresh tokens separately).
+
+        Args:
+            subject_token: Token being exchanged (from MCP client)
+            requested_audience: Target audience (usually "nextcloud")
+            requested_scopes: Optional scopes (may not be supported by all IdPs)
+
+        Returns:
+            Tuple of (access_token, expires_in)
+
+        Raises:
+            ValueError: If token validation fails
+            RuntimeError: If exchange fails
+        """
+        # 1. Validate subject token (accepts both "mcp-server" and client_id)
+        await self._validate_flow1_token(subject_token)
+
+        # 2. Extract user ID for logging
+        user_id = self._extract_user_id(subject_token)
+
+        # 3. Discover token endpoint
+        discovery = await self._discover_endpoints()
+        token_endpoint = discovery.get("token_endpoint")
+
+        if not token_endpoint:
+            raise RuntimeError("No token endpoint found in discovery")
+
+        # 4. Build pure RFC 8693 exchange request (subject_token ONLY)
+        data = {
+            "grant_type": self.TOKEN_EXCHANGE_GRANT,
+            "subject_token": subject_token,
+            "subject_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
+            "requested_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
+            "audience": requested_audience,
+        }
+
+        # Add scopes if provided (may not be supported by all providers)
+        if requested_scopes:
+            data["scope"] = " ".join(requested_scopes)
+
+        # Add client credentials
+        if self.client_id and self.client_secret:
+            data["client_id"] = self.client_id
+            data["client_secret"] = self.client_secret
+
+        try:
+            # Perform exchange
+            logger.debug(f"Exchanging token for audience={requested_audience}")
+            response = await self.http_client.post(
+                token_endpoint,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+            response.raise_for_status()
+            result = response.json()
+
+            access_token = result.get("access_token")
+            expires_in = result.get("expires_in", 300)
+
+            if not access_token:
+                raise RuntimeError("No access token in exchange response")
+
+            logger.info(
+                f"Pure RFC 8693 token exchange successful for user {user_id}: "
+                f"audience={requested_audience}, expires_in={expires_in}s"
+            )
+
+            return access_token, expires_in
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Token exchange failed: {e.response.text}")
+            raise RuntimeError(f"Token exchange failed: {e}")
+        except Exception as e:
+            logger.error(f"Token exchange error: {e}")
+            raise
+
+    async def _validate_flow1_token(self, token: str):
+        """Validate that token has correct audience for MCP server.
+
+        Accepts either:
+        - "mcp-server" (Progressive Consent legacy)
+        - self.client_id (external IdP, e.g., "nextcloud-mcp-server")
+
+        Args:
+            token: JWT token to validate
+
+        Raises:
+            ValueError: If token is invalid or has wrong audience
+        """
+        try:
+            # Decode without verification first to check audience
+            # In production, should verify signature against JWKS
+            payload = jwt.decode(token, options={"verify_signature": False})
+
+            # Check audience
+            audience = payload.get("aud", [])
+            if isinstance(audience, str):
+                audience = [audience]
+
+            # Accept either "mcp-server" (Progressive Consent) or client_id (external IdP)
+            valid_audiences = ["mcp-server"]
+            if self.client_id:
+                valid_audiences.append(self.client_id)
+
+            if not any(aud in audience for aud in valid_audiences):
+                raise ValueError(
+                    f"Invalid token audience. Expected one of {valid_audiences}, got {audience}"
+                )
+
+            # Check expiration
+            exp = payload.get("exp", 0)
+            if exp < time.time():
+                raise ValueError("Token has expired")
+
+        except jwt.DecodeError as e:
+            raise ValueError(f"Invalid JWT token: {e}")
+
+    def _extract_user_id(self, token: str) -> str:
+        """Extract user ID from JWT token.
+
+        Args:
+            token: JWT token
+
+        Returns:
+            User ID from token
+        """
+        try:
+            payload = jwt.decode(token, options={"verify_signature": False})
+
+            # Try standard claims in order of preference
+            user_id = (
+                payload.get("sub")
+                or payload.get("preferred_username")
+                or payload.get("email")
+                or payload.get("name")
+            )
+
+            if not user_id:
+                raise ValueError("No user identifier in token")
+
+            return user_id
+
+        except jwt.DecodeError as e:
+            raise ValueError(f"Failed to extract user ID: {e}")
+
+    async def _check_provisioning(self, user_id: str) -> bool:
+        """Check if user has completed Flow 2 provisioning.
+
+        Args:
+            user_id: User identifier
+
+        Returns:
+            True if provisioned, False otherwise
+        """
+        await self._ensure_storage()
+        assert self.storage is not None  # _ensure_storage() ensures this
+        token_data = await self.storage.get_refresh_token(user_id)
+        return token_data is not None
+
+    async def _get_user_refresh_token(self, user_id: str) -> Optional[str]:
+        """Get stored refresh token for user from Flow 2 provisioning.
+
+        Args:
+            user_id: User identifier
+
+        Returns:
+            Refresh token if found, None otherwise
+        """
+        await self._ensure_storage()
+        assert self.storage is not None  # _ensure_storage() ensures this
+        token_data = await self.storage.get_refresh_token(user_id)
+        if token_data:
+            return token_data.get("refresh_token")
+        return None
+
+    async def _perform_token_exchange(
+        self,
+        subject_token: str,
+        refresh_token: str,
+        requested_scopes: list[str],
+        requested_audience: str,
+    ) -> Tuple[str, int]:
+        """Perform RFC 8693 token exchange with IdP.
+
+        Args:
+            subject_token: The token being exchanged (Flow 1 token)
+            refresh_token: User's stored refresh token for delegation
+            requested_scopes: Minimal scopes for this operation
+            requested_audience: Target audience
+
+        Returns:
+            Tuple of (access_token, expires_in)
+        """
+        # Discover token endpoint
+        discovery = await self._discover_endpoints()
+        token_endpoint = discovery.get("token_endpoint")
+
+        if not token_endpoint:
+            raise RuntimeError("No token endpoint found in discovery")
+
+        # Build token exchange request per RFC 8693
+        data = {
+            # Token exchange grant type
+            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+            # The token we're exchanging (Flow 1 MCP token)
+            "subject_token": subject_token,
+            "subject_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
+            # Use refresh token as actor token (proves we have delegation rights)
+            "actor_token": refresh_token,
+            "actor_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
+            # Requested token properties
+            "requested_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
+            "audience": requested_audience,
+            "scope": " ".join(requested_scopes),
+        }
+
+        # Add client credentials if configured
+        if self.client_id and self.client_secret:
+            data["client_id"] = self.client_id
+            data["client_secret"] = self.client_secret
+
+        try:
+            # Attempt RFC 8693 token exchange
+            response = await self.http_client.post(
+                token_endpoint,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            if response.status_code == 400:
+                # Token exchange might not be supported, fall back to refresh grant
+                logger.info(
+                    "Token exchange not supported, falling back to refresh grant"
+                )
+                return await self._fallback_refresh_grant(
+                    refresh_token=refresh_token,
+                    requested_scopes=requested_scopes,
+                    token_endpoint=token_endpoint,
+                )
+
+            response.raise_for_status()
+            result = response.json()
+
+            access_token = result.get("access_token")
+            expires_in = result.get("expires_in", 300)  # Default 5 minutes
+
+            if not access_token:
+                raise RuntimeError("No access token in exchange response")
+
+            return access_token, expires_in
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Token exchange failed: {e.response.text}")
+            raise RuntimeError(f"Token exchange failed: {e}")
+        except Exception as e:
+            logger.error(f"Token exchange error: {e}")
+            raise
+
+    async def _fallback_refresh_grant(
+        self, refresh_token: str, requested_scopes: list[str], token_endpoint: str
+    ) -> Tuple[str, int]:
+        """Fallback to standard refresh token grant if token exchange not supported.
+
+        This is less secure than token exchange but provides compatibility.
+
+        Args:
+            refresh_token: User's stored refresh token
+            requested_scopes: Minimal scopes for this operation
+            token_endpoint: Token endpoint URL
+
+        Returns:
+            Tuple of (access_token, expires_in)
+        """
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "scope": " ".join(requested_scopes),  # Request minimal scopes
+        }
+
+        # Add client credentials if configured
+        if self.client_id and self.client_secret:
+            data["client_id"] = self.client_id
+            data["client_secret"] = self.client_secret
+
+        try:
+            response = await self.http_client.post(
+                token_endpoint,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+            response.raise_for_status()
+
+            result = response.json()
+
+            access_token = result.get("access_token")
+            expires_in = result.get("expires_in", 300)  # Default 5 minutes
+
+            if not access_token:
+                raise RuntimeError("No access token in refresh response")
+
+            # Log that we're using fallback
+            logger.warning(
+                f"Using refresh grant fallback for token exchange. "
+                f"Scopes: {requested_scopes}"
+            )
+
+            return access_token, expires_in
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Refresh grant failed: {e.response.text}")
+            raise RuntimeError(f"Refresh grant failed: {e}")
+        except Exception as e:
+            logger.error(f"Refresh grant error: {e}")
+            raise
+
+
+# Singleton instance
+_token_exchange_service: Optional[TokenExchangeService] = None
+
+
+async def get_token_exchange_service() -> TokenExchangeService:
+    """Get or create the singleton token exchange service.
+
+    Note: Storage is initialized lazily only when needed for delegation operations.
+    Pure RFC 8693 exchange (MCP tools) doesn't require storage.
+
+    Returns:
+        TokenExchangeService instance
+    """
+    global _token_exchange_service
+
+    if _token_exchange_service is None:
+        _token_exchange_service = TokenExchangeService()
+        # Storage is initialized lazily via _ensure_storage() when needed
+
+    return _token_exchange_service
+
+
+async def exchange_token_for_delegation(
+    flow1_token: str, requested_scopes: list[str], requested_audience: str = "nextcloud"
+) -> Tuple[str, int]:
+    """Convenience function to exchange tokens (Progressive Consent with refresh tokens).
+
+    NOTE: This is for background jobs only. For MCP tool calls, use exchange_token_for_audience().
+
+    Args:
+        flow1_token: The MCP session token (aud: "mcp-server")
+        requested_scopes: Scopes needed for this operation
+        requested_audience: Target audience (usually "nextcloud")
+
+    Returns:
+        Tuple of (delegated_token, expires_in)
+    """
+    service = await get_token_exchange_service()
+    return await service.exchange_token_for_delegation(
+        flow1_token=flow1_token,
+        requested_scopes=requested_scopes,
+        requested_audience=requested_audience,
+    )
+
+
+async def exchange_token_for_audience(
+    subject_token: str,
+    requested_audience: str = "nextcloud",
+    requested_scopes: list[str] | None = None,
+) -> Tuple[str, int]:
+    """Convenience function for pure RFC 8693 token exchange (no refresh tokens).
+
+    Use this for ALL MCP tool calls (request-time operations).
+
+    Args:
+        subject_token: Token being exchanged (from MCP client)
+        requested_audience: Target audience (usually "nextcloud")
+        requested_scopes: Optional scopes (may not be supported by all IdPs)
+
+    Returns:
+        Tuple of (access_token, expires_in)
+    """
+    service = await get_token_exchange_service()
+    return await service.exchange_token_for_audience(
+        subject_token=subject_token,
+        requested_audience=requested_audience,
+        requested_scopes=requested_scopes,
+    )