bump: version 0.57.60 → 0.57.61

docs: ADR-022 Deployment Mode Consolidation via Login Flow v2

.github/workflows/bump-version.yml

@@ -7,26 +7,158 @@ on:
 
 jobs:
   bump-version:
-    if: "!startsWith(github.event.head_commit.message, 'bump:')"
+    if: "!startsWith(github.event.head_commit.message, 'bump:') && !startsWith(github.event.head_commit.message, 'chore(release):')"
     runs-on: ubuntu-latest
-    name: "Bump version and create changelog with commitizen"
+    name: "Bump version and create changelog for monorepo components"
     permissions:
       contents: write
       packages: write
     steps:
       - name: Check out
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
-      - name: Create bump and changelog
-        uses: commitizen-tools/commitizen-action@bb4f1df6601e2a1a891506581b0c53acdc88e07d # 0.26.0
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
-          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-          changelog_increment_filename: body.md
-      - name: Release
-        uses: softprops/action-gh-release@5be0e66d93ac7ed76da52eca8bb058f665c3a5fe # v2.4.2
-        with:
-          body_path: "body.md"
-          tag_name: v${{ env.REVISION }}
-          token: ${{ secrets.GITHUB_TOKEN }}
+          python-version: '3.11'
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Detect and bump component versions
+        id: bump
+        run: |
+          set -euo pipefail
+
+          # Track which components were bumped
+          BUMPED_COMPONENTS=""
+
+          # Helper function to check for commits with specific scope since last tag
+          has_commits_since_tag() {
+            local tag_pattern="$1"
+            local scope_pattern="$2"
+
+            # Get the most recent tag matching the pattern
+            local last_tag=$(git tag --sort=-creatordate | grep -E "^${tag_pattern}" | head -n 1 || echo "")
+
+            if [ -z "$last_tag" ]; then
+              # No previous tag, check all commits on master
+              local commit_range="master"
+            else
+              # Check commits since last tag
+              local commit_range="${last_tag}..HEAD"
+            fi
+
+            # Count commits matching the scope pattern
+            local commit_count=$(git log "$commit_range" --oneline --grep="^${scope_pattern}" -E | wc -l)
+
+            if [ "$commit_count" -gt 0 ]; then
+              echo "Found $commit_count commits for scope '$scope_pattern' since $last_tag"
+              return 0
+            else
+              echo "No commits found for scope '$scope_pattern' since $last_tag"
+              return 1
+            fi
+          }
+
+          # Bump MCP server (default - all commits except helm scope)
+          echo "Checking MCP server for version bump..."
+
+          # Get the most recent MCP tag
+          last_mcp_tag=$(git tag --sort=-creatordate | grep -E "^v[0-9]" | head -n 1 || echo "")
+
+          if [ -z "$last_mcp_tag" ]; then
+            commit_range="master"
+          else
+            commit_range="${last_mcp_tag}..HEAD"
+          fi
+
+          # Count conventional commits that are NOT scoped to helm
+          mcp_commit_count=$(git log "$commit_range" --oneline --grep="^(feat|fix|docs|refactor|perf|test|build|ci|chore)" -E | \
+            { grep -v "(helm)" || true; } | wc -l)
+
+          MCP_BUMPED=false
+          if [ "$mcp_commit_count" -gt 0 ]; then
+            echo "Found $mcp_commit_count commits for MCP server since $last_mcp_tag"
+            echo "Bumping MCP server version..."
+            ./scripts/bump-mcp.sh
+            BUMPED_COMPONENTS="$BUMPED_COMPONENTS mcp"
+            MCP_BUMPED=true
+          else
+            echo "No commits found for MCP server since $last_mcp_tag"
+          fi
+
+          # Bump Helm chart (scope: helm OR when MCP appVersion changes)
+          echo "Checking Helm chart for version bump..."
+          HELM_HAS_COMMITS=false
+          if has_commits_since_tag "nextcloud-mcp-server-" "(feat|fix|docs|refactor|perf|test|build|ci|chore)\(helm\)(!)?:"; then
+            HELM_HAS_COMMITS=true
+          fi
+
+          if [ "$HELM_HAS_COMMITS" = true ]; then
+            echo "Bumping Helm chart version (helm-scoped commits)..."
+            ./scripts/bump-helm.sh
+            BUMPED_COMPONENTS="$BUMPED_COMPONENTS helm"
+          elif [ "$MCP_BUMPED" = true ]; then
+            echo "Bumping Helm chart version (appVersion changed)..."
+            ./scripts/bump-helm.sh --increment PATCH
+            BUMPED_COMPONENTS="$BUMPED_COMPONENTS helm"
+          fi
+
+          # Output summary
+          if [ -z "$BUMPED_COMPONENTS" ]; then
+            echo "No components required version bumps"
+            echo "bumped=false" >> $GITHUB_OUTPUT
+          else
+            echo "Bumped components:$BUMPED_COMPONENTS"
+            echo "bumped=true" >> $GITHUB_OUTPUT
+            echo "components=$BUMPED_COMPONENTS" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Push tags
+        if: steps.bump.outputs.bumped == 'true'
+        run: |
+          git push
+          git push --tags
+          echo "Pushed tags for components:${{ steps.bump.outputs.components }}"
+
+      - name: Summary
+        run: |
+          if [ "${{ steps.bump.outputs.bumped }}" == "true" ]; then
+            echo "## Version Bump Summary" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "The following components were bumped:" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+
+            for component in ${{ steps.bump.outputs.components }}; do
+              case $component in
+                mcp)
+                  tag=$(git tag --sort=-creatordate | grep -E '^v[0-9]' | head -n 1)
+                  echo "- **MCP Server**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
+                  ;;
+                helm)
+                  tag=$(git tag --sort=-creatordate | grep -E '^nextcloud-mcp-server-' | head -n 1)
+                  echo "- **Helm Chart**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
+                  ;;
+              esac
+            done
+
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "Tags have been pushed and release workflows will trigger automatically." >> $GITHUB_STEP_SUMMARY
+          else
+            echo "## Version Bump Summary" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "✅ No version bumps required - no relevant commits found since last release." >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "The workflow completed successfully with no changes." >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/claude-code-review.yml

@@ -0,0 +1,58 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@2f8ba26a219c06cfb0f468eef8d97055fa814f97 # v1.0.53
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          allowed_bots: "renovate-bot-cbcoutinho"
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+

.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@2f8ba26a219c06cfb0f468eef8d97055fa814f97 # v1.0.53
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

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

@@ -2,7 +2,8 @@ name: Build and Publish Docker Image
 
 on:
   push:
-    tags: ["*"]
+    tags:
+      - "v*"
 
 jobs:
   build-and-push:
@@ -12,11 +13,11 @@ jobs:
       packages: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
         with:
           # list of Docker images to use as base name for tags
           images: |
@@ -33,18 +34,18 @@ jobs:
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
 
       - name: Log in to GitHub Container Registry
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
         with:
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}

.github/workflows/helm-release.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - v*
+      - nextcloud-mcp-server-*
 
 jobs:
   release:
@@ -14,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
@@ -38,6 +39,8 @@ jobs:
 
       - name: Run chart-releaser
         uses: helm/chart-releaser-action@cae68fefc6b5f367a0275617c9f83181ba54714f # v1.7.0
+        with:
+          skip_existing: true
         env:
           CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
 

.github/workflows/rag-evaluation.yml

@@ -0,0 +1,105 @@
+name: RAG Evaluation
+
+on:
+  workflow_dispatch:
+    inputs:
+      manual_path:
+        description: 'Path to Nextcloud User Manual PDF in Nextcloud'
+        required: false
+        default: 'Nextcloud Manual.pdf'
+      embedding_model:
+        description: 'OpenAI embedding model'
+        required: false
+        default: 'openai/text-embedding-3-small'
+      generation_model:
+        description: 'OpenAI generation model'
+        required: false
+        default: 'openai/gpt-4o-mini'
+
+jobs:
+  rag-evaluation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      models: read
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Run docker compose with vector sync
+        uses: hoverkraft-tech/compose-action@4894d2492015c1774ee5a13a95b1072093087ec3 # v2.5.0
+        with:
+          compose-file: |
+            ./docker-compose.yml
+            ./docker-compose.ci.yml
+          up-flags: "--build"
+        env:
+          # Environment variables passed to docker-compose.ci.yml
+          OPENAI_API_KEY: ${{ secrets.GITHUB_TOKEN }}
+          OPENAI_BASE_URL: "https://models.github.ai/inference"
+          OPENAI_EMBEDDING_MODEL: ${{ inputs.embedding_model }}
+          OPENAI_GENERATION_MODEL: ${{ inputs.generation_model }}
+          VECTOR_SYNC_SCAN_INTERVAL: "5"
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+
+      - name: Wait for Nextcloud to be ready
+        run: |
+          echo "Waiting for Nextcloud..."
+          max_attempts=60
+          attempt=0
+          until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8080/ocs/v2.php/apps/serverinfo/api/v1/info | grep -q "401"; do
+            attempt=$((attempt + 1))
+            if [ $attempt -ge $max_attempts ]; then
+              echo "Service did not become ready in time."
+              exit 1
+            fi
+            echo "Attempt $attempt/$max_attempts: Service not ready, sleeping for 5 seconds..."
+            sleep 5
+          done
+          echo "Nextcloud is ready."
+
+      - name: Wait for MCP server to be ready
+        run: |
+          echo "Waiting for MCP server..."
+          max_attempts=30
+          attempt=0
+          until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8000/health/live | grep -q "200"; do
+            attempt=$((attempt + 1))
+            if [ $attempt -ge $max_attempts ]; then
+              echo "MCP server did not become ready in time."
+              exit 1
+            fi
+            echo "Attempt $attempt/$max_attempts: MCP not ready, sleeping for 2 seconds..."
+            sleep 2
+          done
+          echo "MCP server is ready."
+
+      - name: Run RAG evaluation tests
+        env:
+          NEXTCLOUD_HOST: "http://localhost:8080"
+          NEXTCLOUD_USERNAME: "admin"
+          NEXTCLOUD_PASSWORD: "admin"
+          RAG_MANUAL_PATH: ${{ inputs.manual_path }}
+          OPENAI_API_KEY: ${{ secrets.GITHUB_TOKEN }}
+          OPENAI_BASE_URL: "https://models.github.ai/inference"
+          OPENAI_EMBEDDING_MODEL: ${{ inputs.embedding_model }}
+          OPENAI_GENERATION_MODEL: ${{ inputs.generation_model }}
+        run: |
+          uv run pytest tests/integration/test_rag.py -v --log-cli-level=INFO --provider openai
+
+      - name: Capture MCP container logs
+        if: always()
+        run: |
+          echo "=== MCP Container Logs ==="
+          docker compose logs mcp --tail=500
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: rag-evaluation-results
+          path: |
+            pytest-results.xml
+          retention-days: 30

.github/workflows/release.yml

@@ -18,9 +18,9 @@ jobs:
       contents: read
     steps:
       - name: Checkout
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Install uv
-        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
       - name: Install Python 3.11
         run: uv python install 3.11
       - name: Build

.github/workflows/test.yml

@@ -9,9 +9,9 @@ jobs:
   linting:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
       - name: Check format
         run: |
           uv run --frozen ruff format --diff
@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           submodules: 'true'
 
@@ -35,7 +35,7 @@ jobs:
       ###### Required to build OIDC App ######
 
       - name: Set up php 8.4
-        uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # v2
+        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # 2.36.0
         with:
           php-version: 8.4
           coverage: none
@@ -49,14 +49,14 @@ jobs:
 
 
       - name: Run docker compose
-        uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
+        uses: hoverkraft-tech/compose-action@4894d2492015c1774ee5a13a95b1072093087ec3 # v2.5.0
         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@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
 
       - name: Install Playwright dependencies
         run: |

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "third_party/notes"]
 	path = third_party/notes
 	url = https://github.com/cbcoutinho/notes
+[submodule "third_party/astrolabe"]
+	path = third_party/astrolabe
+	url = https://github.com/cbcoutinho/astrolabe

CHANGELOG.md

@@ -1,3 +1,526 @@
+# Changelog - MCP Server
+
+All notable changes to the Nextcloud MCP Server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [PEP 440](https://peps.python.org/pep-0440/).
+
+## v0.64.0 (2026-02-16)
+
+### Feat
+
+- add self-signed SSL certificate support for Nextcloud connections
+
+### Fix
+
+- add type: ignore for caldav ssl_verify_cert parameter
+- convert CA bundle path to ssl.SSLContext to avoid httpx deprecation warning
+
+## v0.63.5 (2026-02-16)
+
+### Refactor
+
+- remove stale astrolabe references from commitizen config
+- extract Astrolabe to separate repository
+
+## v0.63.4 (2026-02-08)
+
+### Fix
+
+- strip whitespace from category names when splitting
+- handle categories, recurrence_rule, attendees, and reminder_minutes in update_event
+
+## v0.63.3 (2026-02-08)
+
+### Fix
+
+- expand recurring events in date-range queries
+
+## v0.63.2 (2026-02-07)
+
+### Fix
+
+- use CalDAV time-range filter for calendar date range queries
+
+## v0.63.1 (2026-02-03)
+
+### Fix
+
+- **helm**: add backward compatibility for legacy persistence configs
+
+## v0.63.0 (2026-01-28)
+
+### Feat
+
+- **astrolabe**: add background token refresh job
+
+### Fix
+
+- **astrolabe**: add pagination and psalm fixes for token refresh
+- **astrolabe**: add locking to prevent token refresh race condition
+- **astrolabe**: add issued_at to on-demand token refresh
+
+## v0.62.0 (2026-01-26)
+
+### Feat
+
+- **scripts**: add database query helpers for development
+
+### Fix
+
+- **astrolabe**: resolve Psalm type errors in PDF preview code
+- **astrolabe**: fix Psalm baseline and ESLint import order
+- **astrolabe**: load pdfjs-dist externally to fix PDF viewer
+- **astrolabe**: improve error messages for authorization issues
+- **astrolabe**: rename OAuthController and fix app password check
+- **tests**: improve Astrolabe integration test reliability
+- **astrolabe**: update Plotly title attributes for v3 compatibility
+- **deps**: update dependency plotly.js-dist-min to v3
+
+### Refactor
+
+- **api**: split management.py into domain-focused modules
+- **astrolabe**: replace client-side PDF.js with server-side PyMuPDF rendering
+
+## v0.61.5 (2026-01-17)
+
+### Fix
+
+- **astrolabe**: improve token refresh error handling and validation
+- **astrolabe**: delete stale tokens when refresh fails
+- **astrolabe**: resolve CI failures for code quality checks
+- **astrolabe**: use internal URL for OAuth token refresh
+
+### Refactor
+
+- **astrolabe**: add PHP property types to fix Psalm errors
+- **astrolabe**: upgrade to @nextcloud/vue 9.3.3 API
+
+## v0.61.4 (2026-01-16)
+
+### Fix
+
+- **astrolabe**: Address reviewer feedback for hybrid mode
+- **astrolabe**: Fix NcSelect options and CSS loading
+- **astrolabe**: fix OAuth flow and settings UI for hybrid mode
+- **api**: return OIDC config in hybrid mode for Astrolabe OAuth flow
+
+## v0.61.3 (2026-01-15)
+
+### Fix
+
+- **astrolabe**: address review feedback for Vue 3 bindings
+- **astrolabe**: update Vue component bindings for Vue 3 compatibility
+
+## v0.61.2 (2026-01-15)
+
+### Fix
+
+- **ci**: bump helm chart version when MCP appVersion changes
+
+## v0.61.1 (2026-01-15)
+
+### Fix
+
+- **astrolabe**: define appName and appVersion for @nextcloud/vue
+
+## v0.61.0 (2026-01-14)
+
+### Feat
+
+- Add rate limiting and extract helpers for app password endpoints
+
+### Fix
+
+- Add missing annotations for deck remove/unassign operations
+- **auth**: Store app passwords locally for multi-user BasicAuth background sync
+
+### Refactor
+
+- Use get_settings() for vector sync enabled check
+- Extract storage helper and improve PHP error handling
+
+## v0.60.4 (2026-01-12)
+
+### Fix
+
+- **deck**: use correct endpoint for reorder_card to fix cross-stack moves
+
+## v0.60.3 (2025-12-31)
+
+### Fix
+
+- **deck**: Always preserve fields in update_card for partial updates
+- **astrolabe**: Fix CSS loading for Nextcloud apps
+- **astrolabe**: Fix revoke access button HTTP method mismatch
+
+## v0.60.2 (2025-12-29)
+
+### Fix
+
+- **oauth**: Enable browser OAuth routes for Management API in hybrid mode
+
+## v0.60.1 (2025-12-26)
+
+### Fix
+
+- **mcp**: Move all imports to the top of modules
+
+## v0.60.0 (2025-12-26)
+
+### Feat
+
+- Remove URL rewriting in favor of proper nextcloud config
+- **helm**: migrate to new environment variable naming convention
+- Migrate to vue 3
+- **astrolabe**: upgrade to Vue 3 and @nextcloud/vue 9
+
+### Fix
+
+- **tests**: Add singleton reset fixture to prevent anyio.WouldBlock errors
+- **tests**: Fix integration test failures in qdrant, sampling, and rag tests
+- **auth**: Skip issuer validation for management API tokens
+- Use settings.enable_offline_access for env var consolidation
+- Add required config.py attributes
+- **docker**: remove overwritehost to fix container-to-container DCR
+- **deps**: update dependency @nextcloud/vue to v9
+- **deps**: update dependency vue to v3
+
+### Refactor
+
+- **auth**: Decouple BasicAuth and OAuth authentication strategies
+
+## v0.59.1 (2025-12-22)
+
+### Fix
+
+- **helm**: set OIDC client env vars when using existingSecret
+- **helm**: trigger chart release workflow on helm chart tags
+
+## v0.59.0 (2025-12-22)
+
+### Feat
+
+- **helm**: add support for multi-user BasicAuth mode
+
+### Fix
+
+- **helm**: address PR #447 reviewer feedback
+- **helm**: include MCP server version bumps in changelog pattern
+
+## v0.58.0 (2025-12-22)
+
+### Feat
+
+- **config**: enable DCR for multi-user BasicAuth with offline access
+- **astrolabe**: implement app password provisioning for multi-user background sync
+- **config**: consolidate configuration with smart dependency resolution (ADR-021)
+
+## v0.57.0 (2025-12-20)
+
+### Feat
+
+- **auth**: add multi-user BasicAuth pass-through mode
+- **astrolabe**: add dynamic MCP server configuration for testing
+
+### Fix
+
+- **config**: address reviewer feedback
+
+### Refactor
+
+- **config**: centralize configuration validation and simplify startup
+
+## v0.56.2 (2025-12-20)
+
+### Fix
+
+- **astrolabe**: screenshots in info.xml
+- **astrolabe**: screenshots in info.xml
+
+## v0.56.1 (2025-12-19)
+
+### Fix
+
+- **astrolabe**: Update screenshots
+- **ci**: skip existing Helm chart releases to prevent duplicate release errors
+
+## v0.56.0 (2025-12-19)
+
+### Feat
+
+- **ci**: add --increment flag to bump scripts for manual version control
+
+### Fix
+
+- **astrolabe**: add contents:write permission to appstore workflow
+- **astrolabe**: update commitizen pattern to properly update info.xml version
+- **astrolabe**: prevent workflow failure when only helm/astrolabe commits exist
+- **astrolabe**: info.xml
+
+## v0.55.1 (2025-12-19)
+
+### Fix
+
+- **ci**: push all tags explicitly in bump workflow
+
+## v0.55.0 (2025-12-19)
+
+### BREAKING CHANGE
+
+- MCP server now bumps for ANY conventional commit except
+those explicitly scoped to helm or astrolabe.
+
+### Feat
+
+- **ci**: implement monorepo-aware version bumping workflow
+
+### Fix
+
+- **ci**: make MCP server default bump target for all non-scoped commits
+- **ci**: restrict docker build to MCP server tags only
+- **ci**: correct appstore-push-action version to v1.0.4
+
+## v0.54.0 (2025-12-19)
+
+### Feat
+
+- **astrolabe**: add Nextcloud App Store deployment automation
+- configure commitizen monorepo with independent versioning
+
+### Fix
+
+- **ci**: improve versioning and error handling
+- **ci**: address critical workflow and validation issues
+- **astrolabe**: address code review feedback
+
+## v0.53.0 (2025-12-19)
+
+### Feat
+
+- add Alembic database migration system
+- make chunk modal title clickable link to documents
+- add native Plotly hover styling for clickable points
+- add click interactivity to Plotly 3D scatter chart
+- improve chunk viewer with fixed navigation and markdown rendering
+- **astrolabe**: enable multi-select for document types and refactor PDF viewer
+- **auth**: implement refresh token rotation for Nextcloud OIDC
+- **astrolabe**: enhance unified search and add webhook management
+- **astrolabe**: add webhook management UI to admin settings
+- **astrolabe**: add OAuth token refresh and webhook presets
+- **search**: add file_path metadata and chunk offsets to search results
+- **astrolabe**: use proper icons and thumbnails in unified search
+- **astrolabe**: add admin search settings and enhanced UI
+- **astrolabe**: add unified search provider with clickable file links
+- **astrolabe**: add 3D PCA visualization for semantic search
+- **astrolabe**: add Nextcloud PHP app for MCP server management
+- **vector-sync**: enable background sync in OAuth mode
+
+### Fix
+
+- **security**: address critical security issues from PR #401 code review
+- **oauth**: enable PKCE for all clients and add token_broker to oauth_context
+- **astrolabe**: revert invalid files_pdfviewer URL for file links
+- resolve type checking warnings for CI
+- move Alembic to package submodule for Docker compatibility
+- update unified search results to match chunk viz display
+- **astrolabe**: handle OAuth refresh token rotation
+- address critical code review issues (4 fixes)
+- resolve CI linting issues for Astroglobe
+
+### Refactor
+
+- **astrolabe**: extract PDF viewer to dedicated component
+- **astrolabe**: reframe UI as semantic search service
+
+## v0.52.1 (2025-12-13)
+
+### Perf
+
+- **deck**: optimize card lookup by storing board_id/stack_id in metadata
+
+## v0.52.0 (2025-12-13)
+
+### Feat
+
+- **vector**: add Deck card vector search with visualization support
+
+## v0.51.0 (2025-12-13)
+
+### Feat
+
+- **vector-viz**: add news_item support for links and chunk expansion
+
+## v0.50.2 (2025-12-13)
+
+### Fix
+
+- **news**: revert get_item() to use get_items() + filter
+
+## v0.50.1 (2025-12-12)
+
+### Fix
+
+- Disable DNS rebinding protection for containerized deployments
+- **deps**: update dependency mcp to >=1.23,<1.24
+
+## v0.50.0 (2025-12-11)
+
+### Feat
+
+- add MCP tool annotations for enhanced UX
+
+### Fix
+
+- address PR review feedback
+
+## v0.49.2 (2025-12-09)
+
+### Fix
+
+- Update lockfile
+
+## v0.49.1 (2025-12-09)
+
+### Fix
+
+- Revert mcp version <1.23
+
+## v0.49.0 (2025-12-08)
+
+### Feat
+
+- **news**: add Nextcloud News app integration
+
+### Fix
+
+- resolve all type checking errors (8 errors fixed)
+
+### Refactor
+
+- **news**: simplify vector sync to fetch all items
+
+### Perf
+
+- **news**: use direct API endpoint for get_item()
+
+## v0.48.6 (2025-12-03)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.23,<1.24
+
+## v0.48.5 (2025-11-28)
+
+### Fix
+
+- **deps**: update dependency pillow to v12
+
+## v0.48.4 (2025-11-23)
+
+### Fix
+
+- Add rate limit retry logic to OpenAI provider
+
+## v0.48.3 (2025-11-23)
+
+### Fix
+
+- Increase MCP sampling timeout to 5 minutes for slower LLMs
+
+## v0.48.2 (2025-11-23)
+
+### Fix
+
+- Share vector sync state with FastMCP session lifespan via module singleton
+- Share vector sync state with FastMCP session lifespan via module singleton
+
+## v0.48.1 (2025-11-23)
+
+### Fix
+
+- Use WebDAV for tag creation and add LLM-as-a-judge for RAG tests
+
+### Refactor
+
+- Move background tasks to server lifespan and deprecate SSE transport
+
+## v0.48.0 (2025-11-23)
+
+### Feat
+
+- Add tag management methods to WebDAV client
+
+## v0.47.0 (2025-11-23)
+
+### Feat
+
+- Add OpenAI provider support for embeddings and generation
+
+## v0.46.2 (2025-11-22)
+
+### Fix
+
+- **smithery**: Enable JSON response format for scanner compatibility
+
+## v0.46.1 (2025-11-22)
+
+### Perf
+
+- Optimize vector viz search performance
+
+## v0.46.0 (2025-11-22)
+
+### Feat
+
+- Add Smithery CLI deployment support
+- Implement ADR-016 Smithery stateless deployment mode
+
+### Fix
+
+- **smithery**: Add JSON Schema metadata to mcp-config endpoint
+- **smithery**: Use container runtime pattern for config discovery
+- Add Smithery lifespan and auth mode detection
+
+## v0.45.0 (2025-11-22)
+
+### Feat
+
+- Add context expansion to semantic search with chunk overlap removal
+- Use Ollama native batch API in embed_batch()
+- Implement Qdrant placeholder state management
+- Switch files to use numeric IDs with file_path resolution
+- Implement per-chunk vector visualization with context expansion
+
+### Fix
+
+- Use alpha_composite for proper RGBA highlight blending
+- Remove pymupdf.layout.activate() to fix page_chunks behavior
+- Centralize PDF processing and generate separate images per chunk
+- Set is_placeholder=False in processor to fix search filtering
+- Increase placeholder staleness threshold to 5x scan interval
+- Add placeholder staleness check to prevent duplicate processing
+- Use empty SparseVector instead of None for placeholders
+- Return empty array instead of null for query_coords when no results
+- Align PDF text extraction between indexing and context expansion
+- Update models and viz to use int-only doc_id
+- Reconstruct full content for notes to match indexed offsets
+- Add async/await, PDF metadata, and type safety fixes
+
+### Refactor
+
+- Simplify PDF text extraction with single to_markdown call
+
+### Perf
+
+- Optimize PDF processing with parallel extraction and single-render highlights
+
+## v0.44.1 (2025-11-21)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.22,<1.23
+
 ## v0.44.0 (2025-11-19)
 
 ### Feat

CLAUDE.md

@@ -56,6 +56,68 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
   - Pass-through (default): Simple, stateless (ENABLE_TOKEN_EXCHANGE=false)
   - Token exchange (opt-in): RFC 8693 delegation (ENABLE_TOKEN_EXCHANGE=true)
 
+### MCP Tool Annotations (ADR-017)
+
+**All tools MUST include annotations** following these patterns:
+
+```python
+from mcp.types import ToolAnnotations
+
+# Read-only tools (list, search, get)
+@mcp.tool(
+    title="Human Readable Name",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=True,  # Nextcloud is external to MCP server
+    ),
+)
+
+# Create operations
+@mcp.tool(
+    title="Create Resource",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # Creates new resources each time
+        openWorldHint=True,
+    ),
+)
+
+# Update operations (with etag/version control)
+@mcp.tool(
+    title="Update Resource",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # ETag changes = different inputs
+        openWorldHint=True,
+    ),
+)
+
+# Delete operations
+@mcp.tool(
+    title="Delete Resource",
+    annotations=ToolAnnotations(
+        destructiveHint=True,   # Permanently deletes data
+        idempotentHint=True,    # Same end state if called repeatedly
+        openWorldHint=True,
+    ),
+)
+
+# HTTP PUT without version control (special case)
+@mcp.tool(
+    title="Write File",
+    annotations=ToolAnnotations(
+        idempotentHint=True,  # Same content = same end state
+        openWorldHint=True,
+    ),
+)
+```
+
+**Key Principles**:
+- **Idempotency**: Same inputs → same result. ETags change after updates, making them non-idempotent
+- **Destructive**: Operations that permanently delete/overwrite data
+- **Open World**: All Nextcloud tools access external service (openWorldHint=True)
+- **Titles**: Use human-readable names, not snake_case function names
+
+**See**: `docs/ADR-017-mcp-tool-annotations.md` for detailed rationale and examples
+
 ### Project Structure
 - `nextcloud_mcp_server/client/` - HTTP clients for Nextcloud APIs
 - `nextcloud_mcp_server/server/` - MCP tool/resource definitions
@@ -177,6 +239,25 @@ uv run python -m tests.load.benchmark --output results.json --verbose
 
 **Credentials**: root/password, nextcloud/password, database: `nextcloud`
 
+### Quick Query Script (Recommended for Agents)
+
+Use `scripts/dbquery.py` for single SQL statements without requiring approval for each `docker compose exec`:
+
+```bash
+# Basic query
+./scripts/dbquery.py "SELECT COUNT(*) FROM oc_users"
+
+# Vertical output (one column per line) - useful for wide tables
+./scripts/dbquery.py -E "SELECT * FROM oc_oidc_clients LIMIT 1"
+
+# With different credentials
+./scripts/dbquery.py -u nextcloud -p nextcloud "SHOW TABLES"
+```
+
+### Direct Docker Access
+
+For interactive sessions or complex operations:
+
 ```bash
 # Connect to database
 docker compose exec db mariadb -u root -ppassword nextcloud
@@ -202,6 +283,40 @@ docker compose exec db mariadb -u root -ppassword nextcloud -e \
 - `oc_oidc_registration_tokens` - RFC 7592 registration tokens
 - `oc_oidc_redirect_uris` - Redirect URIs
 
+### SQLite Databases (MCP Services)
+
+Use `scripts/sqlitequery.py` to query SQLite databases in MCP service containers:
+
+```bash
+# List tables
+./scripts/sqlitequery.py ".tables"
+
+# Query specific service
+./scripts/sqlitequery.py -s oauth "SELECT * FROM refresh_tokens"
+./scripts/sqlitequery.py -s keycloak "SELECT * FROM oauth_clients"
+./scripts/sqlitequery.py -s basic "SELECT * FROM app_passwords"
+
+# With column headers
+./scripts/sqlitequery.py --column "SELECT * FROM audit_logs LIMIT 5"
+
+# JSON output
+./scripts/sqlitequery.py --json "SELECT * FROM oauth_sessions"
+
+# View schema
+./scripts/sqlitequery.py -s oauth ".schema refresh_tokens"
+```
+
+**Services**: `mcp` (default), `oauth`, `keycloak`, `basic`
+
+**SQLite Tables**:
+- `refresh_tokens` - OAuth refresh tokens with user profiles
+- `audit_logs` - Security audit trail
+- `oauth_clients` - DCR OAuth client credentials
+- `oauth_sessions` - OAuth flow session state
+- `registered_webhooks` - Webhook registrations
+- `app_passwords` - Multi-user BasicAuth passwords
+- `alembic_version` - Migration tracking
+
 ## Architecture Quick Reference
 
 **For detailed architecture, see:**
@@ -444,6 +559,29 @@ docker compose exec app php occ user_oidc:provider keycloak
 **Nextcloud**: `docker compose exec app php occ ...` for occ commands
 **MariaDB**: `docker compose exec db mariadb -u [user] -p [password] [database]` for queries
 
+### Querying Nextcloud Application Logs
+
+**Use this pattern** to inspect Nextcloud application logs during debugging:
+
+```bash
+# View recent log entries
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq | tail
+
+# Filter by app
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.app == "astrolabe")' | tail
+
+# Filter by log level (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=FATAL)
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.level >= 3)' | tail
+
+# Search for specific messages
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.message | contains("OAuth"))' | tail -20
+
+# View full exception traces
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.exception != null)' | tail -5
+```
+
+**Log Structure**: Each entry is a JSON object with fields: `reqId`, `level`, `time`, `remoteAddr`, `user`, `app`, `method`, `url`, `message`, `userAgent`, `version`, `exception`
+
 **For detailed setup, see**:
 - `docs/installation.md` - Installation guide
 - `docs/configuration.md` - Configuration options

CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contributing to Nextcloud MCP Server
+
+## Version Management
+
+This monorepo uses commitizen for version management with **independent versioning** for two components:
+
+### Components
+
+| Component | Scope | Bump Command | Tag Example |
+|-----------|-------|--------------|-------------|
+| MCP Server | `mcp` or none | `./scripts/bump-mcp.sh` | `v0.54.0` |
+| Helm Chart | `helm` | `./scripts/bump-helm.sh` | `nextcloud-mcp-server-0.54.0` |
+
+> **Note:** The Astrolabe Nextcloud app has been moved to its own repository at [cbcoutinho/astrolabe](https://github.com/cbcoutinho/astrolabe).
+
+### Commit Message Format
+
+Use conventional commits with **scopes** to target specific components:
+
+```bash
+# MCP server changes
+feat(mcp): add calendar sync API
+fix(mcp): resolve authentication bug
+
+# Helm chart changes
+feat(helm): add resource limits
+docs(helm): update values documentation
+```
+
+**Unscoped commits** default to the MCP server:
+```bash
+feat: add new feature  # → MCP server (v0.54.0)
+```
+
+### Release Workflow
+
+#### 1. Make Changes with Scoped Commits
+
+```bash
+git commit -m "feat(helm): add ingress annotations"
+git commit -m "feat(mcp): add calendar sync"
+```
+
+#### 2. Bump Component Versions
+
+```bash
+# Bump MCP server (reads commits with scope=mcp or unscoped)
+./scripts/bump-mcp.sh
+# → Creates tag: v0.54.0
+# → Updates: pyproject.toml, Chart.yaml:appVersion
+
+# Bump Helm chart (reads commits with scope=helm)
+./scripts/bump-helm.sh
+# → Creates tag: nextcloud-mcp-server-0.54.0
+# → Updates: Chart.yaml:version
+
+```
+
+#### 3. Push Tags
+
+```bash
+git push --follow-tags
+```
+
+### Changelog Filtering
+
+Each component maintains its own `CHANGELOG.md`:
+
+- **MCP Server**: `CHANGELOG.md` (root) - includes `feat(mcp):` and unscoped commits
+- **Helm Chart**: `charts/nextcloud-mcp-server/CHANGELOG.md` - includes `feat(helm):` only
+
+### Manual Version Bumps
+
+For specific increments:
+
+```bash
+# Patch bump (0.53.0 → 0.53.1)
+uv run cz bump --increment PATCH
+
+# Minor bump (0.53.0 → 0.54.0)
+uv run cz bump --increment MINOR
+
+# Major bump (0.53.0 → 1.0.0)
+uv run cz bump --increment MAJOR
+
+# For non-MCP components, use --config
+cd charts/nextcloud-mcp-server
+uv run cz --config .cz.toml bump --increment MINOR
+```
+
+### Versioning Philosophy
+
+- **MCP Server**: Follows PEP 440, `major_version_zero = true` (0.x.x for pre-1.0)
+- **Helm Chart**: Follows PEP 440, starts at 0.53.0 (continues from current)
+
+### Chart.yaml Version vs appVersion
+
+The Helm chart has TWO version fields:
+
+- **`version`**: Chart packaging version (bumped by `feat(helm):`)
+  - Example: `0.53.0` → `0.54.0` when adding resource limits
+
+- **`appVersion`**: MCP server version being deployed (bumped by `feat(mcp):`)
+  - Example: `"0.53.0"` → `"0.54.0"` when MCP server releases
+
+This allows the chart to evolve independently from the application.

Dockerfile

@@ -1,21 +1,28 @@
-FROM docker.io/library/python:3.12-slim-trixie@sha256:2e683fc3e18a248aa23b8022f2a3474b072b04fb851efe9b49f6b516a8944939
+FROM docker.io/library/python:3.12-slim-trixie@sha256:9e01bf1ae5db7649a236da7be1e94ffbbbdd7a93f867dd0d8d5720d9e1f89fab
 
-COPY --from=ghcr.io/astral-sh/uv:0.9.10@sha256:29bd45092ea8902c0bbb7f0a338f0494a382b1f4b18355df5be270ade679ff1d /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.10.4@sha256:4cac394b6b72846f8a85a7a0e577c6d61d4e17fe2ccee65d9451a8b3c9efb4ac /uv /uvx /bin/
 
 # Install dependencies
 # 1. git (required for caldav dependency from git)
 # 2. sqlite for development with token db
 RUN apt update && apt install --no-install-recommends --no-install-suggests -y \
     git \
+    tesseract-ocr \
     sqlite3 && apt clean
 
 WORKDIR /app
 
+COPY pyproject.toml uv.lock README.md .
+
+RUN uv sync --locked --no-dev --no-install-project --no-cache
+
 COPY . .
 
 RUN uv sync --locked --no-dev --no-editable --no-cache
 
 ENV PYTHONUNBUFFERED=1
 ENV VIRTUAL_ENV=/app/.venv
+ENV PATH=/app/.venv/bin:$PATH
+ENV TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata
 
-ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "--host", "0.0.0.0"]
+ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "run", "--host", "0.0.0.0"]

Dockerfile.smithery

@@ -0,0 +1,44 @@
+# Dockerfile for Smithery stateless deployment
+# ADR-016: Stateless mode for multi-user public Nextcloud instances
+#
+# This image excludes:
+# - Vector database dependencies (qdrant-client)
+# - Background sync workers
+# - Admin UI routes (/app)
+# - Semantic search tools
+#
+# Features included:
+# - Core Nextcloud tools (notes, calendar, contacts, files, deck, tables, cookbook)
+# - Per-session app password authentication
+# - Multi-user support via Smithery session config
+
+FROM docker.io/library/python:3.12-slim-trixie@sha256:9e01bf1ae5db7649a236da7be1e94ffbbbdd7a93f867dd0d8d5720d9e1f89fab
+
+WORKDIR /app
+
+# Install uv for fast dependency management
+COPY --from=ghcr.io/astral-sh/uv:0.10.4@sha256:4cac394b6b72846f8a85a7a0e577c6d61d4e17fe2ccee65d9451a8b3c9efb4ac /uv /uvx /bin/
+
+# Install dependencies
+# 1. git (required for caldav dependency from git)
+# 2. sqlite for development with token db
+RUN apt update && apt install --no-install-recommends --no-install-suggests -y \
+    git
+
+# Copy project files
+COPY . .
+
+RUN uv sync --locked --no-dev --no-editable --no-cache
+
+# Set Smithery mode environment variables
+ENV SMITHERY_DEPLOYMENT=true
+ENV VECTOR_SYNC_ENABLED=false
+
+# Smithery sets PORT=8081 by default
+EXPOSE 8081
+
+# Health check endpoint
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD uv run python -c "import httpx; httpx.get('http://localhost:${PORT:-8081}/health/live').raise_for_status()"
+
+CMD ["/app/.venv/bin/smithery-main"]

README.md

@@ -5,6 +5,7 @@
 # Nextcloud MCP Server
 
 [![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)
+[![smithery badge](https://smithery.ai/badge/@cbcoutinho/nextcloud-mcp-server)](https://smithery.ai/server/@cbcoutinho/nextcloud-mcp-server)
 
 **A production-ready MCP server that connects AI assistants to your Nextcloud instance.**
 
@@ -17,7 +18,20 @@ This is a **dedicated standalone MCP server** designed for external MCP clients
 
 ## Quick Start
 
-Get up and running in 60 seconds using Docker:
+The fastest way to get started is via [Smithery](https://smithery.ai/server/@cbcoutinho/nextcloud-mcp-server) - no Docker or self-hosting required:
+
+1. Visit the [Smithery marketplace page](https://smithery.ai/server/@cbcoutinho/nextcloud-mcp-server)
+2. Click "Deploy" and configure:
+   - **Nextcloud URL**: Your Nextcloud instance (e.g., `https://cloud.example.com`)
+   - **Username**: Your Nextcloud username
+   - **App Password**: Generate one in Nextcloud → Settings → Security → Devices & sessions
+
+> [!NOTE]
+> Smithery runs in stateless mode without semantic search. For full features, use [Docker](#docker-self-hosted) or see [ADR-016](docs/ADR-016-smithery-stateless-deployment.md).
+
+## Docker (Self-Hosted)
+
+For full features including semantic search, run with Docker:
 
 ```bash
 # 1. Create a minimal configuration
@@ -37,12 +51,11 @@ curl http://127.0.0.1:8000/health/ready
 # 4. Connect to the endpoint
 http://127.0.0.1:8000/sse
 
-# 4. Or with --transport streamable-http
+# Or with --transport streamable-http
 http://127.0.0.1:8000/mcp
 ```
 
 **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)
 
@@ -50,7 +63,7 @@ http://127.0.0.1:8000/mcp
 
 - **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)
+- **Semantic Search (Experimental)** - Optional vector-powered search for Notes, Files, News items, and Deck cards (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)
@@ -68,7 +81,7 @@ http://127.0.0.1:8000/mcp
 | **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) |
+| **Semantic Search** | 2+ | Vector search for Notes, Files, News items, and Deck cards (experimental, opt-in, requires infrastructure) |
 
 Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request!
 
@@ -86,7 +99,7 @@ Want to see another Nextcloud app supported? [Open an issue](https://github.com/
 
 ### Authentication Modes
 
-The server supports two authentication modes:
+The server supports three authentication modes:
 
 **Single-User Mode (BasicAuth):**
 - One set of credentials shared by all MCP clients
@@ -100,6 +113,12 @@ The server supports two authentication modes:
 - More secure: tokens expire, credentials never shared with server
 - Best for: Teams, multi-user deployments, production environments with multiple users
 
+**Hybrid Mode (Multi-User BasicAuth + OAuth):**
+- MCP clients use BasicAuth (simple, stateless)
+- Admin operations use OAuth (webhooks, background sync)
+- Best for: Nextcloud deployments with admin-managed webhooks and semantic search
+- Requires: `ENABLE_MULTI_USER_BASIC_AUTH=true` + `ENABLE_OFFLINE_ACCESS=true`
+
 See [docs/authentication.md](docs/authentication.md) for detailed setup instructions.
 
 ## Semantic Search
@@ -114,7 +133,7 @@ This enables natural language queries and helps discover related content across
 
 > [!NOTE]
 > **Semantic Search is experimental and opt-in:**
-> - Disabled by default (`VECTOR_SYNC_ENABLED=false`)
+> - Disabled by default (`ENABLE_SEMANTIC_SEARCH=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
@@ -132,7 +151,7 @@ This enables natural language queries and helps discover related content across
 ### 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)
+- **[Semantic Search Architecture](docs/semantic-search-architecture.md)** - Experimental vector search (Notes, Files, News items, Deck cards; opt-in)
 - **[Vector Sync UI Guide](docs/user-guide/vector-sync-ui.md)** - Browser interface for semantic search visualization and testing
 
 ### Advanced Topics

alembic.ini

@@ -0,0 +1,90 @@
+# Alembic configuration file for nextcloud-mcp-server
+
+[alembic]
+# Path to migration scripts
+script_location = nextcloud_mcp_server/alembic
+
+# Template used to generate migration file names
+# Default: %%(rev)s_%%(slug)s
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
+
+# Timezone for migration timestamps
+# Default: utc
+timezone = utc
+
+# Max length of characters to apply to the "slug" field
+# Default: 40
+# truncate_slug_length = 40
+
+# Set to 'true' to run the environment during the 'revision' command
+# Default: false
+# revision_environment = false
+
+# Set to 'true' to allow .pyc and .pyo files without a source .py file
+# Default: false
+# sourceless = false
+
+# Version location specification
+# Supports single or multiple directories
+version_locations = nextcloud_mcp_server/alembic/versions
+
+# Path separator for version locations (required to suppress deprecation warning)
+# Use os (for cross-platform compatibility)
+path_separator = os
+
+# Set to 'true' to search source files recursively in each "version_locations" directory
+# Default: false
+# recursive_version_locations = false
+
+# Output encoding used when revision files are written
+# Default: utf-8
+# output_encoding = utf-8
+
+# Database URL - can be overridden by:
+# 1. Passing -x database_url=... to alembic commands
+# 2. Setting in environment via get_database_url() in env.py
+# Default: sqlite:///app/data/tokens.db
+sqlalchemy.url = sqlite+aiosqlite:////app/data/tokens.db
+
+[post_write_hooks]
+# Post-write hooks allow you to run scripts after generating migration files
+# Example: format migrations with ruff
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = format REVISION_SCRIPT_FILENAME
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/README

@@ -0,0 +1,71 @@
+Database Migrations for nextcloud-mcp-server
+============================================
+
+This directory contains Alembic database migrations for the token storage database.
+
+Structure
+---------
+- env.py: Alembic environment configuration
+- script.py.mako: Template for generating new migration files
+- versions/: Directory containing migration scripts
+
+Usage
+-----
+Migrations are managed via the CLI:
+
+    # Upgrade database to latest version
+    uv run nextcloud-mcp-server db upgrade
+
+    # Show current database version
+    uv run nextcloud-mcp-server db current
+
+    # Show migration history
+    uv run nextcloud-mcp-server db history
+
+    # Create a new migration (developers only)
+    uv run nextcloud-mcp-server db migrate "description of changes"
+
+    # Downgrade database by one version (emergency use only)
+    uv run nextcloud-mcp-server db downgrade
+
+Direct Alembic Usage
+--------------------
+You can also use Alembic commands directly:
+
+    # Specify database URL via -x flag
+    uv run alembic -x database_url=sqlite+aiosqlite:////path/to/tokens.db upgrade head
+
+    # Or set in alembic.ini and run
+    uv run alembic upgrade head
+    uv run alembic current
+    uv run alembic history
+
+Writing Migrations
+------------------
+Since we don't use SQLAlchemy models, migrations are written with raw SQL:
+
+    def upgrade() -> None:
+        op.execute("""
+            ALTER TABLE refresh_tokens
+            ADD COLUMN new_field TEXT
+        """)
+
+    def downgrade() -> None:
+        # SQLite doesn't support DROP COLUMN, use table recreation
+        op.execute("""
+            CREATE TABLE refresh_tokens_new AS
+            SELECT user_id, encrypted_token, ... FROM refresh_tokens
+        """)
+        op.execute("DROP TABLE refresh_tokens")
+        op.execute("ALTER TABLE refresh_tokens_new RENAME TO refresh_tokens")
+
+Migration File Naming
+---------------------
+Format: YYYYMMDD_HHMM_<revision>_<slug>.py
+Example: 20251217_2200_001_initial_schema.py
+
+Notes
+-----
+- Migrations run automatically when RefreshTokenStorage.initialize() is called
+- Existing databases are automatically stamped with the initial version
+- SQLite has limited ALTER TABLE support - complex changes require table recreation

alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Apply migration changes to upgrade the database schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Revert migration changes to downgrade the database schema."""
+    ${downgrades if downgrades else "pass"}

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

@@ -3,3 +3,9 @@
 set -euox pipefail
 
 php /var/www/html/occ config:system:set trusted_domains 2 --value=host.docker.internal
+
+# Set overwrite.cli.url to the external URL for OIDC discovery
+# This ensures OAuth flows redirect to the correct external URL
+# Important: The Astrolabe OAuth controller makes internal HTTP requests to /.well-known/openid-configuration
+# which needs to return URLs reachable by external browsers (localhost:8080, not localhost:80)
+php /var/www/html/occ config:system:set overwrite.cli.url --value="http://localhost:8080"

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

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

app-hooks/post-installation/20-install-astrolabe-app.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+set -euox pipefail
+
+echo "Installing Astrolabe app from app store..."
+
+if [ -d /var/www/html/custom_apps/astrolabe ]; then
+    echo "astrolabe app directory found in custom_apps (already installed)"
+    php /var/www/html/occ app:enable astrolabe
+else
+    php /var/www/html/occ app:install astrolabe
+    php /var/www/html/occ app:enable astrolabe
+fi
+
+echo "Astrolabe app installed successfully"
+echo ""
+echo "Note: MCP server configuration is managed dynamically during tests"
+echo "      to support testing multiple MCP server deployments."

app-hooks/post-installation/25-configure-mcp-server-url.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Configure MCP server URL for Astrolabe background sync
+# This URL is used by Astrolabe to send app passwords to the MCP server
+
+set -e
+
+# The MCP multi-user BasicAuth service runs on port 8000 inside the container
+# From Nextcloud's perspective (inside Docker network), we reach it via service name
+MCP_SERVER_URL="${MCP_SERVER_URL:-http://mcp-multi-user-basic:8000}"
+
+echo "Configuring MCP server URL: $MCP_SERVER_URL"
+
+# Set the mcp_server_url in config.php via occ
+php occ config:system:set mcp_server_url --value="$MCP_SERVER_URL"
+
+echo "MCP server URL configured successfully"

charts/nextcloud-mcp-server/.cz.toml

@@ -0,0 +1,25 @@
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.57.61"
+tag_format = "nextcloud-mcp-server-$version"
+version_scheme = "semver"
+update_changelog_on_bump = true
+major_version_zero = true
+
+# Update chart version only (NOT appVersion)
+version_files = [
+    "Chart.yaml:^version:"
+]
+
+# Ignore tags from other components
+ignored_tag_formats = [
+    "v*",              # MCP server tags
+    "astrolabe-v*",    # Astrolabe tags
+]
+
+# Filter commits by scope
+# Includes helm-scoped commits AND MCP server version bumps (which update appVersion)
+[tool.commitizen.customize]
+changelog_pattern = "^((feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:|bump: version.*→.*)"
+schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:\\s.+"
+message_template = "{{change_type}}(helm): {{message}}"

charts/nextcloud-mcp-server/Chart.lock

@@ -1,9 +1,9 @@
 dependencies:
 - name: qdrant
   repository: https://qdrant.github.io/qdrant-helm
-  version: 1.16.0
+  version: 1.16.3
 - name: ollama
   repository: https://otwld.github.io/ollama-helm
-  version: 1.34.0
-digest: sha256:9dfb8d6e3d5488f669d4c37f3a766213b598ff3de2aead2c734789736c7835b4
-generated: "2025-11-17T17:08:48.055530019Z"
+  version: 1.43.0
+digest: sha256:533eda3fdb4bd92cdafee49bd7b0428fc87d21b509032442c04ed645900e464a
+generated: "2026-02-16T11:16:41.257136832Z"

charts/nextcloud-mcp-server/Chart.yaml

@@ -2,8 +2,8 @@ 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.44.0
-appVersion: "0.44.0"
+version: 0.57.61
+appVersion: "0.64.0"
 keywords:
   - nextcloud
   - mcp
@@ -27,10 +27,10 @@ annotations:
   grafana_dashboard_folder: "Nextcloud MCP"
 dependencies:
   - name: qdrant
-    version: "1.16.0"
+    version: "1.16.3"
     repository: https://qdrant.github.io/qdrant-helm
     condition: qdrant.networkMode.deploySubchart
   - name: ollama
-    version: "1.34.0"
+    version: "1.43.0"
     repository: https://otwld.github.io/ollama-helm
     condition: ollama.enabled

charts/nextcloud-mcp-server/README.md

@@ -99,11 +99,11 @@ ingress:
 |-----------|-------------|---------|
 | `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** |
+| `nextcloud.publicIssuerUrl` | Public URL for browser-accessible OAuth authorization endpoint (OAuth only, optional) | Smart default** |
 
 **Smart Defaults:**
 - `*mcpServerUrl`: If not set, automatically uses ingress host (if enabled) or `http://localhost:8000` (for port-forward setups)
-- `**publicIssuerUrl`: If not set, automatically defaults to `nextcloud.host` (which works when both clients and MCP server access Nextcloud at the same URL)
+- `**publicIssuerUrl`: If not set, defaults to `nextcloud.host`. **Only used for authorization endpoints** that browsers must access. All server-to-server endpoints (token, JWKS, introspection, userinfo) use URLs from OIDC discovery without rewriting
 
 #### Authentication
 
@@ -118,6 +118,25 @@ ingress:
 | `auth.oauth.persistence.enabled` | Enable persistent storage for OAuth | `true` |
 | `auth.oauth.persistence.size` | Size of OAuth storage PVC | `100Mi` |
 
+#### Data Storage
+
+The `/app/data` directory is used for application data (token databases, Qdrant persistent storage, etc.). It is always mounted as writable to support the read-only root filesystem security context.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `dataStorage.enabled` | Enable persistent storage for `/app/data` | `false` |
+| `dataStorage.size` | Size of data storage PVC | `1Gi` |
+| `dataStorage.storageClass` | Storage class (leave empty for default) | `""` |
+| `dataStorage.accessMode` | Access mode | `ReadWriteOnce` |
+| `dataStorage.existingClaim` | Use existing PVC | `""` |
+
+**When to enable persistence:**
+- Multi-user basic auth with offline access (stores `tokens.db`)
+- Qdrant persistent mode (stores vector database)
+- Any feature requiring persistent app data
+
+**When persistence is disabled:** Uses `emptyDir` (non-persistent, data lost on pod restart, but directory remains writable).
+
 #### MCP Server Configuration
 
 | Parameter | Description | Default |
@@ -208,16 +227,16 @@ The application exposes HTTP health check endpoints:
 
 #### Vector Search & Semantic Capabilities (Optional)
 
-Enable semantic search capabilities by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
+Enable semantic search capabilities with BM25 hybrid search by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
 
-**Vector Sync Configuration:**
+**Semantic Search 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` |
+| `semanticSearch.enabled` | Enable semantic search and background vector synchronization | `false` |
+| `semanticSearch.scanInterval` | Scan interval in seconds | `3600` |
+| `semanticSearch.processorWorkers` | Number of concurrent processor workers | `3` |
+| `semanticSearch.queueMaxSize` | Maximum queue size for pending documents | `10000` |
 
 **Document Chunking Configuration:**
 
@@ -427,7 +446,7 @@ 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
+  # publicIssuerUrl defaults to nextcloud.host (only used for browser-accessible auth endpoint)
 
 auth:
   mode: oauth
@@ -459,7 +478,7 @@ This example shows OAuth without pre-registered credentials (using DCR) and opti
 nextcloud:
   host: https://cloud.example.com
   # mcpServerUrl will automatically use ingress host (https://mcp.example.com)
-  # publicIssuerUrl will automatically default to nextcloud.host
+  # publicIssuerUrl will automatically default to nextcloud.host (only used for browser-accessible auth endpoint)
 
 auth:
   mode: oauth
@@ -537,8 +556,8 @@ auth:
     username: admin
     password: secure-password
 
-# Enable vector sync
-vectorSync:
+# Enable semantic search
+semanticSearch:
   enabled: true
   scanInterval: 1800  # Scan every 30 minutes
   processorWorkers: 5
@@ -576,7 +595,7 @@ ollama:
 Or use an external Ollama instance:
 
 ```yaml
-vectorSync:
+semanticSearch:
   enabled: true
 
 qdrant:
@@ -592,7 +611,7 @@ ollama:
 Or use OpenAI for embeddings:
 
 ```yaml
-vectorSync:
+semanticSearch:
   enabled: true
 
 qdrant:
@@ -689,7 +708,9 @@ Readiness (returns 200 if ready, 503 if not ready):
 
 1. **Connection refused to Nextcloud**
    - Verify `nextcloud.host` is accessible from the Kubernetes cluster
+   - For OAuth mode: Ensure MCP server can reach OIDC discovery endpoints (token, JWKS, introspection, userinfo URLs)
    - Check network policies and firewall rules
+   - Note: Do not use internal Docker hostnames (like `http://app:80`) for `nextcloud.host` - use externally resolvable URLs
 
 2. **Authentication failures**
    - For basic auth: verify username/password are correct

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

@@ -69,12 +69,12 @@ Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentic
    {{- end }}
 {{- end }}
 
-{{- if .Values.vectorSync.enabled }}
+{{- if .Values.semanticSearch.enabled }}
 
-5. Vector Search & Semantic Capabilities:
-   - Vector Sync: Enabled
-   - Scan Interval: {{ .Values.vectorSync.scanInterval }}s
-   - Processor Workers: {{ .Values.vectorSync.processorWorkers }}
+5. Semantic Search & Vector Capabilities:
+   - Semantic Search: Enabled
+   - Scan Interval: {{ .Values.semanticSearch.scanInterval }}s
+   - Processor Workers: {{ .Values.semanticSearch.processorWorkers }}
    {{- if .Values.qdrant.enabled }}
    - Qdrant: Deployed as subchart ({{ .Release.Name }}-qdrant:6333)
    {{- else }}
@@ -120,6 +120,55 @@ Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentic
    The dashboard JSON is available in the chart at charts/nextcloud-mcp-server/dashboards/nextcloud-mcp-server.json
 {{- end }}
 
+{{- $legacyMultiUserBasic := eq (include "nextcloud-mcp-server.legacyMultiUserBasicPersistence" .) "true" }}
+{{- $legacyQdrant := eq (include "nextcloud-mcp-server.legacyQdrantPersistence" .) "true" }}
+{{- if or $legacyMultiUserBasic $legacyQdrant }}
+
+================================================================================
+                         DEPRECATION WARNING
+================================================================================
+
+You are using deprecated persistence configuration that will be removed in a
+future release. Your deployment will continue to work, but please migrate to
+the new unified dataStorage configuration.
+
+Deprecated settings detected:
+{{- if $legacyMultiUserBasic }}
+  - auth.multiUserBasic.persistence.* (currently enabled)
+{{- end }}
+{{- if $legacyQdrant }}
+  - qdrant.localPersistence.* (currently enabled)
+{{- end }}
+
+To migrate, update your values.yaml:
+
+  dataStorage:
+    enabled: true
+{{- if $legacyMultiUserBasic }}
+    size: {{ .Values.auth.multiUserBasic.persistence.size }}
+{{- else if $legacyQdrant }}
+    size: {{ .Values.qdrant.localPersistence.size }}
+{{- end }}
+    # storageClass: ""  # Optional: specify storage class
+    # existingClaim: "" # Optional: use existing PVC to preserve data
+
+After migrating, remove the deprecated settings:
+{{- if $legacyMultiUserBasic }}
+  - auth.multiUserBasic.persistence.enabled
+  - auth.multiUserBasic.persistence.size
+  - auth.multiUserBasic.persistence.storageClass
+  - auth.multiUserBasic.persistence.accessMode
+{{- end }}
+{{- if $legacyQdrant }}
+  - qdrant.localPersistence.enabled
+  - qdrant.localPersistence.size
+  - qdrant.localPersistence.storageClass
+  - qdrant.localPersistence.accessMode
+{{- end }}
+
+================================================================================
+{{- end }}
+
 For more information and documentation:
 - GitHub: https://github.com/cbcoutinho/nextcloud-mcp-server
 - Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme

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

@@ -72,6 +72,28 @@ Create the name of the secret to use for basic auth
 {{- end }}
 {{- end }}
 
+{{/*
+Create the name of the secret to use for multi-user basic auth
+*/}}
+{{- define "nextcloud-mcp-server.multiUserBasicSecretName" -}}
+{{- if .Values.auth.multiUserBasic.existingSecret }}
+{{- .Values.auth.multiUserBasic.existingSecret }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-multi-user-basic
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the PVC to use for multi-user basic token storage
+*/}}
+{{- define "nextcloud-mcp-server.multiUserBasicPvcName" -}}
+{{- if .Values.auth.multiUserBasic.persistence.existingClaim }}
+{{- .Values.auth.multiUserBasic.persistence.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-token-storage
+{{- end }}
+{{- end }}
+
 {{/*
 Create the name of the secret to use for OAuth
 */}}
@@ -105,6 +127,55 @@ Create the name of the PVC to use for Qdrant local persistent storage
 {{- end }}
 {{- end }}
 
+{{/*
+Create the name of the PVC to use for /app/data storage
+*/}}
+{{- define "nextcloud-mcp-server.dataStoragePvcName" -}}
+{{- if .Values.dataStorage.existingClaim }}
+{{- .Values.dataStorage.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-data-storage
+{{- end }}
+{{- end }}
+
+{{/*
+Determine if data storage PVC should be enabled (backward compatible)
+Checks new dataStorage.enabled OR legacy persistence configs
+*/}}
+{{- define "nextcloud-mcp-server.dataStorageEnabled" -}}
+{{- if .Values.dataStorage.enabled -}}
+true
+{{- else if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled -}}
+true
+{{- else if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled -}}
+true
+{{- else -}}
+false
+{{- end -}}
+{{- end }}
+
+{{/*
+Check if legacy multi-user-basic persistence config is being used
+*/}}
+{{- define "nextcloud-mcp-server.legacyMultiUserBasicPersistence" -}}
+{{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled (not .Values.dataStorage.enabled) -}}
+true
+{{- else -}}
+false
+{{- end -}}
+{{- end }}
+
+{{/*
+Check if legacy qdrant persistence config is being used
+*/}}
+{{- define "nextcloud-mcp-server.legacyQdrantPersistence" -}}
+{{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled (not .Values.dataStorage.enabled) -}}
+true
+{{- else -}}
+false
+{{- end -}}
+{{- end }}
+
 {{/*
 Return the MCP server port
 */}}

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

@@ -68,7 +68,7 @@ spec:
             - name: NEXTCLOUD_HOST
               value: {{ .Values.nextcloud.host | quote }}
             {{- if eq .Values.auth.mode "basic" }}
-            # Basic auth mode
+            # Basic auth mode (single-user)
             - name: NEXTCLOUD_USERNAME
               valueFrom:
                 secretKeyRef:
@@ -79,6 +79,41 @@ spec:
                 secretKeyRef:
                   name: {{ include "nextcloud-mcp-server.basicAuthSecretName" . }}
                   key: {{ .Values.auth.basic.passwordKey }}
+            {{- else if eq .Values.auth.mode "multi-user-basic" }}
+            # Multi-user BasicAuth mode (pass-through)
+            - name: ENABLE_MULTI_USER_BASIC_AUTH
+              value: "true"
+            - name: NEXTCLOUD_MCP_SERVER_URL
+              value: {{ include "nextcloud-mcp-server.mcpServerUrl" . | quote }}
+            - name: NEXTCLOUD_PUBLIC_ISSUER_URL
+              value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
+            {{- if .Values.auth.multiUserBasic.enableOfflineAccess }}
+            # Background operations with app passwords (replaces deprecated ENABLE_OFFLINE_ACCESS)
+            - name: ENABLE_BACKGROUND_OPERATIONS
+              value: "true"
+            - name: TOKEN_STORAGE_DB
+              value: {{ .Values.auth.multiUserBasic.tokenStorageDb | quote }}
+            - name: TOKEN_ENCRYPTION_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.multiUserBasicSecretName" . }}
+                  key: {{ .Values.auth.multiUserBasic.tokenEncryptionKeyKey }}
+            - name: NEXTCLOUD_OIDC_SCOPES
+              value: {{ .Values.auth.multiUserBasic.scopes | quote }}
+            {{- if or .Values.auth.multiUserBasic.clientId .Values.auth.multiUserBasic.existingSecret }}
+            # Static OAuth credentials (optional - uses DCR if not provided)
+            - name: NEXTCLOUD_OIDC_CLIENT_ID
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.multiUserBasicSecretName" . }}
+                  key: {{ .Values.auth.multiUserBasic.clientIdKey }}
+            - name: NEXTCLOUD_OIDC_CLIENT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.multiUserBasicSecretName" . }}
+                  key: {{ .Values.auth.multiUserBasic.clientSecretKey }}
+            {{- end }}
+            {{- end }}
             {{- else if eq .Values.auth.mode "oauth" }}
             # OAuth mode
             - name: NEXTCLOUD_MCP_SERVER_URL
@@ -87,7 +122,7 @@ spec:
               value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
             - name: NEXTCLOUD_OIDC_SCOPES
               value: {{ .Values.auth.oauth.scopes | quote }}
-            {{- if .Values.auth.oauth.clientId }}
+            {{- if or .Values.auth.oauth.clientId .Values.auth.oauth.existingSecret }}
             - name: NEXTCLOUD_OIDC_CLIENT_ID
               valueFrom:
                 secretKeyRef:
@@ -147,16 +182,16 @@ spec:
               value: {{ .Values.documentProcessing.custom.types | quote }}
             {{- end }}
             {{- end }}
-            # Vector Sync
-            - name: VECTOR_SYNC_ENABLED
-              value: {{ .Values.vectorSync.enabled | quote }}
-            {{- if .Values.vectorSync.enabled }}
+            # Semantic Search (replaces deprecated VECTOR_SYNC_ENABLED)
+            - name: ENABLE_SEMANTIC_SEARCH
+              value: {{ .Values.semanticSearch.enabled | quote }}
+            {{- if .Values.semanticSearch.enabled }}
             - name: VECTOR_SYNC_SCAN_INTERVAL
-              value: {{ .Values.vectorSync.scanInterval | quote }}
+              value: {{ .Values.semanticSearch.scanInterval | quote }}
             - name: VECTOR_SYNC_PROCESSOR_WORKERS
-              value: {{ .Values.vectorSync.processorWorkers | quote }}
+              value: {{ .Values.semanticSearch.processorWorkers | quote }}
             - name: VECTOR_SYNC_QUEUE_MAX_SIZE
-              value: {{ .Values.vectorSync.queueMaxSize | quote }}
+              value: {{ .Values.semanticSearch.queueMaxSize | quote }}
             {{- end }}
             # Document Chunking (always set, used by vector sync processor)
             - name: DOCUMENT_CHUNK_SIZE
@@ -251,10 +286,8 @@ spec:
             - name: oauth-storage
               mountPath: /app/.oauth
             {{- end }}
-            {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
-            - name: qdrant-data
+            - name: data-storage
               mountPath: /app/data
-            {{- end }}
             {{- with .Values.volumeMounts }}
             {{- toYaml . | nindent 12 }}
             {{- end }}
@@ -266,10 +299,12 @@ spec:
           persistentVolumeClaim:
             claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
         {{- end }}
-        {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
-        - name: qdrant-data
+        - name: data-storage
+        {{- if eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true" }}
           persistentVolumeClaim:
-            claimName: {{ include "nextcloud-mcp-server.qdrantPvcName" . }}
+            claimName: {{ include "nextcloud-mcp-server.dataStoragePvcName" . }}
+        {{- else }}
+          emptyDir: {}
         {{- end }}
         {{- with .Values.volumes }}
         {{- toYaml . | nindent 8 }}

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

@@ -16,20 +16,34 @@ spec:
       storage: {{ .Values.auth.oauth.persistence.size }}
 {{- end }}
 ---
-{{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled (not .Values.qdrant.localPersistence.existingClaim) }}
+{{- if and (eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true") (not .Values.dataStorage.existingClaim) }}
+{{- $legacyMultiUserBasic := eq (include "nextcloud-mcp-server.legacyMultiUserBasicPersistence" .) "true" }}
+{{- $legacyQdrant := eq (include "nextcloud-mcp-server.legacyQdrantPersistence" .) "true" }}
+{{- $accessMode := .Values.dataStorage.accessMode }}
+{{- $storageClass := .Values.dataStorage.storageClass }}
+{{- $size := .Values.dataStorage.size }}
+{{- if $legacyMultiUserBasic }}
+{{- $accessMode = .Values.auth.multiUserBasic.persistence.accessMode }}
+{{- $storageClass = .Values.auth.multiUserBasic.persistence.storageClass }}
+{{- $size = .Values.auth.multiUserBasic.persistence.size }}
+{{- else if $legacyQdrant }}
+{{- $accessMode = .Values.qdrant.localPersistence.accessMode }}
+{{- $storageClass = .Values.qdrant.localPersistence.storageClass }}
+{{- $size = .Values.qdrant.localPersistence.size }}
+{{- end }}
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
-  name: {{ include "nextcloud-mcp-server.fullname" . }}-qdrant-data
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-data-storage
   labels:
     {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
 spec:
   accessModes:
-    - {{ .Values.qdrant.localPersistence.accessMode }}
-  {{- if .Values.qdrant.localPersistence.storageClass }}
-  storageClassName: {{ .Values.qdrant.localPersistence.storageClass }}
+    - {{ $accessMode }}
+  {{- if $storageClass }}
+  storageClassName: {{ $storageClass }}
   {{- end }}
   resources:
     requests:
-      storage: {{ .Values.qdrant.localPersistence.size }}
+      storage: {{ $size }}
 {{- end }}

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

@@ -13,6 +13,24 @@ data:
 {{- end }}
 {{- end }}
 ---
+{{- if eq .Values.auth.mode "multi-user-basic" }}
+{{- if and .Values.auth.multiUserBasic.enableOfflineAccess (not .Values.auth.multiUserBasic.existingSecret) }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-multi-user-basic
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.auth.multiUserBasic.tokenEncryptionKeyKey }}: {{ .Values.auth.multiUserBasic.tokenEncryptionKey | b64enc | quote }}
+  {{- if .Values.auth.multiUserBasic.clientId }}
+  {{ .Values.auth.multiUserBasic.clientIdKey }}: {{ .Values.auth.multiUserBasic.clientId | b64enc | quote }}
+  {{ .Values.auth.multiUserBasic.clientSecretKey }}: {{ .Values.auth.multiUserBasic.clientSecret | b64enc | quote }}
+  {{- end }}
+{{- end }}
+{{- end }}
+---
 {{- if eq .Values.auth.mode "oauth" }}
 {{- if and .Values.auth.oauth.clientId (not .Values.auth.oauth.existingSecret) }}
 apiVersion: v1

charts/nextcloud-mcp-server/values.yaml

@@ -26,21 +26,29 @@ nextcloud:
   # 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
+  # Public issuer URL for browser-accessible OAuth authorization endpoints (OAuth mode only)
+  # ONLY used to make authorization endpoints accessible to users' browsers
+  # All server-to-server communication (token endpoint, JWKS, introspection, userinfo)
+  # uses URLs from OIDC discovery without any rewriting
+  #
+  # Use case: When MCP server accesses Nextcloud at one URL but browsers need a different
+  # public URL for OAuth login (e.g., server uses internal DNS, browsers use public domain)
+  #
+  # If not specified, defaults to nextcloud.host (works when MCP server and browsers
+  # both access Nextcloud at the same URL)
   # Example: https://cloud.example.com
   publicIssuerUrl: ""
 
 # Authentication configuration
-# Choose either basic auth OR oauth (not both)
+# Choose one mode: "basic", "multi-user-basic", or "oauth"
 auth:
-  # Authentication mode: "basic" or "oauth"
-  # basic: Uses username/password (recommended for most users)
+  # Authentication mode: "basic", "multi-user-basic", or "oauth"
+  # basic: Single-user with username/password (recommended for personal use)
+  # multi-user-basic: Multi-user with BasicAuth pass-through (credentials in request headers)
   # oauth: Uses OAuth2/OIDC (experimental, requires patches)
   mode: basic
 
-  # Basic authentication settings
+  # Basic authentication settings (single-user mode)
   basic:
     # Nextcloud username (ignored if existingSecret is set)
     username: ""
@@ -58,6 +66,47 @@ auth:
     usernameKey: "username"
     passwordKey: "password"
 
+  # Multi-user BasicAuth settings (pass-through mode)
+  # Users provide credentials in request headers (Authorization: Basic ...)
+  # Server optionally stores app passwords for background operations
+  multiUserBasic:
+    # Enable offline access (background operations using app passwords via Astrolabe)
+    # When enabled, requires token encryption key. OAuth client credentials are optional (uses DCR if not provided)
+    enableOfflineAccess: false
+    # Token encryption key (required if enableOfflineAccess: true, ignored if existingSecret is set)
+    # Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+    tokenEncryptionKey: ""
+    # Token storage database path
+    tokenStorageDb: "/app/data/tokens.db"
+    # OAuth client credentials (optional - uses Dynamic Client Registration if not provided)
+    # Only needed if enableOfflineAccess: true
+    clientId: ""
+    clientSecret: ""
+    # OAuth scopes to request (space-separated)
+    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"
+    # Use existing secret for multi-user basic auth credentials
+    # If set, tokenEncryptionKey, clientId, and clientSecret above are ignored
+    # Secret should contain keys specified in the *Key fields below
+    # Example:
+    #   kubectl create secret generic my-multiuser-creds \
+    #     --from-literal=token_encryption_key=ESF1BvEQ... \
+    #     --from-literal=client_id=my-client-id \
+    #     --from-literal=client_secret=my-client-secret
+    existingSecret: ""
+    # Keys in the existing secret
+    tokenEncryptionKeyKey: "token_encryption_key"
+    clientIdKey: "client_id"
+    clientSecretKey: "client_secret"
+    # Persistent storage for token database
+    persistence:
+      enabled: true
+      # Storage class (leave empty for default)
+      storageClass: ""
+      accessMode: ReadWriteOnce
+      size: 100Mi
+      # Use existing PVC
+      existingClaim: ""
+
   # OAuth2/OIDC settings (experimental)
   oauth:
     # OAuth token type: "jwt" or "opaque"
@@ -90,6 +139,27 @@ auth:
       # Use existing PVC
       existingClaim: ""
 
+# Data Storage Configuration
+# Persistent volume for /app/data directory
+# Used for: token databases, qdrant persistent storage, and any app data
+# When disabled, uses emptyDir (non-persistent, but still writable)
+dataStorage:
+  # Enable persistent storage for /app/data
+  # Set to true when using:
+  # - Multi-user basic auth with offline access (stores tokens.db)
+  # - Qdrant persistent mode (stores vector database)
+  # - Any feature requiring persistent app data
+  # Set to false for basic auth without persistence (uses emptyDir)
+  enabled: false
+  # Storage class (leave empty for default)
+  storageClass: ""
+  accessMode: ReadWriteOnce
+  # Size for data storage (should accommodate tokens.db and/or qdrant data)
+  # Recommended: 1Gi minimum, 5Gi for production with qdrant
+  size: 1Gi
+  # Use existing PVC
+  existingClaim: ""
+
 # MCP server configuration
 mcp:
   # Transport mode (default: streamable-http for SSE)
@@ -316,10 +386,11 @@ extraEnvFrom: []
 # - secretRef:
 #     name: my-secret
 
-# Vector Sync Configuration
-# Background synchronization of Nextcloud content into vector database for semantic search
-vectorSync:
-  # Enable background vector synchronization
+# Semantic Search Configuration
+# Enable semantic search with BM25 hybrid search and background synchronization
+# of Nextcloud content into vector database
+semanticSearch:
+  # Enable semantic search and background vector synchronization
   enabled: false
   # Scan interval in seconds (how often to check for changes)
   scanInterval: 3600
@@ -330,7 +401,7 @@ vectorSync:
 
 # Document Chunking Configuration
 # Controls how documents are split into chunks before embedding
-# Only relevant when vectorSync.enabled is true
+# Only relevant when semanticSearch.enabled is true
 documentChunking:
   # Number of words per chunk (default: 512)
   # Smaller chunks (256-384): Better for precise searches, more chunks to store

docker-compose.ci.yml

@@ -0,0 +1,25 @@
+# CI-specific overrides for RAG evaluation pipeline
+# This file is used by the rag-evaluation.yml workflow to configure the MCP
+# container with OpenAI/GitHub Models API for vector embeddings.
+#
+# Usage:
+#   docker compose -f docker-compose.yml -f docker-compose.ci.yml up
+#
+# Environment variables (set in CI workflow):
+#   OPENAI_API_KEY - API key for embeddings (GitHub Models uses GITHUB_TOKEN)
+#   OPENAI_BASE_URL - API endpoint (e.g., https://models.github.ai/inference)
+#   OPENAI_EMBEDDING_MODEL - Model name (e.g., openai/text-embedding-3-small)
+#   OPENAI_GENERATION_MODEL - Model name for generation (e.g., openai/gpt-4o-mini)
+
+services:
+  mcp:
+    environment:
+      # OpenAI provider configuration (required for CI vector sync)
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - OPENAI_BASE_URL=${OPENAI_BASE_URL:-https://models.github.ai/inference}
+      - OPENAI_EMBEDDING_MODEL=${OPENAI_EMBEDDING_MODEL:-openai/text-embedding-3-small}
+      - OPENAI_GENERATION_MODEL=${OPENAI_GENERATION_MODEL:-openai/gpt-4o-mini}
+      # Faster sync for CI
+      - VECTOR_SYNC_SCAN_INTERVAL=${VECTOR_SYNC_SCAN_INTERVAL:-5}
+      # Enable document processing for PDF parsing
+      - ENABLE_DOCUMENT_PROCESSING=true

docker-compose.yml

@@ -3,11 +3,13 @@ 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:1cac8492bd78b1ec693238dc600be173397efd7b55eabc725abc281dc855b482
+    image: docker.io/library/mariadb:lts@sha256:8164f184d16c30e2f159e30518113667b796306dff0fe558876ab1ff521a682f
     restart: always
     command: --transaction-isolation=READ-COMMITTED
     volumes:
       - db:/var/lib/mysql
+    ports:
+      - 127.0.0.1:3306:3306
     environment:
       - MYSQL_ROOT_PASSWORD=password
       - MYSQL_PASSWORD=password
@@ -17,14 +19,14 @@ 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:5013e94192ef18a5d8368179c7522e5300f9265cc339cadac76c7b93303a2752
+    image: docker.io/library/redis:alpine@sha256:fd83658b0e40e2164617d262f13c02ca9ee9e1e6b276fd2fa06617e09bd5c780
     restart: always
 
   app:
-    image: docker.io/library/nextcloud:32.0.1@sha256:d572839eeb693026d72a0c6aa48076df0bb8930797ea321e604936ef7189d06e
+    image: docker.io/library/nextcloud:32.0.6@sha256:0e1084cc59df77bec7d6bb29d9ac6939da8372512237a9c51f74ff0a970524f2
     restart: always
     ports:
-      - 0.0.0.0:8080:80
+      - 127.0.0.1:8080:80
     depends_on:
       - redis
       - db
@@ -34,7 +36,7 @@ services:
       - ./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
+      #- ./third_party:/opt/apps:ro
     environment:
       - NEXTCLOUD_TRUSTED_DOMAINS=app
       - NEXTCLOUD_ADMIN_USER=admin
@@ -51,14 +53,14 @@ services:
       retries: 30
 
   recipes:
-    image: docker.io/library/nginx:alpine@sha256:b3c656d55d7ad751196f21b7fd2e8d4da9cb430e32f646adcf92441b72f82b14
+    image: docker.io/library/nginx:alpine@sha256:5878d06ae4c83d73285438255f705bb3f9a736f41cd24876ed25bb33faf76c7d
     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
+    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:3b9280eb9aa53d76a8f4a2465400ae747774d4bfd71dd73d603353b0b55c435d
     restart: always
     ports:
       - 127.0.0.1:8002:8000
@@ -85,8 +87,8 @@ services:
       - NEXTCLOUD_PASSWORD=admin
       - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
 
-      # Vector sync configuration (ADR-007)
-      - VECTOR_SYNC_ENABLED=true
+      # Semantic search configuration (ADR-007, ADR-021)
+      #- ENABLE_SEMANTIC_SEARCH=true
       - VECTOR_SYNC_SCAN_INTERVAL=60
       - VECTOR_SYNC_PROCESSOR_WORKERS=1
 
@@ -122,6 +124,40 @@ services:
       # - DOCUMENT_CHUNK_SIZE=512      # Words per chunk (default: 512)
       # - DOCUMENT_CHUNK_OVERLAP=50    # Overlapping words (default: 50, recommended: 10-20% of chunk size)
 
+  mcp-multi-user-basic:
+    build: .
+    restart: always
+    command: ["--transport", "streamable-http"]
+    depends_on:
+      app:
+        condition: service_healthy
+    ports:
+      - 127.0.0.1:8003:8000
+    environment:
+      # Multi-user BasicAuth pass-through mode (ADR-020)
+      - NEXTCLOUD_HOST=http://app:80
+      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8003
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+      - ENABLE_MULTI_USER_BASIC_AUTH=true
+      - ENABLE_BACKGROUND_OPERATIONS=true
+
+      # Token storage (required for middleware initialization)
+      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      - ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+
+      # OAuth credentials for background sync (optional - uses DCR if not provided)
+      # Uncomment to avoid DCR:
+      # - NEXTCLOUD_OIDC_CLIENT_ID=your_client_id
+      # - NEXTCLOUD_OIDC_CLIENT_SECRET=your_client_secret
+
+      # NO admin credentials - credentials come from client Authorization header
+    volumes:
+      - multi-user-basic-data:/app/data
+
   mcp-oauth:
     build: .
     command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
@@ -142,7 +178,7 @@ services:
       - 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
+      - ENABLE_BACKGROUND_OPERATIONS=true
       - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
       - TOKEN_STORAGE_DB=/app/data/tokens.db
 
@@ -150,6 +186,19 @@ services:
       # Tokens must contain BOTH MCP and Nextcloud audiences
       # No token exchange needed - tokens work for both MCP auth and Nextcloud APIs
 
+      # Semantic search configuration (ADR-007, ADR-021)
+      - ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+
+      # Qdrant configuration - persistent local storage
+      - QDRANT_LOCATION=/app/data/qdrant
+
+      # Embedding provider for vector sync (use Simple provider as fallback)
+      # Ollama not available in CI/test environments
+      # - OLLAMA_BASE_URL=http://ollama:11434
+      # - OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
       # 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)
@@ -158,7 +207,7 @@ services:
       - oauth-tokens:/app/data
 
   keycloak:
-    image: quay.io/keycloak/keycloak:26.4.5@sha256:653852bfdea2be6e958b9e90a976eff1c6de34edd55f2f679bdc48ef16bc528e
+    image: quay.io/keycloak/keycloak:26.5.3@sha256:5a236ae4dd8ece77490115bace15a11a4d15e9cbcf58a490b95a7da2cd71d32a
     command:
       - "start-dev"
       - "--import-realm"
@@ -206,7 +255,7 @@ services:
       - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888/realms/nextcloud-mcp
 
       # Refresh token storage (ADR-002 Tier 1 & 2)
-      - ENABLE_OFFLINE_ACCESS=true
+      - ENABLE_BACKGROUND_OPERATIONS=true
       - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
       - TOKEN_STORAGE_DB=/app/data/tokens.db
 
@@ -224,8 +273,28 @@ services:
       - keycloak-tokens:/app/data
       - keycloak-oauth-storage:/app/.oauth
 
+  # Smithery stateless deployment mode (ADR-016)
+  # Test with: docker compose --profile smithery up smithery
+  # Then: curl http://localhost:8081/.well-known/mcp-config
+  smithery:
+    build:
+      context: .
+      dockerfile: Dockerfile.smithery
+    restart: always
+    depends_on:
+      app:
+        condition: service_healthy
+    ports:
+      - 127.0.0.1:8081:8081
+    environment:
+      - SMITHERY_DEPLOYMENT=true
+      - ENABLE_SEMANTIC_SEARCH=false
+      - PORT=8081
+    profiles:
+      - smithery
+
   qdrant:
-    image: qdrant/qdrant:v1.16.0@sha256:1005201498cf927d835383d0f918b17d8c9da7db58550f169f694455e42d78f4
+    image: docker.io/qdrant/qdrant:v1.16.3@sha256:0425e3e03e7fd9b3dc95c4214546afe19de2eb2e28ca621441a56663ac6e1f46
     restart: always
     ports:
       - 127.0.0.1:6333:6333  # REST API
@@ -251,3 +320,4 @@ volumes:
   keycloak-oauth-storage:
   qdrant-data:
   mcp-data:
+  multi-user-basic-data:

docs/ADR-016-smithery-stateless-deployment.md

@@ -0,0 +1,492 @@
+# ADR-016: Smithery Stateless Deployment for Multi-User Public Nextcloud Instances
+
+**Status:** Proposed
+**Date:** 2025-01-22
+**Deciders:** Development Team
+**Related:** ADR-004 (OAuth), ADR-007 (Background Vector Sync), ADR-015 (Unified Provider)
+
+## Context
+
+[Smithery](https://smithery.ai) is a hosting platform and marketplace for MCP servers that provides:
+
+- **Discovery**: Marketplace listing for MCP servers
+- **Hosting**: Containerized deployment with auto-scaling
+- **Authentication UI**: OAuth flow presentation for users
+- **Session Configuration**: Per-user settings passed via URL parameters
+- **Observability**: Usage logs and monitoring
+
+### Current Architecture Limitations
+
+The current nextcloud-mcp-server architecture assumes a **self-hosted deployment** with:
+
+1. **Persistent Infrastructure**
+   - Qdrant vector database for semantic search
+   - Background sync worker for content indexing
+   - Refresh token storage for offline access
+
+2. **Single-Tenant Configuration**
+   - Environment variables configure one Nextcloud instance
+   - `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD`
+   - Or OAuth with a single IdP
+
+3. **Stateful Operations**
+   - Vector sync maintains index state across requests
+   - Token storage persists between sessions
+
+### Smithery Hosting Constraints
+
+Smithery-hosted containers are **stateless by design**:
+
+- No persistent storage between requests
+- No background workers or cron jobs
+- No databases (Qdrant, Redis, etc.)
+- Containers may be recycled at any time
+- Configuration passed per-session via URL parameters
+
+### Opportunity
+
+Many users have **publicly accessible Nextcloud instances** and want to:
+
+1. Try the MCP server without self-hosting infrastructure
+2. Connect multiple users to different Nextcloud instances
+3. Use basic Nextcloud tools without semantic search
+4. Benefit from Smithery's discovery and OAuth UI
+
+## Decision
+
+Implement a **stateless deployment mode** for Smithery that:
+
+1. **Disables stateful features** (vector sync, semantic search)
+2. **Creates clients per-session** from Smithery configuration
+3. **Supports multiple Nextcloud instances** via session config
+4. **Provides a useful subset of tools** that work without infrastructure
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Smithery-Hosted Stateless Mode                        │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  MCP Client                    Smithery                                  │
+│  (Cursor, Claude)              Infrastructure                            │
+│        │                            │                                    │
+│        │ 1. Connect                 │                                    │
+│        ├───────────────────────────►│                                    │
+│        │                            │                                    │
+│        │ 2. Config UI               │                                    │
+│        │◄───────────────────────────┤  User enters:                      │
+│        │    (Smithery presents)     │  - nextcloud_url                   │
+│        │                            │  - auth_mode (basic/oauth)         │
+│        │                            │  - credentials                     │
+│        │ 3. Tool call               │                                    │
+│        ├───────────────────────────►│                                    │
+│        │    + session config        │                                    │
+│        │                            │                                    │
+│        │                    ┌───────┴───────┐                            │
+│        │                    │  MCP Server   │                            │
+│        │                    │  Container    │                            │
+│        │                    │               │                            │
+│        │                    │ 4. Create     │                            │
+│        │                    │    client     │                            │
+│        │                    │    from       │                            │
+│        │                    │    config     │                            │
+│        │                    │      │        │                            │
+│        │                    │      ▼        │                            │
+│        │                    │ 5. Call       │                            │
+│        │                    │    Nextcloud  │───────► User's Nextcloud   │
+│        │                    │    API        │         Instance           │
+│        │                    │      │        │                            │
+│        │                    │      ▼        │                            │
+│        │ 6. Response        │ Return result │                            │
+│        │◄───────────────────┤               │                            │
+│        │                    └───────────────┘                            │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Session Configuration Schema
+
+```python
+from pydantic import BaseModel, Field
+
+class SmitheryConfigSchema(BaseModel):
+    """Configuration schema for Smithery session."""
+
+    # Required: Nextcloud instance
+    nextcloud_url: str = Field(
+        ...,
+        description="Your Nextcloud instance URL (e.g., https://cloud.example.com)"
+    )
+
+    # Authentication mode
+    auth_mode: str = Field(
+        "app_password",
+        description="Authentication method: 'app_password' or 'oauth'"
+    )
+
+    # App Password authentication (recommended for Smithery)
+    username: str | None = Field(
+        None,
+        description="Nextcloud username (required for app_password auth)"
+    )
+    app_password: str | None = Field(
+        None,
+        description="Nextcloud app password (Settings → Security → App passwords)"
+    )
+
+    # OAuth authentication (advanced)
+    # When auth_mode='oauth', Smithery handles the OAuth flow
+    # and passes the access token automatically
+```
+
+### Feature Matrix
+
+| Feature | Self-Hosted | Smithery Stateless |
+|---------|-------------|-------------------|
+| **Notes** | | |
+| List/Search notes | ✓ | ✓ |
+| Get/Create/Update notes | ✓ | ✓ |
+| Semantic search | ✓ | ✗ |
+| **Calendar** | | |
+| List calendars | ✓ | ✓ |
+| Get/Create events | ✓ | ✓ |
+| **Contacts** | | |
+| List address books | ✓ | ✓ |
+| Search/Get contacts | ✓ | ✓ |
+| **Files (WebDAV)** | | |
+| List/Download files | ✓ | ✓ |
+| Upload files | ✓ | ✓ |
+| Search files | ✓ | ✓ (keyword only) |
+| **Deck** | | |
+| List boards/cards | ✓ | ✓ |
+| Create/Update cards | ✓ | ✓ |
+| **Tables** | | |
+| List/Query tables | ✓ | ✓ |
+| Create/Update rows | ✓ | ✓ |
+| **Cookbook** | | |
+| List/Get recipes | ✓ | ✓ |
+| **Semantic Search** | | |
+| Vector search | ✓ | ✗ |
+| RAG answers | ✓ | ✗ |
+| **Background Sync** | | |
+| Auto-indexing | ✓ | ✗ |
+| Webhook sync | ✓ | ✗ |
+| **Admin UI (`/app`)** | | |
+| Vector sync status | ✓ | ✗ |
+| Vector visualization | ✓ | ✗ |
+| Webhook management | ✓ | ✗ |
+| Session management | ✓ | ✗ |
+
+### Implementation
+
+#### 1. Deployment Mode Detection
+
+```python
+# nextcloud_mcp_server/config.py
+
+class DeploymentMode(Enum):
+    SELF_HOSTED = "self_hosted"      # Full features, env-based config
+    SMITHERY_STATELESS = "smithery"  # Stateless, session-based config
+
+def get_deployment_mode() -> DeploymentMode:
+    """Detect deployment mode from environment."""
+    if os.getenv("SMITHERY_DEPLOYMENT") == "true":
+        return DeploymentMode.SMITHERY_STATELESS
+    return DeploymentMode.SELF_HOSTED
+```
+
+#### 2. Session-Based Client Factory
+
+```python
+# nextcloud_mcp_server/context.py
+
+async def get_client(ctx: Context) -> NextcloudClient:
+    """Get NextcloudClient - from session config or environment."""
+
+    mode = get_deployment_mode()
+
+    if mode == DeploymentMode.SMITHERY_STATELESS:
+        # Create client from Smithery session config
+        config = ctx.session_config
+        if not config:
+            raise McpError("Session configuration required")
+
+        return NextcloudClient(
+            base_url=config.nextcloud_url,
+            username=config.username,
+            password=config.app_password,
+        )
+    else:
+        # Existing behavior: from environment or OAuth context
+        return await _get_client_from_context(ctx)
+```
+
+#### 3. Conditional Tool Registration
+
+```python
+# nextcloud_mcp_server/app.py
+
+def create_mcp_server(mode: DeploymentMode) -> FastMCP:
+    """Create MCP server with mode-appropriate tools."""
+
+    mcp = FastMCP("Nextcloud MCP")
+
+    # Always register core tools
+    configure_notes_tools(mcp)
+    configure_calendar_tools(mcp)
+    configure_contacts_tools(mcp)
+    configure_webdav_tools(mcp)
+    configure_deck_tools(mcp)
+    configure_tables_tools(mcp)
+    configure_cookbook_tools(mcp)
+
+    # Only register stateful tools in self-hosted mode
+    if mode == DeploymentMode.SELF_HOSTED:
+        configure_semantic_tools(mcp)  # Requires Qdrant
+        register_oauth_tools(mcp)       # Requires token storage
+
+    return mcp
+```
+
+#### 4. Exclude Admin UI Routes
+
+The `/app` admin UI should **not be installed** in Smithery mode because:
+
+- **Vector sync status** - No vector sync in stateless mode
+- **Vector visualization** - No Qdrant to visualize
+- **Webhook management** - No webhook sync without background workers
+- **Session management** - No persistent sessions to manage
+
+```python
+# nextcloud_mcp_server/app.py
+
+def create_app(mode: DeploymentMode) -> Starlette:
+    """Create Starlette app with mode-appropriate routes."""
+
+    routes = [
+        Route("/health/live", health_live, methods=["GET"]),
+        Route("/health/ready", health_ready, methods=["GET"]),
+    ]
+
+    # Only mount admin UI in self-hosted mode
+    if mode == DeploymentMode.SELF_HOSTED:
+        browser_app = create_browser_app()
+        routes.append(
+            Route("/app", lambda r: RedirectResponse("/app/", status_code=307))
+        )
+        routes.append(Mount("/app", app=browser_app))
+        logger.info("Admin UI mounted at /app")
+    else:
+        logger.info("Admin UI disabled in Smithery stateless mode")
+
+    # Mount FastMCP at root
+    mcp_app = create_mcp_server(mode).streamable_http_app()
+    routes.append(Mount("/", app=mcp_app))
+
+    return Starlette(routes=routes, lifespan=starlette_lifespan)
+```
+
+**Endpoints by Mode:**
+
+| Endpoint | Self-Hosted | Smithery |
+|----------|-------------|----------|
+| `/mcp` | ✓ | ✓ |
+| `/health/live` | ✓ | ✓ |
+| `/health/ready` | ✓ | ✓ |
+| `/.well-known/mcp-config` | ✓ | ✓ |
+| `/app` | ✓ | ✗ |
+| `/app/vector-sync/status` | ✓ | ✗ |
+| `/app/vector-viz` | ✓ | ✗ |
+| `/app/webhooks` | ✓ | ✗ |
+
+#### 5. Smithery Integration Files
+
+**smithery.yaml:**
+```yaml
+runtime: "container"
+build:
+  dockerfile: "Dockerfile.smithery"
+  dockerBuildPath: "."
+startCommand:
+  type: "http"
+  configSchema:
+    type: "object"
+    required: ["nextcloud_url", "username", "app_password"]
+    properties:
+      nextcloud_url:
+        type: "string"
+        title: "Nextcloud URL"
+        description: "Your Nextcloud instance URL (e.g., https://cloud.example.com)"
+      username:
+        type: "string"
+        title: "Username"
+        description: "Your Nextcloud username"
+      app_password:
+        type: "string"
+        title: "App Password"
+        description: "Generate at Settings → Security → App passwords"
+  exampleConfig:
+    nextcloud_url: "https://cloud.example.com"
+    username: "alice"
+    app_password: "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
+```
+
+**Dockerfile.smithery:**
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+# Copy project files
+COPY pyproject.toml uv.lock ./
+COPY nextcloud_mcp_server ./nextcloud_mcp_server
+
+# Install dependencies (without vector/semantic extras)
+RUN uv sync --frozen --no-dev
+
+# Set Smithery mode
+ENV SMITHERY_DEPLOYMENT=true
+ENV VECTOR_SYNC_ENABLED=false
+
+# Smithery sets PORT=8081
+EXPOSE 8081
+
+CMD ["uv", "run", "python", "-m", "nextcloud_mcp_server.smithery_main"]
+```
+
+**nextcloud_mcp_server/smithery_main.py:**
+```python
+"""Smithery-specific entrypoint for stateless deployment."""
+
+import os
+import uvicorn
+from starlette.middleware.cors import CORSMiddleware
+
+from nextcloud_mcp_server.app import create_mcp_server
+from nextcloud_mcp_server.config import DeploymentMode
+
+def main():
+    # Force stateless mode
+    os.environ["SMITHERY_DEPLOYMENT"] = "true"
+    os.environ["VECTOR_SYNC_ENABLED"] = "false"
+
+    mcp = create_mcp_server(DeploymentMode.SMITHERY_STATELESS)
+    app = mcp.streamable_http_app()
+
+    # Add CORS for browser-based clients
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["GET", "POST", "OPTIONS"],
+        allow_headers=["*"],
+        expose_headers=["mcp-session-id", "mcp-protocol-version"],
+    )
+
+    # Smithery sets PORT environment variable
+    port = int(os.environ.get("PORT", 8081))
+    uvicorn.run(app, host="0.0.0.0", port=port)
+
+if __name__ == "__main__":
+    main()
+```
+
+### Security Considerations
+
+1. **App Passwords over User Passwords**
+   - Smithery config encourages app passwords (revocable, scoped)
+   - Documentation guides users to create dedicated app passwords
+   - App passwords can be revoked without changing main password
+
+2. **HTTPS Required**
+   - `nextcloud_url` must be HTTPS for production use
+   - Validation rejects HTTP URLs in Smithery mode
+
+3. **No Credential Storage**
+   - Credentials exist only for request duration
+   - No server-side persistence of user credentials
+   - Smithery handles secure config transmission
+
+4. **Scope Limitation**
+   - Stateless mode cannot access offline_access
+   - No background operations on user's behalf
+   - Clear user expectation: tools work during session only
+
+### Migration Path
+
+Users can start with Smithery stateless mode and migrate to self-hosted:
+
+1. **Try on Smithery** → Basic tools, no setup
+2. **Self-host for semantic search** → Add Qdrant, enable vector sync
+3. **Full deployment** → Background sync, webhooks, multi-user OAuth
+
+## Consequences
+
+### Positive
+
+1. **Lower barrier to entry** - Users can try without infrastructure
+2. **Multi-user support** - Each session connects to different Nextcloud
+3. **Smithery ecosystem** - Discovery, observability, OAuth UI
+4. **Clear feature tiers** - Stateless (simple) vs self-hosted (full)
+
+### Negative
+
+1. **No semantic search** - Key differentiator unavailable on Smithery
+2. **Per-request auth** - Credentials sent with each request
+3. **No offline access** - Cannot perform background operations
+4. **Maintenance burden** - Two deployment modes to support
+
+### Neutral
+
+1. **Feature subset** - May encourage users to self-host for full features
+2. **Documentation needs** - Clear guidance on mode differences required
+
+## Alternatives Considered
+
+### 1. External MCP Only
+
+**Approach:** Only support self-hosted external MCP registration on Smithery.
+
+**Rejected because:**
+- Higher barrier to entry for new users
+- Misses opportunity for Smithery marketplace visibility
+- Users want to try before committing to infrastructure
+
+### 2. Embedded Vector DB (SQLite-vec)
+
+**Approach:** Use SQLite with vector extensions for per-request indexing.
+
+**Rejected because:**
+- No persistence between requests anyway
+- Indexing latency too high for synchronous requests
+- Complexity without benefit in stateless context
+
+### 3. External Vector DB Service
+
+**Approach:** Connect to Pinecone/Weaviate Cloud from Smithery container.
+
+**Rejected because:**
+- Adds external dependency and cost
+- Per-user collections require complex multi-tenancy
+- Sync still impossible without background workers
+
+### 4. Hybrid: Smithery + User's Qdrant
+
+**Approach:** User provides their own Qdrant URL in session config.
+
+**Considered for future:**
+- Could enable semantic search for advanced users
+- Adds complexity to session config
+- Sync still requires external trigger (manual or webhook)
+
+## References
+
+- [Smithery Documentation](https://smithery.ai/docs)
+- [Smithery Session Configuration](https://smithery.ai/docs/build/session-config)
+- [Smithery External MCPs](https://smithery.ai/docs/build/external)
+- [MCP Streamable HTTP Transport](https://modelcontextprotocol.io/docs/concepts/transports)
+- [Nextcloud App Passwords](https://docs.nextcloud.com/server/latest/user_manual/en/session_management.html#app-passwords)

docs/ADR-017-mcp-tool-annotations.md

@@ -0,0 +1,506 @@
+# ADR-017: Add MCP Tool Annotations for Enhanced Client UX
+
+## Status
+
+Implemented
+
+## Context
+
+The MCP Python SDK supports tool annotations that provide behavioral hints and improved UX to MCP clients. Currently, our 101 tools across 10 modules lack these annotations, resulting in:
+
+- Snake_case function names displayed to users (e.g., "nc_notes_create_note" instead of "Create Note")
+- No behavioral hints for clients about read-only, destructive, or idempotent operations
+- Missing parameter descriptions for better auto-completion and inline help
+- Clients cannot optimize caching, warn before destructive operations, or retry safely
+
+### Available MCP Annotations
+
+The MCP SDK provides three types of annotations:
+
+#### 1. Tool Decorator Parameters
+```python
+@mcp.tool(
+    title="Human-Readable Name",
+    description="Tool description",  # Can also come from docstring
+    annotations=ToolAnnotations(...),
+    icons=[Icon(...)]  # Optional visual icons
+)
+```
+
+#### 2. ToolAnnotations Behavioral Hints
+```python
+from mcp.types import ToolAnnotations
+
+ToolAnnotations(
+    title="Alternative Title",  # Decorator title takes precedence
+    readOnlyHint=True,         # Tool doesn't modify data
+    destructiveHint=True,       # Tool may delete/overwrite data
+    idempotentHint=True,        # Repeated calls with same args are safe
+    openWorldHint=True          # Interacts with external entities
+)
+```
+
+#### 3. Parameter Descriptions
+```python
+from pydantic import Field
+
+async def tool(
+    param: str = Field(description="What this parameter does"),
+    ctx: Context
+):
+```
+
+### Idempotency Analysis
+
+**Important**: Idempotency means calling with **the same inputs** produces the same result.
+
+**NOT Idempotent** (different inputs each call):
+- **Updates with etag**: `update_note(id=1, title="X", etag="abc")` → etag changes to "def"
+  - Second call: `update_note(id=1, title="X", etag="abc")` → fails (etag mismatch)
+  - Different input (stale etag) → different result (error)
+- **Creates**: `create_note(title="X")` → creates note 1
+  - Second call → creates note 2 (different result)
+- **Append operations**: `append_content(id=1, text="X")` → adds X once
+  - Second call → adds X again (different result)
+
+**Idempotent**:
+- **Deletes**: `delete_note(id=1)` → note deleted
+  - Second call → 404 or success (same end state: note doesn't exist)
+  - Note: May return different status code, but end state is identical
+- **Full resource PUT without version control**: `write_file(path="/test.txt", content="Hello")` → file has "Hello"
+  - Second call → file still has "Hello" (same end state)
+  - Example: `nc_webdav_write_file` uses HTTP PUT without etags/version control
+- **Set operations**: `set_property(id=1, value="X")` → property = X
+  - Second call → property still = X (same result)
+  - Note: Nextcloud updates with etags use version control, so not idempotent
+
+**Read-Only** (always idempotent, never destructive):
+- All list, search, get operations
+
+## Decision
+
+Add annotations to all 101 tools in three phases:
+
+### Phase 1: Titles (Quick Win)
+Add human-readable titles to all tools:
+
+```python
+@mcp.tool(title="Create Note")
+async def nc_notes_create_note(...):
+```
+
+**Effort**: 2-3 hours
+**Impact**: Immediate UX improvement
+
+### Phase 2: ToolAnnotations (Behavioral Hints)
+Add annotations based on corrected categorization:
+
+```python
+# Read-only tools
+@mcp.tool(
+    title="Search Notes",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=True  # Nextcloud is external to MCP server
+    )
+)
+
+# Delete tools (idempotent: same end state)
+@mcp.tool(
+    title="Delete Note",
+    annotations=ToolAnnotations(
+        destructiveHint=True,
+        idempotentHint=True,  # Deleting deleted item = same end state
+        openWorldHint=True
+    )
+)
+
+# Create tools (not idempotent: creates multiple items)
+@mcp.tool(
+    title="Create Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,
+        openWorldHint=True
+    )
+)
+
+# Update tools with etag (not idempotent: etag changes)
+@mcp.tool(
+    title="Update Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # Etag required = different inputs each time
+        openWorldHint=True
+    )
+)
+
+# Append operations (not idempotent: adds content each time)
+@mcp.tool(
+    title="Append to Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,
+        openWorldHint=True
+    )
+)
+```
+
+**Effort**: 4-6 hours
+**Impact**: Better client behavior (caching, warnings, retry logic)
+
+### Phase 3: Parameter Descriptions
+Add Field() descriptions to parameters:
+
+```python
+from pydantic import Field
+
+@mcp.tool(title="Create Note", annotations=ToolAnnotations(idempotentHint=False))
+async def nc_notes_create_note(
+    title: str = Field(description="The title of the note"),
+    content: str = Field(description="Markdown content of the note"),
+    category: str = Field(description="Category or folder name for organizing"),
+    ctx: Context
+) -> CreateNoteResponse:
+```
+
+**Effort**: 6-8 hours
+**Impact**: Better auto-completion and inline help
+
+## Tool Categorization
+
+### Read-Only Tools (~40 tools)
+**Pattern**: List, search, get operations
+**Annotations**: `readOnlyHint=True`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_search_notes` → "Search Notes"
+- `nc_webdav_list_directory` → "List Files and Directories"
+- `nc_calendar_list_calendars` → "List Calendars"
+- `nc_contacts_get_contact` → "Get Contact"
+- `nc_semantic_search` → "Semantic Search"
+- `check_logged_in` → "Check Server Login Status"
+
+### Create Tools (~20 tools)
+**Pattern**: Create new resources
+**Annotations**: `idempotentHint=False`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_create_note` → "Create Note"
+- `nc_calendar_create_event` → "Create Calendar Event"
+- `nc_contacts_create_contact` → "Create Contact"
+- `deck_create_card` → "Create Kanban Card"
+- `nc_tables_create_row` → "Create Table Row"
+
+### Update Tools (~25 tools)
+**Pattern**: Modify existing resources with etag
+**Annotations**: `idempotentHint=False` (etag changes), `openWorldHint=True`
+
+Examples:
+- `nc_notes_update_note` → "Update Note"
+- `nc_calendar_update_event` → "Update Calendar Event"
+- `nc_contacts_update_contact` → "Update Contact"
+- `deck_update_card` → "Update Kanban Card"
+
+**Rationale**: Updates require etag, which changes after each update. Same parameters on second call will fail due to stale etag = NOT idempotent.
+
+### Append/Accumulate Tools (~5 tools)
+**Pattern**: Add content without replacing
+**Annotations**: `idempotentHint=False`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_append_content` → "Append to Note"
+
+**Rationale**: Each call adds content, changing the result = NOT idempotent.
+
+### Delete Tools (~10 tools)
+**Pattern**: Remove resources
+**Annotations**: `destructiveHint=True`, `idempotentHint=True`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_delete_note` → "Delete Note"
+- `nc_webdav_delete_resource` → "Delete File or Directory"
+- `nc_calendar_delete_event` → "Delete Calendar Event"
+- `nc_contacts_delete_contact` → "Delete Contact"
+
+**Rationale**: Deleting already-deleted item results in same end state (item doesn't exist) = idempotent. Status code may differ, but outcome is identical.
+
+### Special Cases
+
+#### OAuth Provisioning Tools
+```python
+# Not read-only but requires user interaction
+@mcp.tool(
+    title="Grant Server Access to Nextcloud",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        idempotentHint=False,  # Creates new OAuth session each time
+        openWorldHint=True
+    )
+)
+async def provision_nextcloud_access(ctx: Context):
+```
+
+#### Semantic Search (Closed World)
+```python
+@mcp.tool(
+    title="Semantic Search",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=False  # Searches only indexed Nextcloud data
+    )
+)
+async def nc_semantic_search(query: str, ctx: Context):
+```
+
+**Rationale**: Semantic search only queries pre-indexed Nextcloud content, not the "open world" like web search would.
+
+## Tool Priority Matrix
+
+### Critical Priority (~2 tools)
+OAuth tools required for server functionality:
+- `provision_nextcloud_access` → "Grant Server Access to Nextcloud"
+- `check_logged_in` → "Check Server Login Status"
+
+### High Priority (~50 tools)
+Most commonly used modules:
+- **Notes** (14 tools): Create, read, update, delete notes
+- **WebDAV** (13 tools): File operations
+- **Calendar** (15 tools): Events and todos
+- **Semantic Search** (6 tools): AI-powered search
+- **Contacts** (9 tools): Address book operations
+
+### Medium Priority (~35 tools)
+Secondary functionality:
+- **Deck** (9 tools): Kanban boards
+- **Tables** (7 tools): Structured data
+- **Sharing** (5 tools): File sharing
+
+### Low Priority (~14 tools)
+Less frequently used:
+- **Cookbook** (8 tools): Recipe management
+- **News** (6 tools): RSS feeds
+
+## Implementation Plan
+
+### Week 1: Phase 1 - Titles
+- Add human-readable titles to all 101 tools
+- Update tool name mapping in documentation
+- Manual test in MCP inspector
+
+### Week 2: Phase 2 - ToolAnnotations (High Priority)
+- Add annotations to Critical and High priority tools (~52 tools)
+- Focus on Notes, WebDAV, Calendar, Semantic, OAuth
+- Add unit tests validating annotation presence
+
+### Week 3: Phase 2 - ToolAnnotations (Medium/Low Priority)
+- Complete remaining tools (~49 tools)
+- Deck, Tables, Contacts, Cookbook, News
+- Update tool listings in README
+
+### Week 4: Phase 3 - Parameter Descriptions
+- Add Field() descriptions to Critical/High priority tools
+- Start with OAuth, Notes, WebDAV modules
+- Incremental completion over time
+
+## Benefits
+
+### For Users
+- **Clearer UI**: "Create Note" vs "nc_notes_create_note"
+- **Safety**: Warnings before destructive operations
+- **Better help**: Parameter descriptions in auto-completion
+- **Confidence**: Know which operations are safe to retry
+
+### For MCP Clients
+- **Caching**: Cache results from read-only tools
+- **Safety prompts**: Warn before destructiveHint=true
+- **Retry logic**: Safely retry idempotent operations
+- **UI organization**: Group by behavior (reads vs writes vs deletes)
+- **Performance**: Optimize based on hints
+
+### For Developers
+- **Self-documenting**: Behavior is explicit
+- **Consistency**: Standard patterns across codebase
+- **Testing**: Validate annotations match implementation
+- **Maintenance**: Clear expectations for new tools
+
+## Consequences
+
+### Positive
+- Immediate UX improvement with minimal effort
+- Clients can make smarter decisions
+- Self-documenting code
+- Follows MCP best practices
+
+### Negative
+- Initial effort to add annotations (12-15 hours total)
+- Must maintain annotations when adding new tools
+- Risk of incorrect annotations misleading clients
+
+### Neutral
+- Annotations are hints, not guarantees
+- Clients may ignore annotations
+- Backward compatible (additive change)
+
+### Mitigations
+- **Incorrect annotations**: Add tests validating behavior matches hints
+- **Maintenance burden**: Add to code review checklist and tool template
+- **Documentation**: Update CLAUDE.md with annotation guidelines
+
+## Examples
+
+### Complete Annotated Tool (Delete)
+
+```python
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+@mcp.tool(
+    title="Delete Note",
+    annotations=ToolAnnotations(
+        destructiveHint=True,   # Deletes data permanently
+        idempotentHint=True,    # Same end state (note doesn't exist)
+        openWorldHint=True      # Nextcloud is external
+    )
+)
+@require_scopes("notes:write")
+@instrument_tool
+async def nc_notes_delete_note(
+    note_id: int = Field(description="The ID of the note to delete permanently"),
+    ctx: Context
+) -> DeleteNoteResponse:
+    """Delete a note permanently (requires notes:write scope)"""
+    client = await get_client(ctx)
+    # ... implementation ...
+```
+
+### Complete Annotated Tool (Update)
+
+```python
+@mcp.tool(
+    title="Update Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,   # NOT idempotent: etag changes each update
+        openWorldHint=True
+    )
+)
+@require_scopes("notes:write")
+@instrument_tool
+async def nc_notes_update_note(
+    note_id: int = Field(description="The ID of the note to update"),
+    title: str | None = Field(
+        default=None,
+        description="New title (omit to keep current)"
+    ),
+    content: str | None = Field(
+        default=None,
+        description="New markdown content (omit to keep current)"
+    ),
+    category: str | None = Field(
+        default=None,
+        description="New category/folder (omit to keep current)"
+    ),
+    etag: str = Field(
+        description="ETag from get_note (prevents concurrent modification)"
+    ),
+    ctx: Context
+) -> UpdateNoteResponse:
+    """Update an existing note's title, content, or category.
+
+    The etag parameter is required to prevent overwriting concurrent changes.
+    Get the current ETag by first calling nc_notes_get_note.
+    If the note has been modified since you retrieved it, the update will fail.
+    """
+    client = await get_client(ctx)
+    # ... implementation ...
+```
+
+### Complete Annotated Tool (Read-Only)
+
+```python
+@mcp.tool(
+    title="Search Notes",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,    # Doesn't modify data
+        openWorldHint=True    # Queries Nextcloud
+    )
+)
+@require_scopes("notes:read")
+@instrument_tool
+async def nc_notes_search_notes(
+    query: str = Field(description="Search term to match in note titles or content"),
+    ctx: Context
+) -> SearchNotesResponse:
+    """Search notes by title or content, returning id, title, and category.
+
+    This is a read-only operation that searches across all user notes.
+    Use nc_notes_get_note to retrieve the full content of matching notes.
+    """
+    client = await get_client(ctx)
+    # ... implementation ...
+```
+
+## Testing Strategy
+
+### Unit Tests
+Add tests validating annotation presence and correctness:
+
+```python
+def test_notes_tools_have_annotations():
+    """Verify all notes tools have appropriate annotations."""
+    tools = get_registered_tools(mcp)
+
+    # Check create tool
+    create_tool = tools["nc_notes_create_note"]
+    assert create_tool.title == "Create Note"
+    assert create_tool.annotations.idempotentHint is False
+
+    # Check delete tool
+    delete_tool = tools["nc_notes_delete_note"]
+    assert delete_tool.title == "Delete Note"
+    assert delete_tool.annotations.destructiveHint is True
+    assert delete_tool.annotations.idempotentHint is True
+
+    # Check read-only tool
+    search_tool = tools["nc_notes_search_notes"]
+    assert search_tool.title == "Search Notes"
+    assert search_tool.annotations.readOnlyHint is True
+```
+
+### Integration Tests
+- Verify existing tests pass with annotations
+- Manual testing in MCP inspector/client
+
+### Documentation Updates
+- Update README tool listings with new titles
+- Add annotation guidelines to CLAUDE.md
+- Include examples in developer documentation
+
+## Resolved Questions
+
+1. **WebDAV write_file idempotency** (Resolved: 2025-12-11)
+   - **Decision**: Mark as `idempotentHint=True`
+   - **Rationale**: Uses HTTP PUT without version control. Writing same content to same path repeatedly produces identical end state, which is the definition of idempotency in HTTP semantics.
+
+2. **Semantic search openWorldHint** (Resolved: 2025-12-11)
+   - **Decision**: Mark as `openWorldHint=True`
+   - **Rationale**: For consistency with other Nextcloud tools. While the data being searched is "indexed/internal", Nextcloud itself is external to the MCP server. The fact that data is indexed is an implementation detail, not a fundamental difference from other Nextcloud queries.
+
+3. **Read-only with side effects**: Should tools that log analytics still be readOnlyHint=true?
+   - **Decision**: Yes. Logging/analytics are non-visible side effects that don't change user-observable state. Read-only refers to data modifications that affect the user's content.
+
+## Future Considerations
+
+1. **Icons**: Visual icons for tools (requires design work, deferred to future ADR)
+2. **Parameter descriptions**: Add Pydantic `Field(description=...)` for better auto-completion (Phase 3, future work)
+
+## References
+
+- MCP Python SDK: `/home/chris/Software/python-sdk/`
+- ToolAnnotations spec: `src/mcp/types.py:1247`
+- FastMCP decorator: `src/mcp/server/fastmcp/server.py:444`
+- Examples: `examples/fastmcp/parameter_descriptions.py`, `examples/fastmcp/icons_demo.py`
+
+## Decision Timeline
+
+- **Proposed**: 2025-12-11
+- **Reviewed**: 2025-12-11 (Self-review during implementation)
+- **Accepted**: 2025-12-11
+- **Implemented**: 2025-12-11 (Phase 1 & 2 complete)

docs/ADR-020-deployment-modes-and-configuration-validation.md

@@ -0,0 +1,342 @@
+# ADR-020: Deployment Modes and Configuration Validation
+
+**Status:** Accepted
+**Date:** 2025-12-20
+**Deciders:** Development Team
+**Related:** ADR-002 (Vector Sync), ADR-004 (Progressive Consent), ADR-019 (Multi-user BasicAuth)
+
+## Context
+
+The MCP server supports multiple deployment scenarios with different authentication methods, storage backends, and feature sets. Over time, the configuration system evolved to support ~500+ possible combinations across deployment modes, authentication patterns, and feature toggles. This complexity made it difficult to:
+
+1. Understand what configuration is required for a given deployment
+2. Debug configuration errors (validation scattered across multiple files)
+3. Provide helpful error messages when configuration is invalid
+4. Maintain clear boundaries between deployment modes
+
+**Problems Identified:**
+- No single source of truth for "what config is required for mode X"
+- Validation happening at 4+ different points (Settings.__post_init__, setup_oauth_config(), context helpers, starlette_lifespan)
+- Startup sequence unclear (OAuth setup before FastMCP creation, sync initialization errors)
+- Error messages generic ("X is required") without explaining which deployment mode triggered the requirement
+- Multiple overlapping decision trees (deployment mode, auth mode, features)
+
+## Decision
+
+We formalize five distinct deployment modes with explicit configuration requirements and implement centralized configuration validation.
+
+### Deployment Modes
+
+#### 1. Single-User BasicAuth
+
+**Use Case:** Personal Nextcloud instance, local development
+
+**Required Configuration:**
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password  # Or app password
+```
+
+**Optional Configuration:**
+```bash
+# Vector sync (semantic search)
+VECTOR_SYNC_ENABLED=true
+QDRANT_LOCATION=/path/to/qdrant  # Or QDRANT_URL for remote
+
+# Embeddings (optional - Simple provider used as fallback)
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Document processing
+DOCUMENT_CHUNK_SIZE=512
+DOCUMENT_CHUNK_OVERLAP=50
+```
+
+**Characteristics:**
+- Single shared NextcloudClient created at startup
+- No OAuth infrastructure needed
+- No multi-user support
+- Vector sync runs as single-user background task
+- Admin UI available at /app
+
+---
+
+#### 2. Multi-User BasicAuth Pass-Through
+
+**Use Case:** Internal deployment where users provide their own credentials, no background sync needed
+
+**Required Configuration:**
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+```
+
+**Optional Configuration:**
+```bash
+# For background sync (requires app passwords from Astrolabe)
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+VECTOR_SYNC_ENABLED=true
+# ... plus Qdrant and embedding config
+```
+
+**Conditional Requirements:**
+- If `ENABLE_OFFLINE_ACCESS=true`: requires `NEXTCLOUD_OIDC_CLIENT_ID`, `NEXTCLOUD_OIDC_CLIENT_SECRET`, `TOKEN_ENCRYPTION_KEY`, `TOKEN_STORAGE_DB`
+- If `VECTOR_SYNC_ENABLED=true`: requires `ENABLE_OFFLINE_ACCESS=true`
+
+**Characteristics:**
+- No OAuth for client authentication (uses BasicAuth in request headers)
+- BasicAuthMiddleware extracts credentials from Authorization header
+- Client created per-request from extracted credentials
+- Optional: Background sync using app passwords (via Astrolabe API)
+- Admin UI available at /app
+
+---
+
+#### 3. OAuth Single-Audience (Default)
+
+**Use Case:** Multi-user deployment with OAuth authentication, tokens work for both MCP and Nextcloud
+
+**Required Configuration:**
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+# No NEXTCLOUD_USERNAME/PASSWORD (triggers OAuth mode)
+```
+
+**Auto-Configured:**
+- OIDC discovery URL: `{NEXTCLOUD_HOST}/.well-known/openid-configuration`
+- Client credentials: Dynamic Client Registration (DCR) if available
+- Token storage: SQLite at `~/.oauth/clients.db`
+
+**Optional Configuration:**
+```bash
+# Static client credentials (instead of DCR)
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+
+# Offline access for background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+VECTOR_SYNC_ENABLED=true
+# ... plus Qdrant and embedding config
+
+# Scopes
+NEXTCLOUD_OIDC_SCOPES="openid profile email notes:read notes:write ..."
+```
+
+**Conditional Requirements:**
+- If `ENABLE_OFFLINE_ACCESS=true`: requires `TOKEN_ENCRYPTION_KEY`, `TOKEN_STORAGE_DB`
+- If `VECTOR_SYNC_ENABLED=true`: requires `ENABLE_OFFLINE_ACCESS=true`
+
+**Characteristics:**
+- Tokens contain both `aud: ["mcp-server", "nextcloud"]`
+- Pass token through to Nextcloud APIs (no exchange)
+- Client created per-request from token in Authorization header
+- Background sync uses refresh tokens (if offline_access enabled)
+- Admin UI available at /app
+
+---
+
+#### 4. OAuth Token Exchange (RFC 8693)
+
+**Use Case:** Multi-user deployment where MCP token is separate from Nextcloud token
+
+**Required Configuration:**
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+# No NEXTCLOUD_USERNAME/PASSWORD (triggers OAuth mode)
+```
+
+**Optional Configuration:**
+- Same as OAuth Single-Audience, plus:
+```bash
+TOKEN_EXCHANGE_CACHE_TTL=300  # Cache exchanged tokens
+```
+
+**Characteristics:**
+- Tokens contain only `aud: "mcp-server"`
+- MCP server exchanges token for Nextcloud token via RFC 8693
+- Exchanged tokens cached per-user
+- Client created per-request using exchanged token
+- Background sync uses refresh tokens (if offline_access enabled)
+
+---
+
+#### 5. Smithery Stateless
+
+**Use Case:** Multi-tenant SaaS deployment via Smithery platform
+
+**Required Configuration:**
+- None! Configuration comes from session URL params: `?nextcloud_url=...&username=...&app_password=...`
+
+**Forbidden Configuration:**
+- Must NOT set: `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD`, `ENABLE_MULTI_USER_BASIC_AUTH`, `ENABLE_TOKEN_EXCHANGE`, `ENABLE_OFFLINE_ACCESS`, `VECTOR_SYNC_ENABLED`, `NEXTCLOUD_OIDC_CLIENT_ID`, `NEXTCLOUD_OIDC_CLIENT_SECRET`
+
+**Characteristics:**
+- No persistent storage (stateless)
+- Client created per-request from session config
+- No vector sync (disabled)
+- No admin UI (no /app routes)
+- No OAuth infrastructure
+
+---
+
+### Configuration Validation
+
+**Implementation:** `nextcloud_mcp_server/config_validators.py`
+
+**Key Functions:**
+```python
+def detect_auth_mode(settings: Settings) -> AuthMode:
+    """Detect authentication mode from configuration.
+
+    Priority (most specific to most general):
+    1. Smithery (explicit flag)
+    2. Token exchange (most specific OAuth mode)
+    3. Multi-user BasicAuth
+    4. Single-user BasicAuth
+    5. OAuth single-audience (default OAuth mode)
+    """
+
+def validate_configuration(settings: Settings) -> tuple[AuthMode, list[str]]:
+    """Validate configuration for detected mode.
+
+    Returns:
+        Tuple of (detected_mode, list_of_errors)
+        Empty list means valid configuration.
+    """
+```
+
+**Validation Rules:**
+- **Required variables:** Must be set and non-empty
+- **Forbidden variables:** Must NOT be set (or must be False for booleans)
+- **Conditional requirements:** If feature X is enabled, requires variables Y and Z
+
+**Error Messages:**
+```
+Configuration validation failed for {mode} mode:
+  - [{mode}] Missing required configuration: NEXTCLOUD_HOST
+  - [{mode}] ENABLE_OFFLINE_ACCESS must be enabled when VECTOR_SYNC_ENABLED is true
+
+Mode: {mode}
+Description: {mode_description}
+
+Required configuration:
+  - VAR1
+  - VAR2
+
+Optional configuration:
+  - VAR3
+  - VAR4
+
+Conditional requirements:
+  When FEATURE is enabled:
+    - VAR5
+    - VAR6
+```
+
+**Integration:**
+- Validation runs at app startup in `get_app()` (app.py:1048-1062)
+- All errors reported before any initialization begins
+- Mode-specific error messages explain requirements
+- Validation uses the same Settings object used throughout the app
+
+### Configuration Matrix
+
+| Variable | Single BasicAuth | Multi BasicAuth | OAuth Single | OAuth Exchange | Smithery |
+|----------|------------------|-----------------|--------------|----------------|----------|
+| **NEXTCLOUD_HOST** | Required | Required | Required | Required | Forbidden |
+| **NEXTCLOUD_USERNAME** | Required | Forbidden | Forbidden | Forbidden | Forbidden |
+| **NEXTCLOUD_PASSWORD** | Required | Forbidden | Forbidden | Forbidden | Forbidden |
+| **ENABLE_MULTI_USER_BASIC_AUTH** | Forbidden | Required | Forbidden | Forbidden | Forbidden |
+| **ENABLE_TOKEN_EXCHANGE** | Forbidden | Forbidden | Forbidden | Required | Forbidden |
+| **ENABLE_OFFLINE_ACCESS** | Optional\* | Optional\* | Optional\* | Optional\* | Forbidden |
+| **TOKEN_ENCRYPTION_KEY** | If offline | If offline | If offline | If offline | Forbidden |
+| **TOKEN_STORAGE_DB** | If offline | If offline | If offline | If offline | Forbidden |
+| **OIDC_CLIENT_ID** | Forbidden | If offline | Optional\*\* | Optional\*\* | Forbidden |
+| **OIDC_CLIENT_SECRET** | Forbidden | If offline | Optional\*\* | Optional\*\* | Forbidden |
+| **VECTOR_SYNC_ENABLED** | Optional | Optional | Optional | Optional | Forbidden |
+| **QDRANT_URL/LOCATION** | If vector | If vector | If vector | If vector | Forbidden |
+| **OLLAMA_BASE_URL/OPENAI_API_KEY** | Optional | Optional | Optional | Optional | Forbidden |
+
+\* Only enables background sync for semantic search
+\*\* Uses DCR if not provided
+
+## Consequences
+
+### Positive
+
+1. **Clarity:** Single function to detect mode from config
+2. **Validation:** All config validated upfront with helpful errors
+3. **Debugging:** Clear logs showing "Running in X mode with config Y"
+4. **Maintenance:** Mode-specific logic can be isolated
+5. **Documentation:** Clear mapping of mode → required config
+6. **Error Messages:** Context-aware ("X is required for Y mode")
+7. **Testing:** Each mode testable in isolation
+
+### Negative
+
+1. **Migration:** Existing invalid configurations will now fail at startup
+2. **Flexibility:** Less flexibility in configuration combinations
+3. **Strictness:** Some previously-working combinations may be rejected
+
+### Neutral
+
+1. **Backward Compatibility:** Valid configurations continue to work
+2. **Mode Detection:** Automatic based on config (no explicit mode selection)
+3. **Default Mode:** OAuth single-audience when no credentials provided
+
+## Implementation Notes
+
+### Embedding Provider Validation
+
+Originally, validation required either `OLLAMA_BASE_URL` or `OPENAI_API_KEY` when vector sync was enabled. This was too strict because the Simple provider is always available as a fallback (ADR-015). The validation was removed to allow vector sync without explicit provider configuration.
+
+### Variable Scoping Issues
+
+During implementation, several Python variable scoping issues were discovered in `app.py`:
+- Local variable assignments in `starlette_lifespan()` shadowed outer scope variables
+- Fixed by using unique variable names (e.g., `nextcloud_host_for_context`, `basic_auth_storage`)
+- Removed redundant `settings = get_settings()` call (re-used outer scope)
+
+### Docker Compose Configuration
+
+The `mcp-oauth` service configuration was updated to remove `ENABLE_MULTI_USER_BASIC_AUTH=true` which conflicted with its intended OAuth mode. The service now runs in OAuth single-audience mode with vector sync using the Simple embedding provider as fallback.
+
+## Testing
+
+### Unit Tests
+
+`tests/unit/test_config_validators.py` provides comprehensive coverage:
+- Mode detection with priority ordering (7 tests)
+- Single-user BasicAuth validation (8 tests)
+- Multi-user BasicAuth validation (7 tests)
+- OAuth single-audience validation (6 tests)
+- OAuth token exchange validation (3 tests)
+- Smithery validation (4 tests)
+- Mode summary generation (3 tests)
+- Edge cases (3 tests)
+
+**Total: 41 tests, all passing**
+
+### Integration Tests
+
+Integration tests verify that:
+- Each mode starts successfully with valid configuration
+- Invalid configurations fail with clear error messages
+- Existing deployments continue to work
+
+## References
+
+- [ADR-002: Vector Sync Authentication](ADR-002-vector-sync-authentication.md)
+- [ADR-004: Progressive Consent](ADR-004-progressive-consent.md)
+- [ADR-015: Unified Provider Architecture](ADR-015-unified-provider-architecture.md)
+- [ADR-019: Multi-user BasicAuth Pass-Through](ADR-019-multi-user-basicauth-passthrough.md)
+- Implementation: `nextcloud_mcp_server/config_validators.py`
+- Tests: `tests/unit/test_config_validators.py`

docs/ADR-021-configuration-consolidation.md

@@ -0,0 +1,391 @@
+# ADR-021: Configuration Consolidation and Simplification
+
+**Status:** Accepted
+**Date:** 2025-12-21
+**Deciders:** Development Team
+**Related:** ADR-020 (Deployment Modes), ADR-002 (Vector Sync), ADR-004 (Progressive Consent)
+
+## Context
+
+The configuration system has grown complex with overlapping concerns that make it difficult for users to switch between deployment modes and understand configuration dependencies.
+
+### Problems Identified
+
+1. **Confusing variable names don't reflect purpose**:
+   - `ENABLE_OFFLINE_ACCESS` - Actually controls refresh token storage for background operations, not general "offline" capabilities
+   - `VECTOR_SYNC_ENABLED` - Controls semantic search background indexing (implementation detail, not user-facing feature name)
+   - Users struggle to understand what these variables actually control
+
+2. **Redundant configuration requirements**:
+   - Multi-user semantic search requires setting BOTH `ENABLE_OFFLINE_ACCESS=true` AND `VECTOR_SYNC_ENABLED=true`
+   - The dependency is one-way (semantic search needs background ops, but background ops don't need semantic search)
+   - Users must understand internal implementation details to configure a user-facing feature
+
+3. **Implicit mode detection creates ambiguity**:
+   - Five deployment modes detected via priority-based logic
+   - Users can't easily predict which mode will activate
+   - Configuration errors don't clearly indicate which mode triggered the requirement
+
+4. **OIDC_CLIENT_ID vs NEXTCLOUD_OIDC_CLIENT_ID confusion**:
+   - Investigation revealed these are NOT actually overlapping (`OIDC_CLIENT_ID` is test-only)
+   - However, their similar names create confusion
+
+### Current Configuration Complexity
+
+**Example: Multi-user OAuth with semantic search**:
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_OFFLINE_ACCESS=true      # Why is this needed?
+VECTOR_SYNC_ENABLED=true        # And this separately?
+QDRANT_URL=http://qdrant:6333
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```
+
+Users must understand:
+- Semantic search requires background token storage (ENABLE_OFFLINE_ACCESS)
+- Background token storage requires encryption keys
+- The relationship between ENABLE_OFFLINE_ACCESS and VECTOR_SYNC_ENABLED
+- Which deployment mode these settings will activate
+
+## Decision
+
+We consolidate overlapping functionality and add explicit mode selection while maintaining 100% backward compatibility.
+
+### 1. Automatic Dependency Resolution
+
+**Make ENABLE_SEMANTIC_SEARCH the primary control** that automatically enables required dependencies:
+
+**New behavior**:
+```python
+@property
+def enable_background_operations(self) -> bool:
+    """Background operations - auto-enabled by semantic search in multi-user modes."""
+    # Check new names first
+    explicit = os.getenv("ENABLE_BACKGROUND_OPERATIONS", "").lower() == "true"
+    # Fall back to old name with deprecation warning
+    legacy = os.getenv("ENABLE_OFFLINE_ACCESS", "").lower() == "true"
+    # Auto-enable if semantic search needs it
+    auto_enabled = self.enable_semantic_search and self.is_multi_user_mode()
+
+    return explicit or legacy or auto_enabled
+
+@property
+def enable_semantic_search(self) -> bool:
+    """Semantic search - renamed from VECTOR_SYNC_ENABLED."""
+    new_value = os.getenv("ENABLE_SEMANTIC_SEARCH", "").lower() == "true"
+    old_value = os.getenv("VECTOR_SYNC_ENABLED", "").lower() == "true"
+    return new_value or old_value
+```
+
+**Result**: Users set `ENABLE_SEMANTIC_SEARCH=true` and the system automatically enables background token storage when needed.
+
+### 2. Explicit Mode Selection (Optional)
+
+Add `MCP_DEPLOYMENT_MODE` environment variable to remove detection ambiguity:
+
+```bash
+# Optional: Explicitly declare deployment mode
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# Valid values: single_user_basic, multi_user_basic,
+#               oauth_single_audience, oauth_token_exchange, smithery
+```
+
+**Detection logic**:
+1. If `MCP_DEPLOYMENT_MODE` is set → validate and use it
+2. Otherwise → use priority-based auto-detection (existing behavior)
+3. Validate explicit mode doesn't conflict with detected mode
+
+### 3. Simplified User Experience
+
+**Before**:
+```bash
+# Multi-user OAuth with semantic search
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_OFFLINE_ACCESS=true      # Confusing
+VECTOR_SYNC_ENABLED=true        # Why both?
+QDRANT_URL=http://qdrant:6333
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```
+
+**After**:
+```bash
+# Multi-user OAuth with semantic search
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience  # Explicit (optional)
+ENABLE_SEMANTIC_SEARCH=true                # Auto-enables background ops
+QDRANT_URL=http://qdrant:6333
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```
+
+**Benefits**:
+- 2 fewer variables to understand/set
+- Clear intent ("I want semantic search")
+- Explicit mode declaration (optional)
+- All existing configs continue working
+
+### 4. Variable Naming Strategy
+
+**Deprecated (but still functional)**:
+- `ENABLE_OFFLINE_ACCESS` → Renamed to `ENABLE_BACKGROUND_OPERATIONS`
+- `VECTOR_SYNC_ENABLED` → Renamed to `ENABLE_SEMANTIC_SEARCH`
+
+**No change needed**:
+- `VECTOR_SYNC_SCAN_INTERVAL` - Implementation tuning parameter (keep as-is)
+- `VECTOR_SYNC_PROCESSOR_WORKERS` - Implementation tuning parameter (keep as-is)
+- `VECTOR_SYNC_QUEUE_MAX_SIZE` - Implementation tuning parameter (keep as-is)
+
+**Rationale**: Only rename user-facing feature flags, not internal tuning parameters.
+
+### 5. Backward Compatibility
+
+**Support both old and new names for minimum 2 major versions**:
+
+```python
+@property
+def enable_semantic_search(self) -> bool:
+    new_value = os.getenv("ENABLE_SEMANTIC_SEARCH", "").lower() == "true"
+    old_value = os.getenv("VECTOR_SYNC_ENABLED", "").lower() == "true"
+
+    if new_value and old_value:
+        logger.warning(
+            "Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. "
+            "Using ENABLE_SEMANTIC_SEARCH. VECTOR_SYNC_ENABLED is deprecated."
+        )
+
+    if old_value and not new_value:
+        logger.warning(
+            "VECTOR_SYNC_ENABLED is deprecated. Please use ENABLE_SEMANTIC_SEARCH instead."
+        )
+
+    return new_value or old_value
+```
+
+**Deprecation timeline**:
+- v0.6.0: Add new variables, deprecate old ones (both work with warnings)
+- v1.0.0: Remove old variables (breaking change, well-announced)
+- Minimum 2 major versions of support (12+ months)
+
+## Consequences
+
+### Positive
+
+1. **Reduced cognitive load**: Users set `ENABLE_SEMANTIC_SEARCH=true` instead of understanding internal dependencies
+2. **Clearer intent**: Variable names reflect user-facing features, not implementation details
+3. **Explicit mode control**: `MCP_DEPLOYMENT_MODE` removes detection ambiguity
+4. **Better onboarding**: New users see simpler configuration in env.sample
+5. **Improved error messages**: Validation can suggest "set MCP_DEPLOYMENT_MODE=X" instead of relying on implicit detection
+6. **No breaking changes**: All existing configurations continue working
+
+### Negative
+
+1. **Transition period complexity**: Both old and new names supported for 2+ versions
+2. **Documentation burden**: All docs must be updated to show new approach
+3. **Test coverage expansion**: Must test both old and new variable names in all modes
+4. **Migration effort**: Existing deployments should eventually migrate (optional but recommended)
+
+### Neutral
+
+1. **Same functionality**: No new features, just better organization
+2. **Same validation**: Underlying requirements unchanged (e.g., semantic search still needs Qdrant)
+3. **Same performance**: No runtime performance impact
+
+## Implementation
+
+### Phase 1: Configuration Consolidation (v0.6.0)
+
+**Files to modify**:
+- `nextcloud_mcp_server/config.py` - Add property-based deprecation with auto-enablement
+- `nextcloud_mcp_server/config_validators.py` - Simplify validation (semantic search no longer requires explicit background operations setting)
+- `nextcloud_mcp_server/app.py` - Add informative logging for auto-enablement
+- `tests/unit/test_config_validators.py` - Add auto-enablement tests
+- `docs/configuration-migration-v2.md` - Create migration guide
+
+**Key changes**:
+1. `enable_background_operations` property auto-enables when `enable_semantic_search=true` in multi-user modes
+2. `enable_semantic_search` property accepts both `ENABLE_SEMANTIC_SEARCH` and `VECTOR_SYNC_ENABLED`
+3. Smart logging when auto-enablement occurs or deprecated variables used
+4. Validation simplified to remove redundant requirements
+
+### Phase 2: Explicit Mode Selection (v0.6.0)
+
+**Files to modify**:
+- `nextcloud_mcp_server/config.py` - Add `deployment_mode` field
+- `nextcloud_mcp_server/config_validators.py` - Check explicit mode first, fall back to auto-detection
+- `tests/unit/test_config_validators.py` - Test mode override and conflict detection
+- `docs/configuration.md` - Document mode selection
+
+**Key changes**:
+1. Add `MCP_DEPLOYMENT_MODE` environment variable (optional)
+2. Mode detection checks explicit mode first, then auto-detects
+3. Validate explicit mode doesn't conflict with detected mode
+4. Better error messages referencing explicit mode setting
+
+### Phase 3: env.sample Reorganization (v0.6.0)
+
+**Files to create/modify**:
+- `env.sample` - Reorganize by deployment mode
+- `env.sample.single-user` - Simplest config template
+- `env.sample.oauth-multi-user` - Multi-user template showing consolidation
+- `env.sample.oauth-advanced` - Token exchange mode template
+- `README.md` - Update Quick Start to reference templates
+
+**Key changes**:
+1. Group related settings by deployment mode
+2. Show simplified configuration (only essential variables)
+3. Document automatic dependencies inline
+4. Provide mode-specific quick-start templates
+
+### Phase 4: Documentation Updates (v0.7.0)
+
+**Files to modify**:
+- `docs/configuration.md` - Lead with consolidated approach
+- `docs/authentication.md` - Update mode guidance with `MCP_DEPLOYMENT_MODE`
+- `docs/troubleshooting.md` - Add consolidation troubleshooting section
+- `docs/configuration-migration-v2.md` - Expand with comprehensive examples
+- `docs/ADR-020-deployment-modes-and-configuration-validation.md` - Update configuration matrix
+- All other ADRs - Update variable references
+
+**Key changes**:
+1. Update all examples to use new variable names
+2. Add before/after migration examples
+3. Document automatic dependency resolution
+4. Add mode selection decision tree diagram
+
+## Validation Strategy
+
+### Test Coverage Requirements
+
+**Backward compatibility tests**:
+- Old variable names still work (ENABLE_OFFLINE_ACCESS, VECTOR_SYNC_ENABLED)
+- New variable names work (ENABLE_BACKGROUND_OPERATIONS, ENABLE_SEMANTIC_SEARCH)
+- Setting both old and new triggers deprecation warning but works correctly
+- All 41 existing config validation tests pass
+
+**Auto-enablement tests**:
+- `ENABLE_SEMANTIC_SEARCH=true` in OAuth mode → `enable_background_operations=true`
+- `ENABLE_SEMANTIC_SEARCH=true` in single-user mode → `enable_background_operations=false` (not needed)
+- `ENABLE_SEMANTIC_SEARCH=false` → `enable_background_operations=false` (unless explicitly set)
+
+**Mode selection tests**:
+- `MCP_DEPLOYMENT_MODE=oauth_single_audience` → mode correctly detected
+- `MCP_DEPLOYMENT_MODE` conflicts with detected mode → validation error
+- No `MCP_DEPLOYMENT_MODE` → auto-detection works as before
+
+## Success Metrics
+
+**Immediate** (v0.6.0 release):
+- Zero breaking changes in existing deployments
+- All 41 config validation tests pass
+- New users report clearer configuration process
+
+**Medium-term** (6 months after v0.6.0):
+- 80% of new deployments use new variable names
+- Mode selection errors decrease by 50%
+- Support requests about configuration decrease
+
+**Long-term** (12+ months):
+- 90% of deployments migrated to new names
+- Old variable names can be safely removed in v1.0.0
+- Configuration-related issues in issue tracker decrease
+
+## Alternatives Considered
+
+### Alternative 1: Just Rename Variables
+
+**Rejected**: User feedback: "There's no reason to just rename variables without consolidating functionality"
+
+This would make names clearer but wouldn't reduce the number of variables users need to set. The real problem is requiring users to set both ENABLE_OFFLINE_ACCESS and VECTOR_SYNC_ENABLED when they just want semantic search.
+
+### Alternative 2: Remove ENABLE_OFFLINE_ACCESS Entirely
+
+**Rejected**: Advanced users need background operations without semantic search
+
+Some deployments might want background token storage for future features (background Deck sync, background Calendar sync, etc.) without enabling semantic search. Keeping ENABLE_BACKGROUND_OPERATIONS (renamed) allows this.
+
+### Alternative 3: Always Auto-Enable Background Operations
+
+**Rejected**: Single-user mode doesn't need background token storage
+
+Auto-enablement is only needed in multi-user modes. Single-user mode uses a shared client with BasicAuth, so background token storage is unnecessary. Always enabling it would waste resources and create confusing log messages.
+
+### Alternative 4: Require All New Names Immediately
+
+**Rejected**: Breaking change would affect all existing deployments
+
+Forcing migration to new variable names in v0.6.0 would break every existing deployment. Supporting both old and new names with deprecation warnings provides a smooth migration path.
+
+## References
+
+- [ADR-020: Deployment Modes and Configuration Validation](ADR-020-deployment-modes-and-configuration-validation.md)
+- [ADR-002: Vector Sync Authentication](ADR-002-vector-sync-authentication.md)
+- [ADR-004: Progressive Consent](ADR-004-mcp-application-oauth.md)
+- [Issue: Configuration complexity for multi-user semantic search](https://github.com/cbcoutinho/nextcloud-mcp-server/issues/XXX)
+
+## Migration Examples
+
+### Example 1: Single-User BasicAuth with Semantic Search
+
+**Before**:
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+VECTOR_SYNC_ENABLED=true
+QDRANT_LOCATION=:memory:
+```
+
+**After** (optional migration):
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+ENABLE_SEMANTIC_SEARCH=true  # Renamed
+QDRANT_LOCATION=:memory:
+# Note: Background operations NOT auto-enabled (not needed in single-user mode)
+```
+
+### Example 2: Multi-User OAuth with Semantic Search
+
+**Before**:
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_OFFLINE_ACCESS=true
+VECTOR_SYNC_ENABLED=true
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+QDRANT_URL=http://qdrant:6333
+```
+
+**After** (simplified):
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience  # Explicit (optional)
+ENABLE_SEMANTIC_SEARCH=true                # Auto-enables background operations
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+QDRANT_URL=http://qdrant:6333
+# Note: ENABLE_OFFLINE_ACCESS no longer needed (auto-enabled)
+```
+
+### Example 3: Multi-User OAuth WITHOUT Semantic Search
+
+**Before**:
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_OFFLINE_ACCESS=true  # For future background features
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```
+
+**After** (optional migration):
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+ENABLE_BACKGROUND_OPERATIONS=true  # Renamed for clarity
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```

docs/MCP-1.23-DNS-REBINDING-FIX.md

@@ -0,0 +1,104 @@
+# MCP 1.23.x DNS Rebinding Protection Fix
+
+## Problem
+
+MCP Python SDK 1.23.0 introduced **automatic DNS rebinding protection** that breaks containerized deployments (Kubernetes, Docker) when the protection is unintentionally auto-enabled.
+
+### Root Cause
+
+From `mcp/server/fastmcp/server.py:177-183` in the Python SDK:
+
+```python
+# Auto-enable DNS rebinding protection for localhost (IPv4 and IPv6)
+if transport_security is None and host in ("127.0.0.1", "localhost", "::1"):
+    transport_security = TransportSecuritySettings(
+        enable_dns_rebinding_protection=True,
+        allowed_hosts=["127.0.0.1:*", "localhost:*", "[::1]:*"],
+        allowed_origins=["http://127.0.0.1:*", "http://localhost:*", "http://[::1]:*"],
+    )
+```
+
+### What Was Happening
+
+1. **FastMCP initialization** in `app.py` didn't pass `host` or `transport_security` parameters
+2. **Defaults applied**: `host="127.0.0.1"`, `transport_security=None`
+3. **Auto-enablement triggered**: Condition `transport_security is None and host == "127.0.0.1"` was TRUE
+4. **Protection activated** with `allowed_hosts=["127.0.0.1:*", "localhost:*", "[::1]:*"]`
+5. **Kubernetes requests rejected**: `Host: nextcloud-mcp-server.default.svc.cluster.local:8000` didn't match allowed hosts
+
+### Why `--host 0.0.0.0` Didn't Help
+
+The `--host` CLI flag (used in Dockerfile/docker-compose) controls **uvicorn's bind address**, NOT the **FastMCP `host` parameter**. These are separate concerns:
+
+- **Uvicorn bind address** (`--host 0.0.0.0`): Where the HTTP server listens
+- **FastMCP host parameter** (defaulted to `"127.0.0.1"`): Used for auto-enablement logic
+
+## Solution
+
+Explicitly disable DNS rebinding protection by passing `transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False)` to all FastMCP instances.
+
+### Changes Made
+
+Modified `nextcloud_mcp_server/app.py`:
+
+1. **Import** `TransportSecuritySettings` from `mcp.server.transport_security`
+2. **Updated all three FastMCP initializations**:
+   - OAuth mode (line 1015)
+   - Smithery stateless mode (line 1030)
+   - BasicAuth mode (line 1040)
+
+Each now includes:
+```python
+transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False)
+```
+
+## Impact
+
+### ✅ What This Fixes
+
+- **Kubernetes deployments**: Requests with k8s service DNS names now work
+- **Docker deployments**: Port-mapped requests (localhost:8000 → container) now work
+- **Reverse proxy deployments**: Proxied requests with various Host headers now work
+- **Ingress controllers**: Requests via ingress hostnames now work
+
+### 🔒 Security Considerations
+
+DNS rebinding protection defends against attacks where:
+1. Attacker controls a DNS domain (e.g., `evil.com`)
+2. DNS initially resolves to attacker's IP
+3. After victim's browser caches the origin, DNS changes to victim's localhost
+4. Attacker's page can now make requests to victim's localhost services
+
+**Why it's safe to disable for this deployment:**
+
+1. **OAuth authentication required** in production deployments (ADR-002, ADR-004)
+2. **Network-level isolation** in containerized environments (k8s network policies, Docker networks)
+3. **MCP is server-to-server**, not exposed to browsers (no CORS concerns)
+4. **Host header validation inappropriate** for multi-tenant k8s environments
+
+If DNS rebinding protection is needed for specific deployments, it can be re-enabled with a custom allowed hosts list:
+
+```python
+transport_security=TransportSecuritySettings(
+    enable_dns_rebinding_protection=True,
+    allowed_hosts=[
+        "nextcloud-mcp-server.default.svc.cluster.local:*",
+        "mcp.example.com:*",
+        # Add all your expected Host header values
+    ]
+)
+```
+
+## Testing
+
+- ✅ Ruff linting passes
+- ✅ Type checking passes (pre-existing warnings unrelated)
+- ✅ Module imports successfully
+- ✅ Compatible with MCP 1.23.x
+
+## References
+
+- [MCP Python SDK 1.23.0 Release](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.0)
+- Commit: `d3a1841` - "Auto-enable DNS rebinding protection for localhost servers"
+- Issue #373 (original report of k8s breakage)
+- PR #382 (MCP 1.23.x upgrade)

docs/auth-flows.md

@@ -0,0 +1,422 @@
+# Authentication Flows by Deployment Mode
+
+This document provides a unified reference for authentication flows across all deployment modes. For configuration details, see [Authentication](authentication.md). For OAuth protocol details, see [OAuth Architecture](oauth-architecture.md).
+
+## Quick Reference Matrix
+
+| Mode | Client → MCP → NC | Background Sync | Astrolabe → MCP |
+|------|-------------------|-----------------|-----------------|
+| [Single-User BasicAuth](#1-single-user-basicauth) | Embedded credentials | Same credentials | N/A |
+| [Multi-User BasicAuth](#2-multi-user-basicauth) | Header pass-through | App password (optional) | Bearer token |
+| [OAuth Single-Audience](#3-oauth-single-audience-default) | Multi-audience token | Refresh token exchange | Bearer token |
+| [OAuth Token Exchange](#4-oauth-token-exchange-rfc-8693) | RFC 8693 exchange | Refresh token exchange | Bearer token |
+| [Smithery Stateless](#5-smithery-stateless) | Session parameters | Not supported | N/A |
+
+## Communication Patterns
+
+This document covers three distinct communication patterns:
+
+1. **MCP Client → MCP Server → Nextcloud**: Interactive tool calls initiated by users through MCP clients (Claude Desktop, etc.)
+2. **MCP Server → Nextcloud**: Background operations like vector sync that run without user interaction
+3. **Astrolabe → MCP Server**: Nextcloud app backend communication for settings UI and unified search
+
+---
+
+## Deployment Modes
+
+### 1. Single-User BasicAuth
+
+**Use Case:** Personal Nextcloud instance, local development, single-user deployments.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud
+    │                             │                            │
+    │── MCP Request ─────────────▶│                            │
+    │   (no auth required)        │                            │
+    │                             │── HTTP + BasicAuth ───────▶│
+    │                             │   Authorization: Basic     │
+    │                             │   (embedded credentials)   │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- Credentials embedded in server configuration (`NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD`)
+- Single shared `NextcloudClient` created at startup
+- No MCP-level authentication required (server trusts local clients)
+- All requests use the same Nextcloud user
+
+**Implementation:** `context.py:78-79` - Returns shared client from lifespan context
+
+#### Background Sync
+
+Uses the same embedded credentials as interactive requests. The background job accesses Nextcloud with the configured username/password.
+
+**Implementation:** Background jobs use `get_settings()` to access credentials
+
+#### Astrolabe Integration
+
+Not applicable - Astrolabe is only used in multi-user deployments where users need personal settings and token management.
+
+---
+
+### 2. Multi-User BasicAuth
+
+**Use Case:** Internal deployment where users provide their own credentials via HTTP headers.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud
+    │                             │                            │
+    │── MCP Request ─────────────▶│                            │
+    │   Authorization: Basic      │                            │
+    │   (user credentials)        │                            │
+    │                             │── BasicAuthMiddleware ────▶│
+    │                             │   Extracts credentials     │
+    │                             │                            │
+    │                             │── HTTP + BasicAuth ───────▶│
+    │                             │   (pass-through)           │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- `BasicAuthMiddleware` extracts credentials from `Authorization: Basic` header
+- Credentials passed through to Nextcloud (not stored)
+- Client created per-request from extracted credentials
+- Stateless - no credential storage between requests
+
+**Implementation:** `context.py:187-248` - `_get_client_from_basic_auth()` extracts credentials from request state
+
+#### Background Sync (Optional)
+
+Requires `ENABLE_OFFLINE_ACCESS=true`. Users can store app passwords via Astrolabe for background operations.
+
+```
+Astrolabe                     MCP Server                   Nextcloud
+    │                             │                            │
+    │── Store App Password ──────▶│                            │
+    │   (via management API)      │                            │
+    │                             │── Store in SQLite ────────▶│
+    │                             │   (encrypted)              │
+    │◀── Confirmation ────────────│                            │
+    │                             │                            │
+    │         [Background Job]    │                            │
+    │                             │── Retrieve app password ──▶│
+    │                             │   (from encrypted storage) │
+    │                             │── HTTP + BasicAuth ───────▶│
+    │                             │   (stored app password)    │
+    │                             │◀── API Response ───────────│
+```
+
+**Requirements:**
+- `ENABLE_OFFLINE_ACCESS=true`
+- `TOKEN_ENCRYPTION_KEY` for credential encryption
+- `TOKEN_STORAGE_DB` for SQLite storage path
+
+#### Astrolabe → MCP Server
+
+```
+Astrolabe                     MCP Server                   Nextcloud OIDC
+    │                             │                            │
+    │── OAuth Flow ──────────────▶│◀── Token from IdP ────────▶│
+    │   (user initiates)          │                            │
+    │                             │                            │
+    │── Bearer Token ────────────▶│                            │
+    │   (management API calls)    │                            │
+    │                             │── Validate via JWKS ──────▶│
+    │                             │   (or introspection)       │
+    │◀── API Response ────────────│                            │
+```
+
+**Key characteristics:**
+- Astrolabe has its own OAuth client (`astrolabe_client_id` in Nextcloud config)
+- Tokens are validated by MCP server using Nextcloud OIDC JWKS
+- Authorization check: `token.sub == requested_resource_owner`
+- Any valid Nextcloud OIDC token accepted (relaxed audience validation per ADR-018)
+
+**Implementation:** `unified_verifier.py:120-183` - `verify_token_for_management_api()` validates without strict audience check
+
+---
+
+### 3. OAuth Single-Audience (Default)
+
+**Use Case:** Multi-user deployment with OAuth authentication. Tokens work for both MCP and Nextcloud.
+
+This is the default mode when `NEXTCLOUD_USERNAME`/`NEXTCLOUD_PASSWORD` are not set.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud
+    │                             │                            │
+    │── Bearer Token ────────────▶│                            │
+    │   aud: ["mcp-server",       │                            │
+    │         "nextcloud"]        │                            │
+    │                             │── Validate MCP audience ──▶│
+    │                             │   (UnifiedTokenVerifier)   │
+    │                             │                            │
+    │                             │── HTTP + Same Token ──────▶│
+    │                             │   Authorization: Bearer    │
+    │                             │   (multi-audience token)   │
+    │                             │                            │
+    │                             │   NC validates its own aud │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- Token contains both audiences: `aud: ["mcp-server", "nextcloud"]`
+- MCP server validates only MCP audience (per RFC 7519)
+- Nextcloud independently validates its own audience
+- No token exchange needed - same token used throughout
+- Stateless operation for interactive requests
+
+**Token validation flow:**
+1. `UnifiedTokenVerifier.verify_token()` validates MCP audience
+2. Token passed directly to Nextcloud via `get_client_from_context()`
+3. Nextcloud validates its own audience when receiving API calls
+
+**Implementation:**
+- `unified_verifier.py:185-252` - `_verify_mcp_audience()` validates MCP audience only
+- `context.py:96-99` - Uses token directly in multi-audience mode
+
+#### Background Sync
+
+Requires `ENABLE_OFFLINE_ACCESS=true`. Uses stored refresh tokens to obtain access tokens for background operations.
+
+```
+                              MCP Server                   Nextcloud OIDC
+                                  │                            │
+    [Background Job starts]       │                            │
+                                  │── Get refresh token ──────▶│
+                                  │   (from encrypted storage) │
+                                  │                            │
+                                  │── Token refresh request ──▶│
+                                  │   grant_type=refresh_token │
+                                  │   scope=openid profile ... │
+                                  │◀── New access + refresh ───│
+                                  │   (rotation)               │
+                                  │                            │
+                                  │── Store rotated refresh ──▶│
+                                  │   (encrypted)              │
+                                  │                            │
+                                  │── HTTP + Access Token ────▶│
+                                  │   Authorization: Bearer    │
+                                  │◀── API Response ───────────│
+```
+
+**Key characteristics:**
+- Refresh tokens stored encrypted in SQLite (`TOKEN_STORAGE_DB`)
+- Nextcloud OIDC rotates refresh tokens on every use (one-time use)
+- `TokenBrokerService` handles token lifecycle
+- Per-user locking prevents race conditions during concurrent refresh
+
+**Implementation:**
+- `token_broker.py:269-362` - `get_background_token()` handles refresh with locking
+- `token_broker.py:428-509` - `_refresh_access_token_with_scopes()` exchanges refresh token
+
+#### Astrolabe → MCP Server
+
+Same as Multi-User BasicAuth. See [Astrolabe → MCP Server](#astrolabe--mcp-server) above.
+
+---
+
+### 4. OAuth Token Exchange (RFC 8693)
+
+**Use Case:** Multi-user deployment where MCP tokens are separate from Nextcloud tokens. Provides stronger security boundaries.
+
+Enabled by `ENABLE_TOKEN_EXCHANGE=true`.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud OIDC
+    │                             │                            │
+    │── Bearer Token ────────────▶│                            │
+    │   aud: "mcp-server"         │                            │
+    │   (MCP audience only)       │                            │
+    │                             │── Validate MCP audience ──▶│
+    │                             │                            │
+    │                             │── RFC 8693 Exchange ──────▶│
+    │                             │   grant_type=              │
+    │                             │     urn:ietf:params:oauth: │
+    │                             │     grant-type:token-exchange
+    │                             │   subject_token=<mcp-token>│
+    │                             │   requested_audience=      │
+    │                             │     "nextcloud"            │
+    │                             │◀── Delegated Token ────────│
+    │                             │   aud: "nextcloud"         │
+    │                             │                            │
+    │                             │── HTTP + Delegated Token ─▶│
+    │                             │   Authorization: Bearer    │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- Strict audience separation: MCP token has `aud: "mcp-server"` only
+- Server exchanges for Nextcloud-audience token on each request
+- Ephemeral delegated tokens (not cached by default)
+- Strongest security boundary between MCP and Nextcloud access
+
+**Token exchange details:**
+- Uses RFC 8693 "urn:ietf:params:oauth:grant-type:token-exchange"
+- Subject token: MCP access token
+- Requested audience: Nextcloud resource URI
+- Result: Short-lived token scoped for Nextcloud
+
+**Implementation:**
+- `token_broker.py:220-267` - `get_session_token()` performs on-demand exchange
+- `token_exchange.py` - `exchange_token_for_delegation()` implements RFC 8693
+- `context.py:88-94` - Routes to session client in exchange mode
+
+#### Background Sync
+
+Same as OAuth Single-Audience. Uses stored refresh tokens from Flow 2 provisioning.
+
+```
+                              MCP Server                   Nextcloud OIDC
+                                  │                            │
+    [User provisions access]      │                            │
+                                  │── Flow 2 OAuth ───────────▶│
+                                  │   client_id="mcp-server"   │
+                                  │   scope=offline_access ... │
+                                  │◀── Refresh Token ──────────│
+                                  │   (stored encrypted)       │
+                                  │                            │
+    [Background Job runs later]   │                            │
+                                  │── Refresh for background ─▶│
+                                  │   (same as single-audience)│
+```
+
+**Key difference from interactive:**
+- Interactive: On-demand token exchange per request
+- Background: Uses pre-provisioned refresh tokens (Flow 2)
+
+#### Astrolabe → MCP Server
+
+Same as Multi-User BasicAuth. See [Astrolabe → MCP Server](#astrolabe--mcp-server) above.
+
+---
+
+### 5. Smithery Stateless
+
+**Use Case:** Multi-tenant SaaS deployment via Smithery platform. Fully stateless.
+
+Enabled by `SMITHERY_DEPLOYMENT=true`.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud
+    │                             │                            │
+    │── SSE Connect ─────────────▶│                            │
+    │   ?nextcloud_url=...        │                            │
+    │   &username=...             │                            │
+    │   &app_password=...         │                            │
+    │                             │── SmitheryConfigMiddleware │
+    │                             │   Extract URL params       │
+    │                             │                            │
+    │── MCP Request ─────────────▶│                            │
+    │   (no Authorization header) │                            │
+    │                             │── Create per-request ─────▶│
+    │                             │   NextcloudClient          │
+    │                             │                            │
+    │                             │── HTTP + BasicAuth ───────▶│
+    │                             │   (from session params)    │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- Configuration passed via URL query parameters (Smithery `configSchema`)
+- No persistent state - client created fresh per request
+- No OAuth infrastructure
+- No background sync support (stateless)
+- No admin UI available
+
+**Required session parameters:**
+- `nextcloud_url`: Nextcloud instance URL
+- `username`: Nextcloud username
+- `app_password`: Nextcloud app password
+
+**Implementation:** `context.py:108-184` - `_get_client_from_session_config()` creates client from session params
+
+#### Background Sync
+
+Not supported. Smithery mode is fully stateless with no credential storage.
+
+#### Astrolabe Integration
+
+Not applicable. Smithery deployments don't integrate with Astrolabe.
+
+---
+
+## Configuration Quick Reference
+
+### Single-User BasicAuth
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+```
+
+### Multi-User BasicAuth
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+
+# Optional: For background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<32-byte-key>
+TOKEN_STORAGE_DB=/data/tokens.db
+```
+
+### OAuth Single-Audience (Default)
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+# No username/password triggers OAuth mode
+
+# Optional: Static client credentials (instead of DCR)
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+
+# Optional: For background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<32-byte-key>
+TOKEN_STORAGE_DB=/data/tokens.db
+```
+
+### OAuth Token Exchange
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+
+# Optional: For background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<32-byte-key>
+TOKEN_STORAGE_DB=/data/tokens.db
+```
+
+### Smithery Stateless
+```bash
+SMITHERY_DEPLOYMENT=true
+# All other config comes from session URL parameters
+```
+
+---
+
+## Related Documentation
+
+- [Authentication](authentication.md) - Configuration details and setup guides
+- [OAuth Architecture](oauth-architecture.md) - Deep OAuth protocol details
+- [ADR-004: Progressive Consent](ADR-004-mcp-application-oauth.md) - Dual OAuth flow architecture
+- [ADR-005: Token Audience Validation](ADR-005-token-audience-validation.md) - Audience validation strategy
+- [ADR-018: Nextcloud PHP App](ADR-018-nextcloud-php-app-for-settings-ui.md) - Astrolabe integration
+- [ADR-020: Deployment Modes](ADR-020-deployment-modes-and-configuration-validation.md) - Mode detection and validation

docs/authentication.md

@@ -140,6 +140,97 @@ Basic Authentication uses username and password credentials directly.
 - [Configuration](configuration.md#basic-authentication-legacy) - BasicAuth environment variables
 - [Running the Server](running.md#basicauth-mode-legacy) - BasicAuth examples
 
+## Hybrid Authentication (Multi-User BasicAuth + OAuth)
+
+When running in multi-user BasicAuth mode with `ENABLE_OFFLINE_ACCESS=true`, the server operates in **hybrid authentication mode**. This provides the simplicity of BasicAuth for normal operations with the security of OAuth for administrative functions.
+
+### Authentication Domains
+
+**MCP Operations** (Tools, Resources):
+- **Auth Method**: BasicAuth (HTTP Basic username/password)
+- **Characteristics**:
+  - Stateless - no token storage
+  - Simple configuration
+  - Direct credential validation against Nextcloud
+  - Credentials passed per-request in Authorization header
+- **Used For**: MCP tool calls from Claude, MCP client operations
+
+**Management APIs** (Webhooks, Admin UI):
+- **Auth Method**: OAuth bearer tokens
+- **Characteristics**:
+  - Per-user authorization via OAuth consent flow
+  - Refresh tokens stored for background operations
+  - Token validation via UnifiedTokenVerifier
+  - Explicit user consent required
+- **Used For**: Astrolabe admin UI, webhook management, vector sync operations
+
+### Configuration
+
+```env
+# Enable multi-user BasicAuth
+ENABLE_MULTI_USER_BASIC_AUTH=true
+
+# Enable hybrid mode (OAuth provisioning for management APIs)
+ENABLE_OFFLINE_ACCESS=true
+
+# Enable background sync (required for hybrid mode currently)
+VECTOR_SYNC_ENABLED=true
+
+# Encryption key for refresh token storage
+TOKEN_ENCRYPTION_KEY=<base64-encoded-key>
+
+# Nextcloud connection
+NEXTCLOUD_HOST=https://cloud.example.com
+
+# OAuth credentials (optional - uses DCR if not set)
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+```
+
+### OAuth Provisioning Flow
+
+1. Admin opens Astrolabe admin settings in Nextcloud
+2. Clicks "Authorize" to enable webhook management
+3. Redirected to `/oauth/authorize-nextcloud` on MCP server
+4. MCP server redirects to Nextcloud OAuth consent page
+5. Admin grants OAuth consent (scopes: `openid`, `profile`, `offline_access`)
+6. Redirected back to `/oauth/callback` on MCP server
+7. MCP server stores refresh token (encrypted)
+8. Admin can now manage webhooks from Astrolabe UI
+
+### Benefits
+
+- **Simple MCP client setup**: Use BasicAuth (no OAuth complexity for end users)
+- **Secure background operations**: Webhooks use per-user OAuth tokens (no shared credentials)
+- **Explicit authorization**: Admins must explicitly grant OAuth consent for webhook operations
+- **Per-user isolation**: Each admin's webhook operations use their own refresh token
+
+### Trade-offs
+
+- **Two auth systems**: More complex server configuration than pure BasicAuth or OAuth
+- **OAuth setup required**: Admins must complete OAuth flow before managing webhooks
+- **Token storage**: Requires database and encryption key for refresh tokens
+
+### Comparison
+
+| Feature | Pure BasicAuth | Hybrid Mode | Pure OAuth |
+|---------|---------------|-------------|------------|
+| MCP Operations | BasicAuth | BasicAuth | OAuth Bearer Token |
+| Management API | N/A | OAuth Bearer Token | OAuth Bearer Token |
+| Webhook Operations | N/A | OAuth Refresh Token | OAuth Refresh Token |
+| MCP Client Setup | Simple | Simple | Complex (PKCE flow) |
+| Admin UI Auth | N/A | OAuth Consent | OAuth Login |
+| Token Storage | None | Refresh tokens only | All tokens |
+| Deployment Complexity | Low | Medium | High |
+
+### Astrolabe User Setup (Hybrid Mode)
+
+For Astrolabe-specific user setup instructions in hybrid mode, see the [Astrolabe documentation](https://github.com/cbcoutinho/astrolabe/blob/master/docs/user-setup-hybrid-mode.md).
+
+### See Also
+- [OAuth Architecture](oauth-architecture.md) - Progressive Consent (Flow 2) details
+- [Configuration](configuration.md#enable_offline_access) - Hybrid mode configuration
+
 ## Mode Detection
 
 The server automatically detects the authentication mode:

docs/configuration-migration-v2.md

@@ -0,0 +1,564 @@
+# Configuration Migration Guide v2
+
+**Version:** v0.58.0
+**Status:** Active
+**Related ADR:** [ADR-021: Configuration Consolidation and Simplification](ADR-021-configuration-consolidation.md)
+
+## Overview
+
+This guide helps you migrate from the old configuration variables to the new consolidated approach introduced in v0.58.0.
+
+**Key Changes:**
+- `VECTOR_SYNC_ENABLED` → `ENABLE_SEMANTIC_SEARCH`
+- `ENABLE_OFFLINE_ACCESS` → `ENABLE_BACKGROUND_OPERATIONS`
+- New: `MCP_DEPLOYMENT_MODE` for explicit mode selection
+- Automatic dependency resolution: semantic search auto-enables background operations
+
+**Backward Compatibility:**
+- Old variable names still work in v0.58.0+
+- Deprecation warnings logged when old names used
+- Old names will be removed in v1.0.0
+
+---
+
+## Quick Reference: Variable Name Changes
+
+| Old Name | New Name | Status |
+|----------|----------|--------|
+| `VECTOR_SYNC_ENABLED` | `ENABLE_SEMANTIC_SEARCH` | Deprecated |
+| `ENABLE_OFFLINE_ACCESS` | `ENABLE_BACKGROUND_OPERATIONS` | Deprecated |
+| N/A (auto-detected) | `MCP_DEPLOYMENT_MODE` | New (optional) |
+
+**Tuning parameters unchanged:**
+- `VECTOR_SYNC_SCAN_INTERVAL` - Keep as-is
+- `VECTOR_SYNC_PROCESSOR_WORKERS` - Keep as-is
+- `VECTOR_SYNC_QUEUE_MAX_SIZE` - Keep as-is
+
+---
+
+## Migration Scenarios
+
+### Scenario 1: Single-User BasicAuth with Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+VECTOR_SYNC_ENABLED=true
+QDRANT_LOCATION=:memory:
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**After (v0.58.0+):**
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# Optional: Explicit mode declaration (recommended)
+MCP_DEPLOYMENT_MODE=single_user_basic
+
+# Updated variable name
+ENABLE_SEMANTIC_SEARCH=true  # Previously VECTOR_SYNC_ENABLED
+
+QDRANT_LOCATION=:memory:
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**What Changed:**
+- ✅ Renamed `VECTOR_SYNC_ENABLED` to `ENABLE_SEMANTIC_SEARCH`
+- ✅ Added optional `MCP_DEPLOYMENT_MODE` for clarity
+- ✅ Background operations NOT auto-enabled (not needed in single-user mode)
+
+**Migration Steps:**
+1. Replace `VECTOR_SYNC_ENABLED=true` with `ENABLE_SEMANTIC_SEARCH=true`
+2. Optionally add `MCP_DEPLOYMENT_MODE=single_user_basic`
+3. Restart server
+4. Verify deprecation warnings are gone
+
+---
+
+### Scenario 2: Multi-User OAuth with Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# Both variables required - confusing!
+ENABLE_OFFLINE_ACCESS=true
+VECTOR_SYNC_ENABLED=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+```
+
+**After (v0.58.0+ - Simplified):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# One variable does it all!
+ENABLE_SEMANTIC_SEARCH=true  # Automatically enables background operations
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+
+# Note: ENABLE_OFFLINE_ACCESS no longer needed!
+# Background operations are auto-enabled by ENABLE_SEMANTIC_SEARCH
+```
+
+**What Changed:**
+- ✅ Removed need for explicit `ENABLE_OFFLINE_ACCESS`
+- ✅ `ENABLE_SEMANTIC_SEARCH` automatically enables background operations in multi-user modes
+- ✅ Renamed `VECTOR_SYNC_ENABLED` to `ENABLE_SEMANTIC_SEARCH`
+- ✅ Added optional explicit mode declaration
+
+**Migration Steps:**
+1. Replace `VECTOR_SYNC_ENABLED=true` with `ENABLE_SEMANTIC_SEARCH=true`
+2. Remove `ENABLE_OFFLINE_ACCESS=true` (auto-enabled)
+3. Optionally add `MCP_DEPLOYMENT_MODE=oauth_single_audience`
+4. Restart server
+5. Check logs for confirmation: "Automatically enabled background operations for semantic search"
+
+---
+
+### Scenario 3: Multi-User OAuth WITHOUT Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# Enable background operations for future features
+ENABLE_OFFLINE_ACCESS=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+```
+
+**After (v0.58.0+):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# Renamed for clarity
+ENABLE_BACKGROUND_OPERATIONS=true  # Previously ENABLE_OFFLINE_ACCESS
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+```
+
+**What Changed:**
+- ✅ Renamed `ENABLE_OFFLINE_ACCESS` to `ENABLE_BACKGROUND_OPERATIONS`
+- ✅ Added optional explicit mode declaration
+
+**Migration Steps:**
+1. Replace `ENABLE_OFFLINE_ACCESS=true` with `ENABLE_BACKGROUND_OPERATIONS=true`
+2. Optionally add `MCP_DEPLOYMENT_MODE=oauth_single_audience`
+3. Restart server
+
+---
+
+### Scenario 4: Multi-User BasicAuth with Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+
+# Both required - redundant
+ENABLE_OFFLINE_ACCESS=true
+VECTOR_SYNC_ENABLED=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+```
+
+**After (v0.58.0+ - Simplified):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=multi_user_basic
+
+# One variable handles both!
+ENABLE_SEMANTIC_SEARCH=true  # Auto-enables background operations
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+
+# Note: ENABLE_OFFLINE_ACCESS no longer needed!
+```
+
+**What Changed:**
+- ✅ Semantic search auto-enables background operations
+- ✅ Removed need for explicit `ENABLE_OFFLINE_ACCESS`
+- ✅ Clearer variable naming
+
+**Migration Steps:**
+1. Replace `VECTOR_SYNC_ENABLED=true` with `ENABLE_SEMANTIC_SEARCH=true`
+2. Remove `ENABLE_OFFLINE_ACCESS=true` (auto-enabled)
+3. Optionally add `MCP_DEPLOYMENT_MODE=multi_user_basic`
+4. Restart server
+
+---
+
+### Scenario 5: Token Exchange Mode with Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+
+# Both required
+ENABLE_OFFLINE_ACCESS=true
+VECTOR_SYNC_ENABLED=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+TOKEN_EXCHANGE_CACHE_TTL=300
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**After (v0.58.0+ - Simplified):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=oauth_token_exchange
+
+# One variable!
+ENABLE_SEMANTIC_SEARCH=true  # Auto-enables background operations
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+TOKEN_EXCHANGE_CACHE_TTL=300
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**What Changed:**
+- ✅ Semantic search auto-enables background operations
+- ✅ Explicit mode declaration available
+
+**Migration Steps:**
+1. Replace `VECTOR_SYNC_ENABLED=true` with `ENABLE_SEMANTIC_SEARCH=true`
+2. Remove `ENABLE_OFFLINE_ACCESS=true` (auto-enabled)
+3. Optionally add `MCP_DEPLOYMENT_MODE=oauth_token_exchange`
+4. Restart server
+
+---
+
+## Understanding Automatic Dependency Resolution
+
+### How It Works
+
+In v0.58.0+, the server uses smart dependency resolution:
+
+```python
+# In multi-user modes (OAuth, Multi-User BasicAuth):
+if ENABLE_SEMANTIC_SEARCH == true:
+    background_operations = automatically enabled
+    refresh_tokens = automatically requested
+    token_storage = required (TOKEN_ENCRYPTION_KEY, TOKEN_STORAGE_DB)
+    oauth_credentials = required (for app password retrieval)
+```
+
+**What this means:**
+- ✅ Set `ENABLE_SEMANTIC_SEARCH=true`
+- ✅ Provide required infrastructure (Qdrant, Ollama, encryption key)
+- ✅ System automatically enables background operations
+- ❌ No need to set `ENABLE_BACKGROUND_OPERATIONS` separately
+
+### When Automatic Enablement Happens
+
+| Deployment Mode | Semantic Search Enabled | Background Operations Auto-Enabled? |
+|----------------|------------------------|-----------------------------------|
+| Single-User BasicAuth | ✅ | ❌ No (not needed) |
+| Multi-User BasicAuth | ✅ | ✅ Yes |
+| OAuth Single-Audience | ✅ | ✅ Yes |
+| OAuth Token Exchange | ✅ | ✅ Yes |
+| Smithery Stateless | N/A (not supported) | N/A |
+
+### When to Explicitly Set ENABLE_BACKGROUND_OPERATIONS
+
+Only needed when you want background operations **without** semantic search:
+
+```bash
+# Example: OAuth mode with background operations but NO semantic search
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# Explicitly enable background operations for future features
+ENABLE_BACKGROUND_OPERATIONS=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# Semantic search disabled
+ENABLE_SEMANTIC_SEARCH=false
+```
+
+---
+
+## Explicit Mode Selection
+
+### Why Use MCP_DEPLOYMENT_MODE?
+
+**Benefits:**
+- ✅ Removes ambiguity about which mode is active
+- ✅ Validation errors reference specific mode requirements
+- ✅ Catches configuration mistakes early
+- ✅ Self-documenting configuration
+
+**Example:**
+```bash
+# Without explicit mode:
+NEXTCLOUD_HOST=https://nextcloud.example.com
+# Is this OAuth or Multi-User BasicAuth? Not immediately clear.
+
+# With explicit mode:
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+NEXTCLOUD_HOST=https://nextcloud.example.com
+# Clear: This is OAuth mode
+```
+
+### Valid Mode Values
+
+| Mode Value | Description |
+|-----------|-------------|
+| `single_user_basic` | Single-user with username/password |
+| `multi_user_basic` | Multi-user with BasicAuth pass-through |
+| `oauth_single_audience` | Multi-user OAuth (recommended) |
+| `oauth_token_exchange` | Multi-user OAuth with token exchange |
+| `smithery` | Smithery platform deployment |
+
+### Mode Detection Priority
+
+When `MCP_DEPLOYMENT_MODE` is set:
+1. ✅ Explicit mode is used
+2. ✅ Server validates configuration matches explicit mode
+3. ❌ Auto-detection is skipped
+
+When `MCP_DEPLOYMENT_MODE` is NOT set:
+1. ✅ Auto-detection runs (existing behavior)
+2. ✅ Priority: Smithery → Token Exchange → Multi-User BasicAuth → Single-User BasicAuth → OAuth Single-Audience
+
+---
+
+## Validation and Error Messages
+
+### Old Validation (v0.57.x)
+
+```
+Error: [multi_user_basic] ENABLE_OFFLINE_ACCESS is required when VECTOR_SYNC_ENABLED is enabled
+```
+
+**Problem:** User must understand internal dependency relationship
+
+### New Validation (v0.58.0+)
+
+```
+Error: [multi_user_basic] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
+```
+
+**Benefit:** Clear what's needed, no mention of internal ENABLE_BACKGROUND_OPERATIONS flag
+
+---
+
+## Troubleshooting Migration
+
+### Issue: Deprecation Warning After Migration
+
+**Symptom:**
+```
+WARNING: VECTOR_SYNC_ENABLED is deprecated. Please use ENABLE_SEMANTIC_SEARCH instead.
+```
+
+**Solution:**
+1. Check for `VECTOR_SYNC_ENABLED` in `.env` file
+2. Replace with `ENABLE_SEMANTIC_SEARCH`
+3. Search for any scripts/CI configs using old name
+4. Restart server
+
+### Issue: Both Old and New Names Set
+
+**Symptom:**
+```
+WARNING: Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. Using ENABLE_SEMANTIC_SEARCH.
+```
+
+**Solution:**
+1. Remove `VECTOR_SYNC_ENABLED` from `.env`
+2. Keep `ENABLE_SEMANTIC_SEARCH`
+3. Restart server
+
+### Issue: Missing Required Dependencies
+
+**Symptom:**
+```
+Error: [oauth_single_audience] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
+```
+
+**Solution:**
+When semantic search is enabled in multi-user modes, you need:
+- `TOKEN_ENCRYPTION_KEY` - Generate with: `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`
+- `TOKEN_STORAGE_DB` - Path to SQLite database (e.g., `/app/data/tokens.db`)
+- `NEXTCLOUD_OIDC_CLIENT_ID` and `NEXTCLOUD_OIDC_CLIENT_SECRET` - For app password retrieval
+
+### Issue: Unexpected Mode Detected
+
+**Symptom:**
+Server activates `oauth_single_audience` mode when you expected `multi_user_basic`
+
+**Solution:**
+Add explicit mode declaration:
+```bash
+MCP_DEPLOYMENT_MODE=multi_user_basic
+ENABLE_MULTI_USER_BASIC_AUTH=true
+```
+
+---
+
+## Testing Your Migration
+
+### Step 1: Verify Configuration
+
+```bash
+# Set new variable names in .env
+cat .env | grep -E "(ENABLE_SEMANTIC_SEARCH|ENABLE_BACKGROUND_OPERATIONS|MCP_DEPLOYMENT_MODE)"
+```
+
+### Step 2: Check for Old Variable Names
+
+```bash
+# Should return nothing after migration
+cat .env | grep -E "(VECTOR_SYNC_ENABLED|ENABLE_OFFLINE_ACCESS)"
+```
+
+### Step 3: Start Server and Check Logs
+
+```bash
+# Start server
+docker-compose up mcp
+
+# Look for:
+# 1. No deprecation warnings
+# 2. Correct mode detected
+# 3. Auto-enablement messages (if using semantic search in multi-user mode)
+```
+
+**Expected Log Output (Multi-User OAuth + Semantic Search):**
+```
+INFO: Using explicit deployment mode: oauth_single_audience
+INFO: Automatically enabled background operations for semantic search in multi-user mode.
+INFO: Vector sync enabled. Starting background scanner...
+```
+
+### Step 4: Verify Functionality
+
+Test that existing features still work:
+- [ ] Semantic search returns results
+- [ ] Background indexing runs
+- [ ] OAuth flow completes successfully
+- [ ] Refresh tokens are stored/retrieved
+
+---
+
+## Quick Start Templates
+
+We provide mode-specific templates for new deployments:
+
+| Template | Use Case |
+|----------|----------|
+| `env.sample.single-user` | Simplest setup |
+| `env.sample.oauth-multi-user` | Recommended multi-user |
+| `env.sample.oauth-advanced` | Token exchange mode |
+
+**Usage:**
+```bash
+cp env.sample.oauth-multi-user .env
+# Edit .env with your values
+docker-compose up -d
+```
+
+---
+
+## Timeline and Support
+
+| Version | Status | Old Variable Support |
+|---------|--------|---------------------|
+| v0.57.x | Stable | Old names only |
+| v0.58.0 | Current | Both old and new (with warnings) |
+| v1.0.0 | Breaking | New names only |
+
+**Recommendation:** Migrate before v1.0.0 (12+ months minimum)
+
+---
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. **Check the logs** - Look for deprecation warnings and error messages
+2. **Review ADR-021** - See [docs/ADR-021-configuration-consolidation.md](ADR-021-configuration-consolidation.md)
+3. **Use mode-specific templates** - See `env.sample.*` files
+4. **File an issue** - Include your `.env` (redacted), logs, and mode
+
+---
+
+## Summary
+
+**What You Need to Do:**
+1. ✅ Rename `VECTOR_SYNC_ENABLED` → `ENABLE_SEMANTIC_SEARCH`
+2. ✅ (Optional) Rename `ENABLE_OFFLINE_ACCESS` → `ENABLE_BACKGROUND_OPERATIONS`
+3. ✅ (Recommended) Add `MCP_DEPLOYMENT_MODE` for clarity
+4. ✅ Remove redundant settings (semantic search auto-enables background ops in multi-user modes)
+5. ✅ Test your configuration
+
+**What the Server Does Automatically:**
+- ✅ Supports both old and new variable names
+- ✅ Logs deprecation warnings for old names
+- ✅ Auto-enables background operations when semantic search is enabled in multi-user modes
+- ✅ Validates configuration and provides clear error messages
+
+**Migration Timeline:**
+- Now → v1.0.0: Both old and new names work
+- v1.0.0+: Only new names supported
+
+**Questions?** See [docs/configuration.md](configuration.md) or file an issue.

docs/configuration.md

@@ -2,25 +2,82 @@
 
 The Nextcloud MCP server requires configuration to connect to your Nextcloud instance. Configuration is provided through environment variables, typically stored in a `.env` file.
 
+> **Note:** Configuration was significantly simplified in v0.58.0. If you're upgrading from v0.57.x, see the [Configuration Migration Guide](configuration-migration-v2.md).
+
 ## Quick Start
 
-Create a `.env` file based on `env.sample`:
+We provide mode-specific configuration templates for quick setup:
 
 ```bash
+# Choose a template based on your deployment mode:
+cp env.sample.single-user .env         # Simplest - one user, local dev
+cp env.sample.oauth-multi-user .env    # Recommended - multi-user OAuth
+cp env.sample.oauth-advanced .env      # Advanced - token exchange mode
+
+# Or start from the full example:
 cp env.sample .env
+
 # Edit .env with your Nextcloud details
 ```
 
-Then choose your authentication mode:
+Then choose your deployment mode:
 
-- [OAuth2/OIDC Configuration](#oauth2oidc-configuration) (Recommended)
-- [Basic Authentication Configuration](#basic-authentication-legacy)
+- [Single-User BasicAuth](#single-user-basicauth-mode) - Simplest for personal instances
+- [Multi-User OAuth](#multi-user-oauth-modes) - Recommended for production
+- [Deployment Mode Selection](#deployment-mode-selection) - Explicit mode declaration
 
 ---
 
-## OAuth2/OIDC Configuration
+## Deployment Mode Selection
 
-OAuth2/OIDC is the recommended authentication mode for production deployments.
+**New in v0.58.0:** You can explicitly declare your deployment mode to remove ambiguity and catch configuration errors early.
+
+```dotenv
+# Optional but recommended
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+```
+
+**Valid values:**
+- `single_user_basic` - Single-user with username/password
+- `multi_user_basic` - Multi-user with BasicAuth pass-through
+- `oauth_single_audience` - Multi-user OAuth (recommended)
+- `oauth_token_exchange` - Multi-user OAuth with token exchange
+- `smithery` - Smithery platform deployment
+
+**Benefits:**
+- ✅ Clear which mode is active
+- ✅ Better validation error messages
+- ✅ Self-documenting configuration
+- ✅ Catches configuration mistakes early
+
+**Auto-detection:** If `MCP_DEPLOYMENT_MODE` is not set, the server auto-detects the mode based on other settings (existing behavior).
+
+See [Authentication Modes](authentication.md) for detailed comparison of deployment modes.
+
+---
+
+## Single-User BasicAuth Mode
+
+BasicAuth with a single user is the simplest deployment mode. Use for personal instances, local development, and testing.
+
+```dotenv
+# Minimal single-user configuration
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=single_user_basic
+```
+
+> [!WARNING]
+> **Security Notice:** BasicAuth stores credentials in environment variables and is less secure than OAuth. Use OAuth for production multi-user deployments.
+
+---
+
+## Multi-User OAuth Modes
+
+OAuth2/OIDC is the recommended authentication mode for production multi-user deployments.
 
 ### Minimal Configuration (Auto-registration)
 
@@ -28,6 +85,9 @@ OAuth2/OIDC is the recommended authentication mode for production deployments.
 # .env file for OAuth with auto-registration
 NEXTCLOUD_HOST=https://your.nextcloud.instance.com
 
+# Optional: Explicit mode declaration (recommended)
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
 # Leave these EMPTY for OAuth mode
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
@@ -41,6 +101,9 @@ This minimal configuration uses dynamic client registration to automatically reg
 # .env file for OAuth with pre-configured client
 NEXTCLOUD_HOST=https://your.nextcloud.instance.com
 
+# Optional: Explicit mode declaration (recommended)
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
 # OAuth Client Credentials (optional - auto-registers if not provided)
 NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
 NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
@@ -108,10 +171,104 @@ NEXTCLOUD_PASSWORD=your_app_password_or_password
 
 ---
 
+## SSL/TLS Configuration (Optional)
+
+If your Nextcloud instance uses a self-signed certificate or a private CA (common with reverse proxies like Traefik or Caddy), the MCP server will reject the connection by default. Use these settings to configure certificate verification.
+
+### Custom CA Bundle (Recommended)
+
+Point the server at your CA certificate file:
+
+```dotenv
+NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem
+```
+
+With Docker, mount the certificate as a read-only volume:
+
+```bash
+docker run \
+  -v /path/to/my-ca.pem:/etc/ssl/certs/my-ca.pem:ro \
+  -e NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem \
+  -e NEXTCLOUD_HOST=https://nextcloud.local \
+  --env-file .env \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+### Disable Verification (Development Only)
+
+> [!WARNING]
+> Disabling TLS verification is insecure. Only use this for local development or testing.
+
+```dotenv
+NEXTCLOUD_VERIFY_SSL=false
+```
+
+### Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NEXTCLOUD_VERIFY_SSL` | ⚠️ Optional | `true` | Set to `false` to disable TLS certificate verification |
+| `NEXTCLOUD_CA_BUNDLE` | ⚠️ Optional | - | Path to a PEM CA bundle file for custom certificate authorities |
+
+### Scope
+
+These settings apply to **all** outbound connections to Nextcloud and its OIDC endpoints, including:
+
+- Nextcloud API calls (Notes, Calendar, Contacts, WebDAV, etc.)
+- OIDC discovery and token endpoints
+- OAuth client registration (DCR)
+- Health checks
+
+They do **not** affect connections to internal services (Ollama, Qdrant, Unstructured) which have their own SSL configuration.
+
+---
+
 ## Semantic Search Configuration (Optional)
 
+**New in v0.58.0:** Simplified semantic search configuration with automatic dependency resolution.
+
 The MCP server includes semantic search capabilities powered by vector embeddings. This feature requires a vector database (Qdrant) and an embedding service.
 
+### Quick Start
+
+**Single-User Mode:**
+```dotenv
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# Enable semantic search
+ENABLE_SEMANTIC_SEARCH=true
+
+# Vector database
+QDRANT_LOCATION=:memory:
+
+# Embedding provider
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**Multi-User OAuth Mode:**
+```dotenv
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# Enable semantic search
+# In multi-user modes, this AUTOMATICALLY enables background operations!
+ENABLE_SEMANTIC_SEARCH=true
+
+# Required for background operations (auto-enabled by semantic search)
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# Vector database
+QDRANT_URL=http://qdrant:6333
+
+# Embedding provider
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+> **Note:** In multi-user modes (OAuth, Multi-User BasicAuth), enabling `ENABLE_SEMANTIC_SEARCH` automatically enables background operations and refresh token storage. You don't need to set `ENABLE_BACKGROUND_OPERATIONS` separately!
+
 ### Qdrant Vector Database Modes
 
 The server supports three Qdrant deployment modes:
@@ -126,7 +283,7 @@ No configuration needed! If neither `QDRANT_URL` nor `QDRANT_LOCATION` is set, t
 
 ```dotenv
 # No Qdrant configuration needed - defaults to :memory:
-VECTOR_SYNC_ENABLED=true
+ENABLE_SEMANTIC_SEARCH=true
 ```
 
 **Pros:**
@@ -145,7 +302,7 @@ For single-instance deployments that need persistence without a separate Qdrant
 ```dotenv
 # Local persistent storage
 QDRANT_LOCATION=/app/data/qdrant  # Or any writable path
-VECTOR_SYNC_ENABLED=true
+ENABLE_SEMANTIC_SEARCH=true
 ```
 
 **Pros:**
@@ -166,7 +323,7 @@ For production deployments with a dedicated Qdrant service:
 QDRANT_URL=http://qdrant:6333
 QDRANT_API_KEY=your-secret-api-key  # Optional
 QDRANT_COLLECTION=nextcloud_content  # Optional
-VECTOR_SYNC_ENABLED=true
+ENABLE_SEMANTIC_SEARCH=true
 ```
 
 **Pros:**
@@ -283,13 +440,15 @@ Solutions:
 - Data corruption in Qdrant
 - Confusing error messages during indexing
 
-### Vector Sync Configuration
+### Background Indexing Configuration
 
 Control background indexing behavior:
 
 ```dotenv
-# Vector sync settings (ADR-007)
-VECTOR_SYNC_ENABLED=true              # Enable background indexing
+# Semantic search (ADR-007, ADR-021)
+ENABLE_SEMANTIC_SEARCH=true           # Enable background indexing
+
+# Tuning parameters (advanced - only modify if needed)
 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)
@@ -299,6 +458,8 @@ DOCUMENT_CHUNK_SIZE=512               # Words per chunk (default: 512)
 DOCUMENT_CHUNK_OVERLAP=50             # Overlapping words between chunks (default: 50)
 ```
 
+> **Note:** The `VECTOR_SYNC_*` tuning parameters keep their names as they're implementation details. Only the user-facing feature flag was renamed to `ENABLE_SEMANTIC_SEARCH`.
+
 ### Embedding Service Configuration
 
 The server uses an embedding service to generate vector representations. Two options are available:
@@ -369,11 +530,11 @@ DOCUMENT_CHUNK_OVERLAP=100
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
+| `ENABLE_SEMANTIC_SEARCH` | ⚠️ Optional | `false` | Enable semantic search with background indexing (replaces `VECTOR_SYNC_ENABLED`) |
 | `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 |
+| `QDRANT_COLLECTION` | ⚠️ Optional | Auto-generated | Qdrant collection name |
 | `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 |
@@ -383,6 +544,9 @@ DOCUMENT_CHUNK_OVERLAP=100
 | `DOCUMENT_CHUNK_SIZE` | ⚠️ Optional | `512` | Words per chunk for document embedding |
 | `DOCUMENT_CHUNK_OVERLAP` | ⚠️ Optional | `50` | Overlapping words between chunks (must be < chunk size) |
 
+**Deprecated variables (still functional):**
+- `VECTOR_SYNC_ENABLED` - Use `ENABLE_SEMANTIC_SEARCH` instead (will be removed in v1.0.0)
+
 ### Docker Compose Example
 
 Enable network mode Qdrant with docker-compose:
@@ -392,7 +556,7 @@ services:
   mcp:
     environment:
       - QDRANT_URL=http://qdrant:6333
-      - VECTOR_SYNC_ENABLED=true
+      - ENABLE_SEMANTIC_SEARCH=true
 
   qdrant:
     image: qdrant/qdrant:latest
@@ -545,6 +709,7 @@ uv run nextcloud-mcp-server --no-oauth \
 
 ## See Also
 
+- [Configuration Migration Guide v2](configuration-migration-v2.md) - **New in v0.58.0:** Migrate from old variable names
 - [OAuth Quick Start](quickstart-oauth.md) - 5-minute OAuth setup for development
 - [OAuth Setup Guide](oauth-setup.md) - Detailed OAuth configuration for production
 - [OAuth Architecture](oauth-architecture.md) - How OAuth works in the MCP server
@@ -553,3 +718,4 @@ uv run nextcloud-mcp-server --no-oauth \
 - [Running the Server](running.md) - Starting the server with different configurations
 - [Troubleshooting](troubleshooting.md) - Common configuration issues
 - [OAuth Troubleshooting](oauth-troubleshooting.md) - OAuth-specific troubleshooting
+- [ADR-021](ADR-021-configuration-consolidation.md) - Configuration consolidation architecture decision

docs/database-migrations.md

@@ -0,0 +1,301 @@
+# Database Migrations
+
+This document describes the database migration system for nextcloud-mcp-server's token storage database.
+
+## Overview
+
+The token storage database uses [Alembic](https://alembic.sqlalchemy.org/) for schema versioning and migrations. Alembic provides:
+
+- **Version Control**: Track schema changes in Git
+- **Rollback Support**: Safely downgrade schema if needed
+- **Audit Trail**: Migration files serve as schema changelog
+- **Automated Upgrades**: Database schema updates automatically on startup
+
+## Architecture
+
+### Migration Strategy
+
+The system handles three scenarios:
+
+1. **New Database**: Runs migrations from scratch to create all tables
+2. **Pre-Alembic Database**: Stamps existing database with initial revision (no changes)
+3. **Alembic-Managed Database**: Upgrades to latest version automatically
+
+### Directory Structure
+
+```
+nextcloud-mcp-server/
+├── alembic/                              # Alembic migrations
+│   ├── versions/                         # Migration scripts
+│   │   └── 20251217_2200_001_initial_schema.py
+│   ├── env.py                            # Alembic environment
+│   ├── script.py.mako                    # Migration template
+│   └── README                            # Migration usage guide
+├── alembic.ini                           # Alembic configuration
+└── nextcloud_mcp_server/
+    ├── auth/storage.py                   # Uses migrations on init
+    └── migrations.py                     # Migration utilities
+```
+
+## Usage
+
+### Automatic Migration on Startup
+
+Migrations run automatically when the server starts:
+
+```bash
+uv run nextcloud-mcp-server
+```
+
+The `RefreshTokenStorage.initialize()` method:
+1. Checks if database is Alembic-managed
+2. Stamps pre-Alembic databases with initial revision
+3. Upgrades to latest version
+
+### Manual Migration Commands
+
+```bash
+# Show current database version
+uv run nextcloud-mcp-server db current
+
+# Upgrade database to latest version
+uv run nextcloud-mcp-server db upgrade
+
+# Show migration history
+uv run nextcloud-mcp-server db history
+
+# Downgrade by one version (emergency use only)
+uv run nextcloud-mcp-server db downgrade
+
+# Specify custom database path
+uv run nextcloud-mcp-server db current -d /path/to/tokens.db
+```
+
+### Environment Variables
+
+- `TOKEN_STORAGE_DB`: Path to database file (default: `/app/data/tokens.db`)
+
+## Creating Migrations (Developers)
+
+### Step 1: Create Migration File
+
+```bash
+uv run nextcloud-mcp-server db migrate "add user preferences table"
+```
+
+This creates a new migration file in `alembic/versions/` with empty `upgrade()` and `downgrade()` functions.
+
+### Step 2: Write Migration SQL
+
+Since we don't use SQLAlchemy models, write raw SQL:
+
+```python
+def upgrade() -> None:
+    """Add user preferences table."""
+    op.execute("""
+        CREATE TABLE user_preferences (
+            user_id TEXT PRIMARY KEY,
+            theme TEXT DEFAULT 'light',
+            language TEXT DEFAULT 'en',
+            created_at INTEGER NOT NULL
+        )
+    """)
+
+    op.execute("""
+        CREATE INDEX idx_user_preferences_user_id
+        ON user_preferences(user_id)
+    """)
+
+
+def downgrade() -> None:
+    """Remove user preferences table."""
+    op.execute("DROP INDEX IF EXISTS idx_user_preferences_user_id")
+    op.execute("DROP TABLE IF EXISTS user_preferences")
+```
+
+### Step 3: Test Migration
+
+```bash
+# Test upgrade
+uv run nextcloud-mcp-server db upgrade -d /tmp/test.db
+
+# Verify schema
+sqlite3 /tmp/test.db ".schema"
+
+# Test downgrade
+uv run nextcloud-mcp-server db downgrade -d /tmp/test.db
+
+# Verify removal
+sqlite3 /tmp/test.db ".schema"
+```
+
+### Step 4: Commit Migration
+
+```bash
+git add alembic/versions/YYYYMMDD_HHMM_XXX_description.py
+git commit -m "feat: add user preferences table migration"
+```
+
+## SQLite Limitations
+
+SQLite has limited `ALTER TABLE` support:
+
+### Supported Operations
+
+- ✅ Add columns: `ALTER TABLE table ADD COLUMN ...`
+- ✅ Rename table: `ALTER TABLE old RENAME TO new`
+- ✅ Rename column: `ALTER TABLE table RENAME COLUMN old TO new` (SQLite 3.25+)
+
+### Unsupported Operations (Requires Table Recreation)
+
+- ❌ Drop column
+- ❌ Change column type
+- ❌ Add constraints to existing columns
+
+### Table Recreation Pattern
+
+For complex schema changes:
+
+```python
+def upgrade() -> None:
+    # Create new table with desired schema
+    op.execute("""
+        CREATE TABLE refresh_tokens_new (
+            user_id TEXT PRIMARY KEY,
+            encrypted_token BLOB NOT NULL,
+            new_field TEXT,  -- New column
+            expires_at INTEGER,
+            created_at INTEGER NOT NULL
+        )
+    """)
+
+    # Copy data from old table
+    op.execute("""
+        INSERT INTO refresh_tokens_new
+        (user_id, encrypted_token, expires_at, created_at)
+        SELECT user_id, encrypted_token, expires_at, created_at
+        FROM refresh_tokens
+    """)
+
+    # Drop old table and rename new table
+    op.execute("DROP TABLE refresh_tokens")
+    op.execute("ALTER TABLE refresh_tokens_new RENAME TO refresh_tokens")
+
+    # Recreate indexes
+    op.execute("CREATE INDEX idx_user_id ON refresh_tokens(user_id)")
+```
+
+## Best Practices
+
+### Naming Conventions
+
+- **Migrations**: `YYYYMMDD_HHMM_XXX_description.py`
+- **Revision IDs**: Sequential numbers (`001`, `002`, `003`)
+- **Descriptions**: Imperative mood ("add table", "remove column")
+
+### Migration Guidelines
+
+1. **Test Thoroughly**: Test both upgrade and downgrade paths
+2. **Preserve Data**: Ensure data migration logic is correct
+3. **Document Changes**: Add comments explaining complex operations
+4. **Small Changes**: One logical change per migration
+5. **No Breaking Changes**: Maintain backward compatibility when possible
+
+### Downgrade Considerations
+
+- **Data Loss**: Downgrade may lose data (dropped columns, tables)
+- **Confirmation**: Downgrade command requires explicit confirmation
+- **Testing**: Always test downgrade path before deploying
+- **Emergency Only**: Use downgrades only for critical rollbacks
+
+## Backward Compatibility
+
+### Pre-Alembic Databases
+
+Existing databases created before Alembic integration are automatically detected and stamped with revision `001`:
+
+1. Server detects no `alembic_version` table
+2. Checks if `refresh_tokens` table exists
+3. If yes, stamps database with `001` (no schema changes)
+4. Future updates use normal migration path
+
+### Migration Path
+
+```
+Pre-Alembic DB → Stamp(001) → Upgrade(002) → Upgrade(003) → ...
+New DB → Migrate(001) → Upgrade(002) → Upgrade(003) → ...
+```
+
+## Troubleshooting
+
+### Migration Fails
+
+```bash
+# Check current state
+uv run nextcloud-mcp-server db current -d /path/to/tokens.db
+
+# View migration history
+uv run nextcloud-mcp-server db history -d /path/to/tokens.db
+
+# Manually inspect database
+sqlite3 /path/to/tokens.db ".schema"
+```
+
+### Reset to Initial State
+
+**WARNING: This destroys all data!**
+
+```bash
+# Downgrade to base (empty database)
+uv run nextcloud-mcp-server db downgrade -d /path/to/tokens.db --revision base
+
+# Upgrade to latest
+uv run nextcloud-mcp-server db upgrade -d /path/to/tokens.db
+```
+
+### Corrupted Migration State
+
+If `alembic_version` table is corrupted:
+
+```bash
+# Manually fix via SQL
+sqlite3 /path/to/tokens.db
+> DELETE FROM alembic_version;
+> INSERT INTO alembic_version (version_num) VALUES ('001');
+> .quit
+
+# Verify and upgrade
+uv run nextcloud-mcp-server db current -d /path/to/tokens.db
+uv run nextcloud-mcp-server db upgrade -d /path/to/tokens.db
+```
+
+## CI/CD Integration
+
+### Pre-Deployment
+
+```bash
+# Run migrations in test environment
+export TOKEN_STORAGE_DB=/app/data/tokens.db
+uv run nextcloud-mcp-server db upgrade
+
+# Verify current version
+uv run nextcloud-mcp-server db current
+```
+
+### Docker Deployment
+
+Migrations run automatically on container startup via `RefreshTokenStorage.initialize()`.
+
+### Rollback Plan
+
+1. Stop application
+2. Backup database: `cp tokens.db tokens.db.backup`
+3. Downgrade: `uv run nextcloud-mcp-server db downgrade --revision XXX`
+4. Deploy previous application version
+5. Restart application
+
+## References
+
+- [Alembic Documentation](https://alembic.sqlalchemy.org/)
+- [SQLite ALTER TABLE Limitations](https://www.sqlite.org/lang_altertable.html)
+- [ADR-004: Progressive Consent](./ADR-004-progressive-consent.md) (migration 001)

docs/running.md

@@ -14,100 +14,10 @@ Before running the server:
 
 ## Quick Start
 
-Load your environment variables and start the server:
+Start the server using Docker:
 
 ```bash
-# Load environment variables from .env
-export $(grep -v '^#' .env | xargs)
-
-# Start the server
-uv run nextcloud-mcp-server
-```
-
-The server will start on `http://127.0.0.1:8000` by default.
-
----
-
-## Running Locally
-
-### Method 1: Using nextcloud-mcp-server CLI (Recommended)
-
-The CLI provides a simple interface with built-in defaults:
-
-#### OAuth Mode
-
-```bash
-# Auto-detected when NEXTCLOUD_USERNAME/PASSWORD not set
-uv run nextcloud-mcp-server
-
-# Explicitly force OAuth mode
-uv run nextcloud-mcp-server --oauth
-
-# OAuth with custom host and port
-uv run nextcloud-mcp-server --oauth --host 0.0.0.0 --port 8080
-
-# OAuth with pre-configured client
-uv run nextcloud-mcp-server --oauth \
-  --oauth-client-id abc123 \
-  --oauth-client-secret xyz789
-
-# OAuth with specific apps only
-uv run nextcloud-mcp-server --oauth \
-  --enable-app notes \
-  --enable-app calendar
-```
-
-#### BasicAuth Mode (Legacy)
-
-```bash
-# Auto-detected when NEXTCLOUD_USERNAME/PASSWORD are set
-uv run nextcloud-mcp-server
-
-# Explicitly force BasicAuth mode
-uv run nextcloud-mcp-server --no-oauth
-
-# BasicAuth with specific apps
-uv run nextcloud-mcp-server --no-oauth \
-  --enable-app notes \
-  --enable-app webdav
-```
-
-### Method 2: Using uvicorn
-
-For more control over server options (workers, reload, etc.):
-
-```bash
-# Load environment variables
-export $(grep -v '^#' .env | xargs)
-
-# Run with uvicorn
-uv run uvicorn nextcloud_mcp_server.app:get_app \
-  --factory \
-  --host 127.0.0.1 \
-  --port 8000 \
-  --reload  # Enable auto-reload for development
-```
-
-See all uvicorn options at [https://www.uvicorn.org/settings/](https://www.uvicorn.org/settings/)
-
-### Method 3: Using Python Module
-
-```bash
-# Load environment variables
-export $(grep -v '^#' .env | xargs)
-
-# Run as Python module
-python -m nextcloud_mcp_server.app --oauth --port 8000
-```
-
----
-
-## Running with Docker
-
-### Basic Docker Run
-
-```bash
-# OAuth mode
+# OAuth mode (recommended)
 docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
   ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 
@@ -116,11 +26,56 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
   ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
 ```
 
-### Docker with Persistent OAuth Storage
+The server will start on `http://127.0.0.1:8000` by default.
+
+---
+
+## Running with Docker
+
+### Basic Docker Run
+
+#### OAuth Mode (Recommended)
 
 ```bash
+# OAuth with auto-registration
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+
+# OAuth with custom port
+docker run -p 127.0.0.1:8080:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+
+# OAuth with pre-configured client
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  -e NEXTCLOUD_OIDC_CLIENT_ID=abc123 \
+  -e NEXTCLOUD_OIDC_CLIENT_SECRET=xyz789 \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+
+# OAuth with specific apps only
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --enable-app notes --enable-app calendar
+```
+
+#### BasicAuth Mode (Legacy)
+
+```bash
+# BasicAuth (requires NEXTCLOUD_USERNAME/PASSWORD in .env)
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+
+# BasicAuth with specific apps
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
+  --enable-app notes --enable-app webdav
+```
+
+### Docker with Persistent Token Storage
+
+```bash
+# Mount volume for persistent OAuth token storage
 docker run -p 127.0.0.1:8000:8000 --env-file .env \
-  -v $(pwd)/.oauth:/app/.oauth \
+  -v $(pwd)/data:/app/data \
   --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 ```
 
@@ -140,7 +95,7 @@ services:
     env_file:
       - .env
     volumes:
-      - ./oauth-storage:/app/.oauth
+      - ./data:/app/data  # Persistent token storage
     restart: unless-stopped
 ```
 
@@ -168,30 +123,39 @@ docker-compose down
 
 ```bash
 # Bind to all interfaces (accessible from network)
-uv run nextcloud-mcp-server --host 0.0.0.0 --port 8000
+docker run -p 0.0.0.0:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 
 # Bind to localhost only (default, more secure)
-uv run nextcloud-mcp-server --host 127.0.0.1 --port 8000
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 
-# Use a different port
-uv run nextcloud-mcp-server --port 8080
+# Use a different port (map host port 8080 to container port 8000)
+docker run -p 127.0.0.1:8080:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 ```
 
-**Security Note:** Using `--host 0.0.0.0` exposes the server to your network. Only use this if you understand the security implications.
+**Security Note:** Binding to `0.0.0.0` exposes the server to your network. Only use this if you understand the security implications.
 
 ### Transport Protocols
 
 The server supports multiple MCP transport protocols:
 
 ```bash
-# Streamable HTTP (recommended)
-uv run nextcloud-mcp-server --transport streamable-http
+# Streamable HTTP (default, recommended)
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --transport streamable-http
 
-# SSE - Server-Sent Events (default, deprecated)
-uv run nextcloud-mcp-server --transport sse
+# SSE - Server-Sent Events (deprecated)
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --transport sse
 
 # HTTP
-uv run nextcloud-mcp-server --transport http
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --transport http
 ```
 
 > [!WARNING]
@@ -201,10 +165,14 @@ uv run nextcloud-mcp-server --transport http
 
 ```bash
 # Set log level (critical, error, warning, info, debug, trace)
-uv run nextcloud-mcp-server --log-level debug
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --log-level debug
 
 # Production: use warning or error
-uv run nextcloud-mcp-server --log-level warning
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --log-level warning
 ```
 
 ### Selective App Enablement
@@ -212,22 +180,26 @@ uv run nextcloud-mcp-server --log-level warning
 By default, all supported Nextcloud apps are enabled. You can enable specific apps only:
 
 ```bash
-# Available apps: notes, tables, webdav, calendar, contacts, deck
+# Available apps: notes, tables, webdav, calendar, contacts, cookbook, deck
 
 # Enable all apps (default)
-uv run nextcloud-mcp-server
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 
 # Enable only Notes
-uv run nextcloud-mcp-server --enable-app notes
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --enable-app notes
 
 # Enable multiple apps
-uv run nextcloud-mcp-server \
-  --enable-app notes \
-  --enable-app calendar \
-  --enable-app contacts
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --enable-app notes --enable-app calendar --enable-app contacts
 
 # Enable only WebDAV for file operations
-uv run nextcloud-mcp-server --enable-app webdav
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --enable-app webdav
 ```
 
 **Use cases:**
@@ -240,24 +212,68 @@ uv run nextcloud-mcp-server --enable-app webdav
 
 ## Development Mode
 
-For active development with auto-reload:
+### Running for Development
+
+For active development with auto-reload, mount your source code as a volume:
 
 ```bash
-# Using uvicorn with reload
-uv run uvicorn nextcloud_mcp_server.app:get_app \
-  --factory \
-  --reload \
-  --host 127.0.0.1 \
-  --port 8000 \
+# Development mode with source code mounted
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  -v $(pwd):/app \
+  -v $(pwd)/data:/app/data \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
   --log-level debug
 ```
 
-Or use the CLI with reload flag:
+For local development without Docker:
 
 ```bash
-uv run nextcloud-mcp-server --reload --log-level debug
+# Load environment variables
+export $(grep -v '^#' .env | xargs)
+
+# Run the server with auto-reload
+uv run nextcloud-mcp-server run --oauth --log-level debug
 ```
 
+### CLI Subcommands
+
+The `nextcloud-mcp-server` CLI has two main subcommands:
+
+1. **`run`** - Start the MCP server (default command in Docker)
+   ```bash
+   uv run nextcloud-mcp-server run --oauth --host 0.0.0.0 --port 8000
+   ```
+
+2. **`db`** - Database migration management (Alembic)
+   ```bash
+   # Show current migration revision
+   uv run nextcloud-mcp-server db current
+
+   # Upgrade to latest migration
+   uv run nextcloud-mcp-server db upgrade
+
+   # Show migration history
+   uv run nextcloud-mcp-server db history
+
+   # Create new migration (developers only)
+   uv run nextcloud-mcp-server db migrate "description of changes"
+   ```
+
+### Database Migrations
+
+Token storage uses **Alembic** for schema management:
+
+- **Automatic migrations**: Database is upgraded automatically on server startup
+- **Backward compatibility**: Pre-Alembic databases are automatically stamped with the initial revision
+- **Migration files**: Located in `alembic/versions/`
+- **For developers**: When changing the schema:
+  1. Create a migration: `uv run nextcloud-mcp-server db migrate "add new column"`
+  2. Edit the generated file in `alembic/versions/` to add SQL statements
+  3. Test upgrade: `uv run nextcloud-mcp-server db upgrade`
+  4. Test downgrade: `uv run nextcloud-mcp-server db downgrade`
+
+See [Database Migrations Guide](database-migrations.md) for detailed information.
+
 ---
 
 ## Connecting to the Server
@@ -266,15 +282,15 @@ uv run nextcloud-mcp-server --reload --log-level debug
 
 MCP Inspector is a browser-based tool for testing MCP servers:
 
-```bash
-# Start MCP Inspector
-uv run mcp dev
-
-# In the browser:
-# 1. Enter server URL: http://localhost:8000
-# 2. Complete OAuth flow (if using OAuth)
-# 3. Explore tools and resources
-```
+1. Start your MCP server using Docker (see above)
+2. Start MCP Inspector:
+   ```bash
+   npx @modelcontextprotocol/inspector
+   ```
+3. In the browser:
+   - Enter server URL: `http://localhost:8000`
+   - Complete OAuth flow (if using OAuth)
+   - Explore tools and resources
 
 ### Using MCP Clients
 
@@ -322,48 +338,13 @@ INFO     Initializing Nextcloud client with BasicAuth
 
 ### Running as a Background Service
 
-#### Using systemd (Linux)
-
-Create `/etc/systemd/system/nextcloud-mcp.service`:
-
-```ini
-[Unit]
-Description=Nextcloud MCP Server
-After=network.target
-
-[Service]
-Type=simple
-User=your-user
-WorkingDirectory=/path/to/nextcloud-mcp-server
-EnvironmentFile=/path/to/.env
-ExecStart=/path/to/uv run nextcloud-mcp-server --oauth
-Restart=on-failure
-RestartSec=10
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Enable and start:
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable nextcloud-mcp
-sudo systemctl start nextcloud-mcp
-sudo systemctl status nextcloud-mcp
-```
-
-#### Using Docker Compose
-
-See [Docker Compose section](#docker-compose) above - includes `restart: unless-stopped`.
+Use Docker Compose with `restart: unless-stopped` (see [Docker Compose section](#docker-compose) above).
 
 ### Monitoring Logs
 
 ```bash
-# Local installation with systemd
-sudo journalctl -u nextcloud-mcp -f
-
-# Docker
+# Docker (find container name first)
+docker ps
 docker logs -f <container-name>
 
 # Docker Compose
@@ -374,35 +355,38 @@ docker-compose logs -f mcp
 
 ## Performance Tuning
 
-### Multiple Workers
-
-For production deployments with higher load:
-
-```bash
-# Using CLI (if supported)
-uv run nextcloud-mcp-server --workers 4
-
-# Using uvicorn
-uv run uvicorn nextcloud_mcp_server.app:get_app \
-  --factory \
-  --workers 4 \
-  --host 0.0.0.0 \
-  --port 8000
-```
-
 ### Production Settings
 
-```bash
-# Recommended production configuration
-uv run nextcloud-mcp-server \
-  --oauth \
-  --host 127.0.0.1 \
-  --port 8000 \
-  --log-level warning \
-  --transport streamable-http \
-  --workers 2
+For production deployments, use Docker Compose with the recommended settings:
+
+```yaml
+version: '3.8'
+
+services:
+  mcp:
+    image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+    command: --oauth --log-level warning --transport streamable-http
+    ports:
+      - "127.0.0.1:8000:8000"
+    env_file:
+      - .env
+    volumes:
+      - ./data:/app/data
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          cpus: '2'
+          memory: 1G
+        reservations:
+          cpus: '0.5'
+          memory: 512M
 ```
 
+### Scaling with Multiple Replicas
+
+For higher load, use Docker Swarm or Kubernetes. See the [Helm Chart](../helm/) for Kubernetes deployments.
+
 ---
 
 ## Troubleshooting
@@ -411,12 +395,18 @@ uv run nextcloud-mcp-server \
 
 Check logs for errors:
 ```bash
-uv run nextcloud-mcp-server --log-level debug
+# View container logs
+docker logs <container-name>
+
+# Or run with debug logging
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+  --log-level debug
 ```
 
 Common issues:
-- Environment variables not loaded - See [Configuration](configuration.md#loading-environment-variables)
-- Port already in use - Try a different port with `--port`
+- Environment variables not loaded - Check your `.env` file
+- Port already in use - Use a different host port (e.g., `-p 127.0.0.1:8080:8000`)
 - OAuth configuration errors - See [Troubleshooting](troubleshooting.md)
 
 ### Can't connect to server

docs/semantic-search-architecture.md

@@ -5,7 +5,7 @@ This document explains the architecture of the semantic search feature in the Ne
 > [!IMPORTANT]
 > **Status: Experimental**
 > - Disabled by default (`VECTOR_SYNC_ENABLED=false`)
-> - Currently supports **Notes app only** (multi-app architecture ready, additional apps planned)
+> - Currently supports **Notes, Files (PDFs), News items, and Deck cards**
 > - Requires additional infrastructure (Qdrant vector database + Ollama embedding service)
 > - RAG answer generation requires MCP client sampling support
 
@@ -39,9 +39,9 @@ Semantic search enables:
 
 ### 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
+- **Supported Apps**: Notes, Files (PDFs with text extraction), News items, Deck cards
+- **Planned Apps**: Calendar events, Calendar tasks, Contacts
+- **Architecture**: Multi-app plugin system ready for additional apps
 
 ## System Components
 

docs/troubleshooting.md

@@ -4,6 +4,146 @@ This guide covers common issues and solutions for the Nextcloud MCP server.
 
 > **OAuth-specific issues?** See the dedicated [OAuth Troubleshooting Guide](oauth-troubleshooting.md) for OAuth authentication problems, OIDC discovery issues, token validation failures, and more.
 
+> **Upgrading from v0.57.x?** See the [Configuration Migration Guide](configuration-migration-v2.md) for help with new variable names.
+
+## Configuration Issues (v0.58.0+)
+
+### Issue: Deprecation warning for VECTOR_SYNC_ENABLED
+
+**Symptom:**
+```
+WARNING: VECTOR_SYNC_ENABLED is deprecated. Please use ENABLE_SEMANTIC_SEARCH instead.
+```
+
+**Cause:** You're using the old variable name from v0.57.x.
+
+**Solution:**
+```bash
+# In your .env file, replace:
+VECTOR_SYNC_ENABLED=true
+
+# With:
+ENABLE_SEMANTIC_SEARCH=true
+```
+
+See [Configuration Migration Guide](configuration-migration-v2.md) for complete migration instructions.
+
+---
+
+### Issue: Deprecation warning for ENABLE_OFFLINE_ACCESS
+
+**Symptom:**
+```
+WARNING: ENABLE_OFFLINE_ACCESS is deprecated. Please use ENABLE_BACKGROUND_OPERATIONS instead.
+```
+
+**Cause:** You're using the old variable name from v0.57.x.
+
+**Solution:**
+
+**If you have semantic search enabled:**
+```bash
+# In multi-user modes, you can remove ENABLE_OFFLINE_ACCESS entirely!
+# ENABLE_SEMANTIC_SEARCH automatically enables background operations
+
+# Before (v0.57.x):
+ENABLE_OFFLINE_ACCESS=true
+VECTOR_SYNC_ENABLED=true
+
+# After (v0.58.0+):
+ENABLE_SEMANTIC_SEARCH=true  # This is all you need!
+```
+
+**If you only want background operations (no semantic search):**
+```bash
+# Replace:
+ENABLE_OFFLINE_ACCESS=true
+
+# With:
+ENABLE_BACKGROUND_OPERATIONS=true
+```
+
+---
+
+### Issue: "Invalid MCP_DEPLOYMENT_MODE"
+
+**Symptom:**
+```
+ValueError: Invalid MCP_DEPLOYMENT_MODE: 'oauth'. Valid values: single_user_basic, multi_user_basic, oauth_single_audience, oauth_token_exchange, smithery
+```
+
+**Cause:** Invalid value for `MCP_DEPLOYMENT_MODE`.
+
+**Solution:**
+Use one of the valid mode values:
+```bash
+# Correct values:
+MCP_DEPLOYMENT_MODE=single_user_basic          # Single-user with username/password
+MCP_DEPLOYMENT_MODE=multi_user_basic           # Multi-user BasicAuth
+MCP_DEPLOYMENT_MODE=oauth_single_audience      # OAuth (recommended)
+MCP_DEPLOYMENT_MODE=oauth_token_exchange       # OAuth with token exchange
+MCP_DEPLOYMENT_MODE=smithery                   # Smithery deployment
+```
+
+Or remove `MCP_DEPLOYMENT_MODE` to use automatic detection.
+
+---
+
+### Issue: Missing TOKEN_ENCRYPTION_KEY when semantic search enabled
+
+**Symptom:**
+```
+Error: [oauth_single_audience] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
+```
+
+**Cause:** In multi-user modes, semantic search automatically enables background operations, which require encrypted token storage.
+
+**Solution:**
+Generate an encryption key and add required token storage configuration:
+
+```bash
+# Generate encryption key
+python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+
+# Add to .env:
+TOKEN_ENCRYPTION_KEY=<generated-key>
+TOKEN_STORAGE_DB=/app/data/tokens.db
+NEXTCLOUD_OIDC_CLIENT_ID=your-client-id       # Required for app password retrieval
+NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
+```
+
+**Why this happens:**
+- v0.58.0+ automatically enables background operations when `ENABLE_SEMANTIC_SEARCH=true` in multi-user modes
+- Background operations need encrypted refresh token storage
+- This simplifies configuration but requires the encryption infrastructure
+
+See [Configuration Guide - Semantic Search](configuration.md#semantic-search-configuration-optional) for details.
+
+---
+
+### Issue: Both old and new variable names set
+
+**Symptom:**
+```
+WARNING: Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. Using ENABLE_SEMANTIC_SEARCH.
+```
+
+**Cause:** You have both the old and new variable names in your configuration.
+
+**Solution:**
+Remove the old variable name:
+```bash
+# Remove this line:
+VECTOR_SYNC_ENABLED=true
+
+# Keep this line:
+ENABLE_SEMANTIC_SEARCH=true
+```
+
+The server will use the new name and ignore the old one, but it's cleaner to remove the old variable entirely.
+
+---
+
 ## OAuth Issues (Quick Reference)
 
 ### Issue: "OAuth mode requires NEXTCLOUD_HOST environment variable"

docs/webhook-management-guide.md

@@ -0,0 +1,339 @@
+# Webhook Management Guide
+
+This guide explains how to enable and disable webhooks for vector sync in each MCP server deployment mode. Webhooks enable near-real-time synchronization of content changes to the vector database, complementing the default polling-based sync.
+
+**Related ADRs:**
+- ADR-010: Webhook-Based Vector Sync
+- ADR-020: Deployment Modes and Configuration Validation
+
+## Prerequisites
+
+Before enabling webhooks, ensure:
+
+1. **Nextcloud 30+** with `webhook_listeners` app enabled
+2. **[Astrolabe app](https://github.com/cbcoutinho/astrolabe)** installed in Nextcloud (provides settings UI and credentials API)
+3. **MCP server** accessible from Nextcloud via HTTP(S)
+4. **Vector sync enabled** on the MCP server
+
+## Webhook Architecture Overview
+
+The webhook system has two components:
+
+1. **Webhook Registration** - Configuring Nextcloud to send change notifications to the MCP server
+2. **Background Sync Credentials** - Allowing the MCP server to access Nextcloud APIs on behalf of users
+
+Both must be configured for webhooks to function properly.
+
+## Deployment Mode Specifics
+
+### 1. Single-User BasicAuth
+
+**Configuration:**
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+VECTOR_SYNC_ENABLED=true
+```
+
+**Enable Webhooks:**
+1. Register webhooks using occ commands (requires Nextcloud admin):
+   ```bash
+   # Enable webhook_listeners app
+   php occ app:enable webhook_listeners
+
+   # Register webhooks for vector sync
+   php occ webhook_listeners:add \
+     --event "OCP\Files\Events\Node\NodeCreatedEvent" \
+     --uri "http://mcp-server:8000/webhooks/nextcloud" \
+     --method POST
+
+   # Repeat for other events (see Event Types below)
+   ```
+
+2. Optionally reduce polling frequency:
+   ```bash
+   VECTOR_SYNC_SCAN_INTERVAL=86400  # 24 hours
+   ```
+
+**Disable Webhooks:**
+```bash
+# List registered webhooks
+php occ webhook_listeners:list
+
+# Remove specific webhook by ID
+php occ webhook_listeners:remove <webhook-id>
+```
+
+**Notes:**
+- Simplest mode - admin credentials used for all operations
+- No per-user provisioning required
+- Background sync runs as the configured admin user
+
+---
+
+### 2. Multi-User BasicAuth Pass-Through
+
+**Configuration:**
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+ENABLE_BACKGROUND_OPERATIONS=true
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/app/data/tokens.db
+VECTOR_SYNC_ENABLED=true
+# OAuth client for Astrolabe API access
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+```
+
+**Credential Architecture:**
+This mode uses **two separate credential mechanisms**:
+
+1. **OAuth Session** (for management API access, including webhooks):
+   - Obtained via browser OAuth flow (`/oauth/login`)
+   - Stores refresh token in MCP server's `tokens.db`
+   - Used for webhook registration/management APIs
+
+2. **App Password** (for background sync):
+   - Generated in Nextcloud Security settings
+   - Stored encrypted in Nextcloud's `oc_preferences` via Astrolabe
+   - Used by background scanners to access Nextcloud APIs
+
+**Enable Webhooks:**
+
+#### Step 1: Complete OAuth Login (for Management API)
+Users must authorize the MCP server to access their Nextcloud:
+
+1. Navigate to **Nextcloud Settings → Astrolabe** (Personal settings)
+2. Click **"Authorize via OAuth"** under "Option 1"
+3. Complete OAuth consent flow
+4. Verify the page shows "Background Sync Access: Active"
+
+#### Step 2: Configure App Password (for Background Sync)
+Since OAuth refresh tokens have short expiry, users should also configure an app password:
+
+1. Navigate to **Nextcloud Settings → Security**
+2. Generate a new app password (name it "Astrolabe" or "MCP Server")
+3. Return to **Nextcloud Settings → Astrolabe**
+4. Under "Option 2: App Password", paste the app password
+5. Click **Save**
+
+#### Step 3: Register Webhooks (Admin)
+Same as Single-User BasicAuth:
+```bash
+php occ webhook_listeners:add \
+  --event "OCP\Files\Events\Node\NodeCreatedEvent" \
+  --uri "http://mcp-server:8003/webhooks/nextcloud" \
+  --method POST
+```
+
+**Disable Webhooks:**
+
+*Per-User:*
+1. Navigate to **Nextcloud Settings → Astrolabe**
+2. Click **"Revoke Access"** (for OAuth tokens) or **"Revoke Access"** (for app password)
+
+*System-Wide:*
+```bash
+php occ webhook_listeners:remove <webhook-id>
+```
+
+**Troubleshooting:**
+
+If OAuth login fails with "Access forbidden - Your client is not authorized":
+1. Check if OAuth client is registered:
+   ```sql
+   SELECT id, name, client_identifier FROM oc_oidc_clients
+   WHERE dcr = 1 ORDER BY id DESC LIMIT 5;
+   ```
+2. Restart MCP server to trigger DCR re-registration
+3. Verify `NEXTCLOUD_OIDC_CLIENT_ID` and `NEXTCLOUD_OIDC_CLIENT_SECRET` are set
+
+If background sync fails with "User no longer provisioned":
+1. Verify app password is stored:
+   ```sql
+   SELECT userid, configkey FROM oc_preferences
+   WHERE appid = 'astrolabe' AND userid = 'username';
+   ```
+2. Ensure user completed **both** OAuth login AND app password setup
+
+---
+
+### 3. OAuth Single-Audience (Default OAuth Mode)
+
+**Configuration:**
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+# No NEXTCLOUD_USERNAME/PASSWORD
+ENABLE_BACKGROUND_OPERATIONS=true
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/app/data/tokens.db
+VECTOR_SYNC_ENABLED=true
+```
+
+**Enable Webhooks:**
+
+#### Step 1: User Provisioning
+Users authorize via OAuth with `offline_access` scope:
+
+1. MCP client initiates OAuth flow
+2. User consents to requested scopes including `offline_access`
+3. MCP server stores refresh token for background operations
+
+Alternatively, via Astrolabe UI:
+1. Navigate to **Nextcloud Settings → Astrolabe**
+2. Click **"Authorize via OAuth"**
+3. Complete consent flow
+
+#### Step 2: Register Webhooks (Admin)
+```bash
+php occ webhook_listeners:add \
+  --event "OCP\Files\Events\Node\NodeCreatedEvent" \
+  --uri "http://mcp-server:8001/webhooks/nextcloud" \
+  --method POST
+```
+
+**Disable Webhooks:**
+
+*Per-User:*
+- Via Astrolabe UI: Click "Disable Indexing" or "Disconnect"
+- Via MCP tool: Use `revoke_nextcloud_access` if available
+
+*System-Wide:*
+```bash
+php occ webhook_listeners:remove <webhook-id>
+```
+
+---
+
+### 4. OAuth Token Exchange (RFC 8693)
+
+**Configuration:**
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+ENABLE_BACKGROUND_OPERATIONS=true
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/app/data/tokens.db
+VECTOR_SYNC_ENABLED=true
+```
+
+**Enable/Disable Webhooks:**
+Same process as OAuth Single-Audience. The token exchange happens transparently when the MCP server accesses Nextcloud APIs.
+
+---
+
+### 5. Smithery Stateless
+
+**Configuration:**
+- Configuration from session URL params
+- `VECTOR_SYNC_ENABLED=false` (required)
+
+**Webhooks:**
+**Not supported.** This mode is stateless with no persistent storage or background operations.
+
+---
+
+## Webhook Event Types
+
+Register these webhook events for full vector sync coverage:
+
+### File/Note Events
+```bash
+# Use BeforeNodeDeletedEvent for deletions (includes node.id)
+php occ webhook_listeners:add --event "OCP\Files\Events\Node\NodeCreatedEvent" --uri "$MCP_URL/webhooks/nextcloud"
+php occ webhook_listeners:add --event "OCP\Files\Events\Node\NodeWrittenEvent" --uri "$MCP_URL/webhooks/nextcloud"
+php occ webhook_listeners:add --event "OCP\Files\Events\Node\BeforeNodeDeletedEvent" --uri "$MCP_URL/webhooks/nextcloud"
+```
+
+### Calendar Events
+```bash
+php occ webhook_listeners:add --event "OCP\Calendar\Events\CalendarObjectCreatedEvent" --uri "$MCP_URL/webhooks/nextcloud"
+php occ webhook_listeners:add --event "OCP\Calendar\Events\CalendarObjectUpdatedEvent" --uri "$MCP_URL/webhooks/nextcloud"
+php occ webhook_listeners:add --event "OCP\Calendar\Events\CalendarObjectDeletedEvent" --uri "$MCP_URL/webhooks/nextcloud"
+```
+
+### Tables Events
+```bash
+php occ webhook_listeners:add --event "OCA\Tables\Event\RowAddedEvent" --uri "$MCP_URL/webhooks/nextcloud"
+php occ webhook_listeners:add --event "OCA\Tables\Event\RowUpdatedEvent" --uri "$MCP_URL/webhooks/nextcloud"
+php occ webhook_listeners:add --event "OCA\Tables\Event\RowDeletedEvent" --uri "$MCP_URL/webhooks/nextcloud"
+```
+
+## Security Considerations
+
+### Webhook Authentication
+Configure `WEBHOOK_SECRET` to require authentication for incoming webhooks:
+
+```bash
+# MCP Server
+WEBHOOK_SECRET=<generate-random-secret>
+
+# Nextcloud webhook registration
+php occ webhook_listeners:add \
+  --event "..." \
+  --uri "$MCP_URL/webhooks/nextcloud" \
+  --header "Authorization: Bearer <secret>"
+```
+
+### Token Storage
+- Refresh tokens and app passwords are encrypted using `TOKEN_ENCRYPTION_KEY`
+- Store the key securely (environment variable, secrets manager)
+- Different users have isolated credential storage
+
+## Monitoring
+
+### MCP Server Logs
+```bash
+# Docker
+docker compose logs mcp-multi-user-basic | grep -i webhook
+
+# Key log messages
+# - "Queued document from webhook: ..." - Success
+# - "Webhook authentication failed" - Auth error
+# - "User X no longer provisioned" - Missing credentials
+```
+
+### Nextcloud Logs
+```bash
+docker compose exec app cat /var/www/html/data/nextcloud.log | \
+  jq 'select(.message | contains("webhook"))' | tail
+```
+
+### Database Checks
+```sql
+-- Check registered webhooks
+SELECT * FROM oc_webhook_listeners;
+
+-- Check OAuth clients
+SELECT id, name, token_type FROM oc_oidc_clients WHERE dcr = 1;
+
+-- Check user credentials stored by Astrolabe app
+SELECT userid, configkey FROM oc_preferences WHERE appid = 'astrolabe';
+```
+
+## Common Issues
+
+### "Access forbidden - Your client is not authorized to connect"
+**Cause:** OAuth client registration expired or not present in Nextcloud
+**Fix:** Restart MCP server to trigger DCR re-registration
+
+### "User X no longer provisioned, stopping scanner"
+**Cause:** Background sync credentials missing or expired
+**Fix:** User must complete credential provisioning (see mode-specific steps)
+
+### "Failed to fetch" in browser console during OAuth
+**Cause:** Network issue between browser and MCP server callback endpoint
+**Fix:** Verify MCP server is accessible at the configured `NEXTCLOUD_MCP_SERVER_URL`
+
+### Webhooks not firing
+**Causes:**
+1. `webhook_listeners` app not enabled
+2. Webhook not registered for the event type
+3. Background job workers not running
+**Fix:**
+```bash
+php occ app:enable webhook_listeners
+php occ background:cron  # or configure systemd cron
+```

env.sample

@@ -1,198 +1,249 @@
-# Nextcloud Instance
+# ============================================
+# DEPLOYMENT MODE SELECTION
+# ============================================
+# Optional: Explicitly declare deployment mode (ADR-021)
+# If not set, mode is auto-detected from other settings
+# Valid values: single_user_basic, multi_user_basic, oauth_single_audience,
+#               oauth_token_exchange, smithery
+#
+# Recommendation: Set this for clarity and to catch configuration errors early
+#MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# ============================================
+# COMMON SETTINGS (Required for all modes)
+# ============================================
+# Your Nextcloud instance URL (without trailing slash)
 NEXTCLOUD_HOST=
 
-# ===== AUTHENTICATION MODE =====
-# Choose ONE of the following:
-
-# Option 1: OAuth2/OIDC (RECOMMENDED - More Secure)
-# - 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_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
-# - Use only for backward compatibility or if OAuth unavailable
-# - If these are set, OAuth mode is disabled
+# ============================================
+# SINGLE-USER BASICAUTH MODE
+# ============================================
+# Simplest deployment - one user, credentials in environment
+# Use for: Personal instances, local development, testing
+#
+# Required:
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
+#
+# Optional features (semantic search, document processing):
+# See "Optional Features" section below
 
 # ============================================
-# Document Processing Configuration
+# MULTI-USER BASICAUTH MODE
 # ============================================
-# 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
+# Users provide credentials in request headers (pass-through)
+# Use for: Multi-user without OAuth, simple shared deployments
+#
+# Required:
+#ENABLE_MULTI_USER_BASIC_AUTH=true
+#
+# Optional - Background Operations (for semantic search, future features):
+# Enable background token storage using app passwords (via Astrolabe)
+# Required for semantic search in multi-user mode
+# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
+#ENABLE_BACKGROUND_OPERATIONS=true
+#NEXTCLOUD_OIDC_CLIENT_ID=
+#NEXTCLOUD_OIDC_CLIENT_SECRET=
+#TOKEN_ENCRYPTION_KEY=
+#TOKEN_STORAGE_DB=/app/data/tokens.db
+#
+# Optional features (semantic search, document processing):
+# See "Optional Features" section below
 
 # ============================================
-# Unstructured.io Processor
+# OAUTH SINGLE-AUDIENCE MODE (Recommended)
 # ============================================
-# 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
+# Multi-user OAuth with single-audience tokens
+# Use for: Multi-user production deployments, enhanced security
+# Tokens work for both MCP server and Nextcloud APIs (pass-through)
+#
+# Required: None (uses Dynamic Client Registration if credentials not provided)
+#
+# Optional - Pre-registered OAuth Client:
+# If you pre-register the client instead of using DCR:
+#NEXTCLOUD_OIDC_CLIENT_ID=
+#NEXTCLOUD_OIDC_CLIENT_SECRET=
+#
+# Optional - Background Operations (for semantic search, future features):
+# Enable refresh token storage for offline access
+# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
+#ENABLE_BACKGROUND_OPERATIONS=true
+#TOKEN_ENCRYPTION_KEY=
+#TOKEN_STORAGE_DB=/app/data/tokens.db
+#
+# Optional - Custom OIDC Discovery:
+# Auto-detected from NEXTCLOUD_HOST if not set
+#NEXTCLOUD_OIDC_DISCOVERY_URL=
+#
+# Optional - Custom Scopes:
+# Default: openid profile email offline_access notes:* calendar:* contacts:* tables:* webdav:* deck:* cookbook:*
+#NEXTCLOUD_OIDC_SCOPES=openid profile email notes:* calendar:*
+#
+# MCP Server URL (for OAuth redirects):
+#NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+#
+# Optional features (semantic search, document processing):
+# See "Optional Features" section below
 
 # ============================================
-# Tesseract Processor (Local OCR)
+# OAUTH TOKEN EXCHANGE MODE (Advanced)
 # ============================================
-# 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
+# Multi-user OAuth with RFC 8693 token exchange
+# Use for: Advanced deployments requiring separate MCP and Nextcloud tokens
+# MCP tokens are separate from Nextcloud tokens
+#
+# Required:
+#ENABLE_TOKEN_EXCHANGE=true
+#
+# Optional - Pre-registered OAuth Client:
+# If you pre-register the client instead of using DCR:
+#NEXTCLOUD_OIDC_CLIENT_ID=
+#NEXTCLOUD_OIDC_CLIENT_SECRET=
+#
+# Optional - Token Exchange Configuration:
+# Cache TTL in seconds (default: 300 = 5 minutes)
+#TOKEN_EXCHANGE_CACHE_TTL=300
+#
+# Optional - Background Operations:
+# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
+#ENABLE_BACKGROUND_OPERATIONS=true
+#TOKEN_ENCRYPTION_KEY=
+#TOKEN_STORAGE_DB=/app/data/tokens.db
+#
+# Optional - Custom OIDC Discovery:
+#NEXTCLOUD_OIDC_DISCOVERY_URL=
+#
+# MCP Server URL (for OAuth redirects):
+#NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+#
+# Optional features (semantic search, document processing):
+# See "Optional Features" section below
 
 # ============================================
-# Custom Processor (Your own API)
+# SMITHERY STATELESS MODE
 # ============================================
-# 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
+# Stateless multi-tenant deployment for Smithery platform
+# Configuration comes from session URL parameters
+# No persistent storage, no OAuth, no vector sync
+#
+# Required: None (all config from session URL)
+# This mode is activated automatically when deployed to Smithery
 
 # ============================================
-# Semantic Search & Vector Sync Configuration
+# OPTIONAL FEATURES (All Deployment Modes)
 # ============================================
-# 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
+# ===== SEMANTIC SEARCH =====
+# AI-powered semantic search across Nextcloud content
+# Requires: Qdrant vector database + embedding provider (Ollama, Bedrock, or Simple fallback)
+#
+# Enable semantic search:
+#ENABLE_SEMANTIC_SEARCH=true
+#
+# Note for Multi-User Modes:
+# ENABLE_SEMANTIC_SEARCH automatically enables background operations when needed
+# No need to set ENABLE_BACKGROUND_OPERATIONS separately
+# The server will automatically request refresh tokens and store them encrypted
+#
+# Vector Database - Choose ONE mode:
+# 1. In-memory (default): Set neither QDRANT_URL nor QDRANT_LOCATION
+# 2. Persistent local: Set QDRANT_LOCATION=/path/to/data
+# 3. Network: Set QDRANT_URL=http://qdrant:6333
+#
+#QDRANT_URL=http://qdrant:6333
+#QDRANT_LOCATION=:memory:
+#QDRANT_API_KEY=
+#QDRANT_COLLECTION=nextcloud_content
+#
+# Embedding Provider - Choose ONE:
+# 1. Ollama (recommended for local deployment):
+#OLLAMA_BASE_URL=http://ollama:11434
+#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+#OLLAMA_VERIFY_SSL=true
+#
+# 2. Amazon Bedrock (for AWS deployments):
+#AWS_REGION=us-east-1
+#BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
+# Optional: AWS credentials (uses credential chain if not set)
+#AWS_ACCESS_KEY_ID=
+#AWS_SECRET_ACCESS_KEY=
+#
+# 3. Simple (automatic fallback, no configuration needed)
+# Uses basic in-memory embeddings if no provider configured
+#
+# Document Chunking:
+# Configure how documents are split before embedding
+#DOCUMENT_CHUNK_SIZE=512
+#DOCUMENT_CHUNK_OVERLAP=50
 
+# ===== SEMANTIC SEARCH TUNING =====
+# Advanced parameters for vector sync background operations
+# Only modify if you understand the implications
+#
 # 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
+# ===== DOCUMENT PROCESSING =====
+# Extract text from PDFs, images, DOCX, etc. for semantic search
+# Disabled by default
+#
+#ENABLE_DOCUMENT_PROCESSING=false
+#DOCUMENT_PROCESSOR=unstructured
+#
+# Unstructured.io Processor (recommended):
+#ENABLE_UNSTRUCTURED=false
+#UNSTRUCTURED_API_URL=http://unstructured:8000
+#UNSTRUCTURED_TIMEOUT=120
+#UNSTRUCTURED_STRATEGY=auto
+#UNSTRUCTURED_LANGUAGES=eng,deu
+#PROGRESS_INTERVAL=10
+#
+# Tesseract OCR (lightweight, images only):
+#ENABLE_TESSERACT=false
+#TESSERACT_CMD=/usr/bin/tesseract
+#TESSERACT_LANG=eng
+#
+# Custom Processor (your own API):
+#ENABLE_CUSTOM_PROCESSOR=false
+#CUSTOM_PROCESSOR_NAME=my_ocr
+#CUSTOM_PROCESSOR_URL=http://localhost:9000/process
+#CUSTOM_PROCESSOR_API_KEY=
+#CUSTOM_PROCESSOR_TIMEOUT=60
+#CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg,image/png
 
-# Network mode: URL to Qdrant service
-#QDRANT_URL=http://qdrant:6333
+# ===== SSL/TLS =====
+# For Nextcloud behind reverse proxies with self-signed or private CA certificates
+#
+# Disable TLS certificate verification (insecure, development only):
+#NEXTCLOUD_VERIFY_SSL=false
+#
+# Use a custom CA bundle (path to PEM file):
+#NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem
+#
+# Docker example: mount the CA bundle as a volume
+#   docker run -v /path/to/ca.pem:/etc/ssl/certs/my-ca.pem:ro \
+#     -e NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem ...
 
-# 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
+# ===== SECURITY & ADVANCED =====
+# Cookie security (browser UI)
+# Auto-detects from NEXTCLOUD_HOST protocol if not set
+#COOKIE_SECURE=true
 
 # ============================================
-# Ollama Embedding Service Configuration
+# DEPRECATED VARIABLES (Backward Compatibility)
 # ============================================
-# 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
+# These variables still work but will be removed in v1.0.0
+# Please migrate to new names:
+#
+# Old Name                  → New Name
+# VECTOR_SYNC_ENABLED      → ENABLE_SEMANTIC_SEARCH
+# ENABLE_OFFLINE_ACCESS    → ENABLE_BACKGROUND_OPERATIONS
+#
+# Migration is optional - both old and new names work
+# Deprecation warnings will be logged when old names are used

env.sample.oauth-advanced

@@ -0,0 +1,80 @@
+# ============================================
+# OAUTH TOKEN EXCHANGE QUICK START (Advanced)
+# ============================================
+# Advanced OAuth deployment with RFC 8693 token exchange
+# Use for: Deployments requiring separate MCP and Nextcloud tokens
+# Features: Dual-audience tokens, enhanced security boundaries
+#
+# Copy this file to .env and configure
+
+# ===== REQUIRED SETTINGS =====
+# Your Nextcloud instance URL (without trailing slash)
+NEXTCLOUD_HOST=https://nextcloud.example.com
+
+# Enable token exchange mode
+ENABLE_TOKEN_EXCHANGE=true
+
+# ===== REQUIRED: LEAVE USERNAME/PASSWORD EMPTY =====
+# OAuth mode activates when these are NOT set
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
+# Recommended for clarity
+MCP_DEPLOYMENT_MODE=oauth_token_exchange
+
+# ===== OPTIONAL: PRE-REGISTERED OAUTH CLIENT =====
+# If you pre-register the OAuth client instead of using DCR:
+#NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
+#NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
+
+# MCP Server URL (for OAuth redirects)
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+
+# ===== OPTIONAL: TOKEN EXCHANGE TUNING =====
+# Cache TTL for exchanged tokens (default: 300 seconds = 5 minutes)
+TOKEN_EXCHANGE_CACHE_TTL=300
+
+# ===== OPTIONAL: SEMANTIC SEARCH =====
+# AI-powered semantic search with automatic background operation setup
+#
+# Note: ENABLE_SEMANTIC_SEARCH automatically enables background operations
+# in token exchange mode, just like in OAuth single-audience mode
+#
+ENABLE_SEMANTIC_SEARCH=true
+
+# Vector Database (required for semantic search)
+QDRANT_URL=http://qdrant:6333
+
+# Embedding Provider (required for semantic search)
+OLLAMA_BASE_URL=http://ollama:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Token Storage (required for background operations - auto-enabled by semantic search)
+# Generate encryption key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+TOKEN_ENCRYPTION_KEY=your-encryption-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# ===== OPTIONAL: DOCUMENT PROCESSING =====
+# Extract text from PDFs, images, DOCX for semantic search
+#ENABLE_DOCUMENT_PROCESSING=true
+#ENABLE_UNSTRUCTURED=true
+#UNSTRUCTURED_API_URL=http://unstructured:8000
+
+# ===== TOKEN EXCHANGE MODE EXPLANATION =====
+# In this mode:
+# 1. MCP clients authenticate with tokens scoped to "mcp-server" audience
+# 2. Server exchanges MCP tokens for Nextcloud tokens on each request
+# 3. Provides clear separation between MCP session and Nextcloud access
+# 4. Enables fine-grained token lifecycle management
+#
+# When to use:
+# - Strict security requirements (separate token contexts)
+# - Complex multi-service architectures
+# - Need independent token expiration policies
+#
+# When NOT to use:
+# - Simple deployments (use oauth_single_audience instead)
+# - High-performance requirements (token exchange adds latency)
+
+# For more configuration options, see env.sample

env.sample.oauth-multi-user

@@ -0,0 +1,77 @@
+# ============================================
+# OAUTH MULTI-USER QUICK START (Recommended)
+# ============================================
+# Multi-user deployment with OAuth authentication
+# Use for: Multi-user production deployments, enhanced security
+# Features: Single-audience tokens, automatic client registration (DCR)
+#
+# Copy this file to .env and configure
+
+# ===== REQUIRED SETTINGS =====
+# Your Nextcloud instance URL (without trailing slash)
+NEXTCLOUD_HOST=https://nextcloud.example.com
+
+# ===== REQUIRED: LEAVE USERNAME/PASSWORD EMPTY =====
+# OAuth mode activates when these are NOT set
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
+# Recommended for clarity
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# ===== OPTIONAL: PRE-REGISTERED OAUTH CLIENT =====
+# If you pre-register the OAuth client instead of using DCR:
+#NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
+#NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
+
+# MCP Server URL (for OAuth redirects)
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+
+# ===== OPTIONAL: SEMANTIC SEARCH (Recommended) =====
+# AI-powered semantic search with automatic background operation setup
+#
+# When you enable semantic search in multi-user mode:
+# 1. ENABLE_SEMANTIC_SEARCH automatically enables background operations
+# 2. Server requests refresh tokens for offline indexing
+# 3. Tokens are stored encrypted in TOKEN_STORAGE_DB
+# 4. No need to set ENABLE_BACKGROUND_OPERATIONS separately!
+#
+ENABLE_SEMANTIC_SEARCH=true
+
+# Vector Database (required for semantic search)
+QDRANT_URL=http://qdrant:6333
+# OR for in-memory mode:
+#QDRANT_LOCATION=:memory:
+
+# Embedding Provider (required for semantic search)
+# Option 1: Ollama (recommended for local deployment)
+OLLAMA_BASE_URL=http://ollama:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Option 2: Amazon Bedrock (for AWS deployments)
+#AWS_REGION=us-east-1
+#BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
+
+# Token Storage (required for background operations - auto-enabled by semantic search)
+# Generate encryption key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+TOKEN_ENCRYPTION_KEY=your-encryption-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# ===== OPTIONAL: DOCUMENT PROCESSING =====
+# Extract text from PDFs, images, DOCX for semantic search
+#ENABLE_DOCUMENT_PROCESSING=true
+#ENABLE_UNSTRUCTURED=true
+#UNSTRUCTURED_API_URL=http://unstructured:8000
+
+# ===== SUMMARY OF AUTO-ENABLEMENT =====
+# With ENABLE_SEMANTIC_SEARCH=true in OAuth mode:
+# ✅ Background operations enabled automatically
+# ✅ Refresh token storage enabled automatically
+# ✅ OAuth credentials required (DCR or pre-registered)
+# ✅ Encryption key required for token storage
+#
+# You only need to set ENABLE_SEMANTIC_SEARCH and provide the required
+# infrastructure (Qdrant, Ollama, encryption key). The rest is automatic!
+
+# For more advanced configuration, see env.sample

env.sample.single-user

@@ -0,0 +1,37 @@
+# ============================================
+# SINGLE-USER BASICAUTH QUICK START
+# ============================================
+# Simplest deployment mode - one user, credentials in environment
+# Use for: Personal instances, local development, testing
+#
+# Copy this file to .env and fill in your credentials
+
+# ===== REQUIRED SETTINGS =====
+# Your Nextcloud instance URL (without trailing slash)
+NEXTCLOUD_HOST=http://localhost:8080
+
+# Your Nextcloud credentials
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
+# Recommended to avoid ambiguity
+MCP_DEPLOYMENT_MODE=single_user_basic
+
+# ===== OPTIONAL: SEMANTIC SEARCH =====
+# Uncomment to enable AI-powered semantic search
+# Requires: Qdrant + embedding provider (Ollama or Bedrock)
+#
+#ENABLE_SEMANTIC_SEARCH=true
+#QDRANT_LOCATION=:memory:
+#OLLAMA_BASE_URL=http://ollama:11434
+#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# ===== OPTIONAL: DOCUMENT PROCESSING =====
+# Extract text from PDFs, images, DOCX for semantic search
+#ENABLE_DOCUMENT_PROCESSING=true
+#ENABLE_UNSTRUCTURED=true
+#UNSTRUCTURED_API_URL=http://unstructured:8000
+
+# That's it! Single-user mode is the simplest to configure.
+# For more options, see env.sample

nextcloud_mcp_server/alembic/env.py

@@ -0,0 +1,133 @@
+"""Alembic environment configuration for nextcloud-mcp-server.
+
+This module configures how Alembic runs database migrations for the
+token storage database. It supports both online and offline migration modes.
+
+Uses anyio for async operations, consistent with the project's async patterns.
+"""
+
+import logging
+from pathlib import Path
+
+import anyio
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+
+# Configure logging
+logger = logging.getLogger("alembic.env")
+
+# This is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Update script location to point to package location
+# This allows alembic to find migrations when installed in site-packages
+script_location = Path(__file__).parent
+config.set_main_option("script_location", str(script_location))
+
+# We don't use SQLAlchemy models, so target_metadata is None
+# Migrations will be written manually using op.execute() for raw SQL
+target_metadata = None
+
+
+def get_database_url() -> str:
+    """
+    Get the database URL from Alembic config or environment.
+
+    The URL can be set in alembic.ini or passed via -x database_url=...
+    when running Alembic commands.
+
+    Returns:
+        Database URL (SQLite URL format)
+    """
+    # Check if URL is passed via -x database_url=...
+    url = context.get_x_argument(as_dictionary=True).get("database_url")
+
+    if not url:
+        # Fall back to alembic.ini configuration
+        url = config.get_main_option("sqlalchemy.url")
+
+    if not url:
+        # Default to /app/data/tokens.db for Docker deployments
+        db_path = Path("/app/data/tokens.db")
+        url = f"sqlite+aiosqlite:///{db_path}"
+        logger.warning(
+            f"No database URL configured, using default: {url}. "
+            "Set sqlalchemy.url in alembic.ini or pass -x database_url=..."
+        )
+
+    return url
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL and not an Engine,
+    though an Engine is acceptable here as well. By skipping the
+    Engine creation we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    This mode is useful for generating SQL scripts without database access.
+    """
+    url = get_database_url()
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    """Execute migrations within a database connection."""
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """Run migrations in 'online' mode with async support.
+
+    In this scenario we create an async Engine and associate
+    a connection with the context.
+    """
+    # Get database URL and update config
+    url = get_database_url()
+    config.set_main_option("sqlalchemy.url", url)
+
+    # Create async engine
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,  # Don't pool connections for migrations
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    This function is called from storage.py's initialize() method via
+    anyio.to_thread.run_sync(), so it always runs in a worker thread
+    with its own event loop. We can safely use anyio.run() here.
+    """
+    anyio.run(run_async_migrations)
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

nextcloud_mcp_server/alembic/versions/20251217_2200_001_initial_schema.py

@@ -0,0 +1,185 @@
+"""Initial schema for token storage database
+
+This migration creates the initial database schema including:
+- refresh_tokens: OAuth refresh tokens and user profiles
+- audit_logs: Audit trail for security events
+- oauth_clients: OAuth client credentials (DCR)
+- oauth_sessions: OAuth flow session state (ADR-004 Progressive Consent)
+- registered_webhooks: Webhook registration tracking (both OAuth and BasicAuth)
+- schema_version: Legacy schema version tracking (deprecated, use alembic_version)
+
+Revision ID: 001
+Revises:
+Create Date: 2025-12-17 22:00:00.000000
+
+"""
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "001"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Create initial database schema."""
+
+    # Refresh tokens table (OAuth mode only, for background jobs)
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS refresh_tokens (
+            user_id TEXT PRIMARY KEY,
+            encrypted_token BLOB NOT NULL,
+            expires_at INTEGER,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL,
+            -- ADR-004 Progressive Consent fields
+            flow_type TEXT DEFAULT 'hybrid',
+            token_audience TEXT DEFAULT 'nextcloud',
+            provisioned_at INTEGER,
+            provisioning_client_id TEXT,
+            scopes TEXT,
+            -- Browser session profile cache
+            user_profile TEXT,
+            profile_cached_at INTEGER
+        )
+        """
+    )
+
+    # Audit logs table (both OAuth and BasicAuth modes)
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS audit_logs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp INTEGER NOT NULL,
+            event TEXT NOT NULL,
+            user_id TEXT NOT NULL,
+            resource_type TEXT,
+            resource_id TEXT,
+            auth_method TEXT,
+            hostname TEXT
+        )
+        """
+    )
+
+    # Index on audit logs for efficient queries
+    op.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_audit_user_timestamp
+        ON audit_logs(user_id, timestamp)
+        """
+    )
+
+    # OAuth client credentials storage (OAuth mode only)
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS oauth_clients (
+            id INTEGER PRIMARY KEY,
+            client_id TEXT UNIQUE NOT NULL,
+            encrypted_client_secret BLOB NOT NULL,
+            client_id_issued_at INTEGER NOT NULL,
+            client_secret_expires_at INTEGER NOT NULL,
+            redirect_uris TEXT NOT NULL,
+            encrypted_registration_access_token BLOB,
+            registration_client_uri TEXT,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL
+        )
+        """
+    )
+
+    # OAuth flow sessions (ADR-004 Progressive Consent)
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS oauth_sessions (
+            session_id TEXT PRIMARY KEY,
+            client_id TEXT,
+            client_redirect_uri TEXT NOT NULL,
+            state TEXT,
+            code_challenge TEXT,
+            code_challenge_method TEXT,
+            mcp_authorization_code TEXT UNIQUE,
+            idp_access_token TEXT,
+            idp_refresh_token TEXT,
+            user_id TEXT,
+            created_at INTEGER NOT NULL,
+            expires_at INTEGER NOT NULL,
+            -- ADR-004 Progressive Consent fields
+            flow_type TEXT DEFAULT 'hybrid',
+            requested_scopes TEXT,
+            granted_scopes TEXT,
+            is_provisioning BOOLEAN DEFAULT FALSE
+        )
+        """
+    )
+
+    # Index for MCP authorization code lookups
+    op.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_oauth_sessions_mcp_code
+        ON oauth_sessions(mcp_authorization_code)
+        """
+    )
+
+    # Legacy schema version tracking table
+    # NOTE: This is deprecated in favor of Alembic's alembic_version table
+    # Kept for backward compatibility with pre-Alembic databases
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS schema_version (
+            version INTEGER PRIMARY KEY,
+            applied_at REAL NOT NULL
+        )
+        """
+    )
+
+    # Registered webhooks tracking (both BasicAuth and OAuth modes)
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS registered_webhooks (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            webhook_id INTEGER NOT NULL UNIQUE,
+            preset_id TEXT NOT NULL,
+            created_at REAL NOT NULL
+        )
+        """
+    )
+
+    # Indexes for efficient webhook queries
+    op.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_webhooks_preset
+        ON registered_webhooks(preset_id)
+        """
+    )
+
+    op.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_webhooks_created
+        ON registered_webhooks(created_at)
+        """
+    )
+
+
+def downgrade() -> None:
+    """Drop all tables and indexes.
+
+    WARNING: This will destroy all data in the database!
+    Use with extreme caution.
+    """
+
+    # Drop indexes first
+    op.execute("DROP INDEX IF EXISTS idx_webhooks_created")
+    op.execute("DROP INDEX IF EXISTS idx_webhooks_preset")
+    op.execute("DROP INDEX IF EXISTS idx_oauth_sessions_mcp_code")
+    op.execute("DROP INDEX IF EXISTS idx_audit_user_timestamp")
+
+    # Drop tables
+    op.execute("DROP TABLE IF EXISTS registered_webhooks")
+    op.execute("DROP TABLE IF EXISTS schema_version")
+    op.execute("DROP TABLE IF EXISTS oauth_sessions")
+    op.execute("DROP TABLE IF EXISTS oauth_clients")
+    op.execute("DROP TABLE IF EXISTS audit_logs")
+    op.execute("DROP TABLE IF EXISTS refresh_tokens")

nextcloud_mcp_server/alembic/versions/20260113_1200_002_add_app_passwords.py

@@ -0,0 +1,50 @@
+"""Add app_passwords table for multi-user BasicAuth mode
+
+This migration adds support for storing app passwords that are provisioned
+via Astrolabe's personal settings. This enables background sync in
+multi-user BasicAuth mode without requiring OAuth.
+
+Revision ID: 002
+Revises: 001
+Create Date: 2026-01-13 12:00:00.000000
+
+"""
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "002"
+down_revision = "001"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Add app_passwords table for multi-user BasicAuth mode."""
+
+    # App passwords table for multi-user BasicAuth background sync
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS app_passwords (
+            user_id TEXT PRIMARY KEY,
+            encrypted_password BLOB NOT NULL,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL
+        )
+        """
+    )
+
+    # Index for efficient user lookups
+    op.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_app_passwords_updated
+        ON app_passwords(updated_at)
+        """
+    )
+
+
+def downgrade() -> None:
+    """Drop app_passwords table."""
+
+    op.execute("DROP INDEX IF EXISTS idx_app_passwords_updated")
+    op.execute("DROP TABLE IF EXISTS app_passwords")

nextcloud_mcp_server/api/__init__.py

@@ -0,0 +1,76 @@
+"""Management API for Nextcloud MCP Server.
+
+Provides REST endpoints for the Nextcloud PHP app to query server status,
+user sessions, and vector sync metrics. All endpoints use OAuth bearer token
+authentication via the UnifiedTokenVerifier.
+
+This package is organized into modules by domain:
+- management.py: Server status, user sessions, shared helpers
+- passwords.py: App password provisioning for multi-user BasicAuth
+- webhooks.py: Webhook registration management
+- visualization.py: Search and PDF visualization endpoints
+"""
+
+# Re-export all public functions for backward compatibility
+from nextcloud_mcp_server.api.management import (
+    __version__,
+    _parse_float_param,
+    _parse_int_param,
+    _sanitize_error_for_client,
+    _validate_query_string,
+    extract_bearer_token,
+    get_server_status,
+    get_user_session,
+    get_vector_sync_status,
+    revoke_user_access,
+    validate_token_and_get_user,
+)
+from nextcloud_mcp_server.api.passwords import (
+    delete_app_password,
+    get_app_password_status,
+    provision_app_password,
+)
+from nextcloud_mcp_server.api.visualization import (
+    get_chunk_context,
+    get_pdf_preview,
+    unified_search,
+    vector_search,
+)
+from nextcloud_mcp_server.api.webhooks import (
+    create_webhook,
+    delete_webhook,
+    get_installed_apps,
+    list_webhooks,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Shared helpers (from management.py)
+    "extract_bearer_token",
+    "validate_token_and_get_user",
+    "_sanitize_error_for_client",
+    "_parse_int_param",
+    "_parse_float_param",
+    "_validate_query_string",
+    # Status endpoints (from management.py)
+    "get_server_status",
+    "get_vector_sync_status",
+    # Session endpoints (from management.py)
+    "get_user_session",
+    "revoke_user_access",
+    # Password endpoints (from passwords.py)
+    "provision_app_password",
+    "get_app_password_status",
+    "delete_app_password",
+    # Webhook endpoints (from webhooks.py)
+    "get_installed_apps",
+    "list_webhooks",
+    "create_webhook",
+    "delete_webhook",
+    # Visualization endpoints (from visualization.py)
+    "unified_search",
+    "vector_search",
+    "get_chunk_context",
+    "get_pdf_preview",
+]

nextcloud_mcp_server/api/management.py

@@ -0,0 +1,519 @@
+"""Management API endpoints for Nextcloud PHP app integration.
+
+ADR-018: Provides REST API endpoints for the Nextcloud PHP app to query:
+- Server status and version
+- User session information and background access status
+- Vector sync metrics
+
+All endpoints use OAuth bearer token authentication via UnifiedTokenVerifier.
+The PHP app obtains tokens through PKCE flow and uses them to access these endpoints.
+
+Shared helper functions for other API modules are also exported from here:
+- extract_bearer_token: Extract OAuth token from request
+- validate_token_and_get_user: Validate token and get user ID
+- _sanitize_error_for_client: Return safe error messages
+- _parse_int_param, _parse_float_param, _validate_query_string: Parameter validation
+"""
+
+import logging
+import time
+from importlib.metadata import version
+from typing import Any
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+logger = logging.getLogger(__name__)
+
+
+# Get package version from metadata
+__version__ = version("nextcloud-mcp-server")
+
+# Track server start time for uptime calculation
+_server_start_time = time.time()
+
+
+def extract_bearer_token(request: Request) -> str | None:
+    """Extract OAuth bearer token from Authorization header.
+
+    Args:
+        request: Starlette request
+
+    Returns:
+        Token string or None if no valid Authorization header
+    """
+    auth_header = request.headers.get("Authorization")
+    if not auth_header:
+        return None
+
+    # Parse "Bearer <token>"
+    parts = auth_header.split()
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        return None
+
+    return parts[1]
+
+
+async def validate_token_and_get_user(
+    request: Request,
+) -> tuple[str, dict[str, Any]]:
+    """Validate OAuth bearer token and extract user ID.
+
+    Uses verify_token_for_management_api which accepts any valid Nextcloud OIDC
+    token (not just MCP-audience tokens). This is needed because Astrolabe
+    (NC PHP app) uses its own OAuth client, separate from MCP server's client.
+
+    Security Model:
+    ~~~~~~~~~~~~~~~
+    - **Authentication** (this function): Verifies token is cryptographically valid
+      and extracts user identity from the `sub` claim.
+    - **Authorization** (calling endpoints): Each endpoint MUST verify that the
+      authenticated user owns the requested resource. For example:
+      - GET /users/{user_id}/session: Checks token_user_id == path_user_id (403 if mismatch)
+      - POST /users/{user_id}/revoke: Checks token_user_id == path_user_id (403 if mismatch)
+
+    This separation ensures that even without audience validation, users can only
+    access their own resources. Cross-user access is blocked at the authorization layer.
+
+    Args:
+        request: Starlette request with Authorization header
+
+    Returns:
+        Tuple of (user_id, validated_token_data)
+
+    Raises:
+        Exception: If token is invalid or missing
+    """
+    token = extract_bearer_token(request)
+    if not token:
+        raise ValueError("Missing Authorization header")
+
+    # Get token verifier from app state
+    # Note: This is set in app.py starlette_lifespan for OAuth mode
+    token_verifier = request.app.state.oauth_context["token_verifier"]
+
+    # Validate token for management API (handles both JWT and opaque tokens)
+    # Uses verify_token_for_management_api which accepts any valid Nextcloud token
+    # without requiring MCP audience - needed for Astrolabe integration (ADR-018)
+    access_token = await token_verifier.verify_token_for_management_api(token)
+
+    if not access_token:
+        raise ValueError("Token validation failed")
+
+    # Extract user ID from AccessToken.resource field (set during verification)
+    user_id = access_token.resource
+    if not user_id:
+        raise ValueError("Token missing user identifier")
+
+    # Return user_id and a dict with token info for compatibility
+    validated = {
+        "sub": user_id,
+        "client_id": access_token.client_id,
+        "scopes": access_token.scopes,
+        "expires_at": access_token.expires_at,
+    }
+
+    return user_id, validated
+
+
+def _sanitize_error_for_client(error: Exception, context: str = "") -> str:
+    """
+    Return a safe, generic error message for clients.
+
+    Detailed error is logged internally but not exposed to clients to prevent
+    information leakage (database paths, API URLs, tokens, etc.).
+
+    Args:
+        error: The exception that occurred
+        context: Optional context for logging (e.g., "revoke_user_access")
+
+    Returns:
+        Generic error message safe for client consumption
+    """
+    # Log detailed error for debugging
+    logger.error(f"Error in {context}: {error}", exc_info=True)
+
+    # Return generic message
+    return "An internal error occurred. Please contact your administrator."
+
+
+def _parse_int_param(
+    value: str | None,
+    default: int,
+    min_val: int,
+    max_val: int,
+    param_name: str,
+) -> int:
+    """Parse and validate integer parameter."""
+    if value is None:
+        return default
+    try:
+        parsed = int(value)
+    except ValueError:
+        raise ValueError(f"Invalid {param_name}: must be an integer")
+    if parsed < min_val or parsed > max_val:
+        raise ValueError(
+            f"Invalid {param_name}: must be between {min_val} and {max_val}"
+        )
+    return parsed
+
+
+def _parse_float_param(
+    value: Any,
+    default: float,
+    min_val: float,
+    max_val: float,
+    param_name: str,
+) -> float:
+    """Parse and validate float parameter."""
+    if value is None:
+        return default
+    try:
+        parsed = float(value)
+    except (ValueError, TypeError):
+        raise ValueError(f"Invalid {param_name}: must be a number")
+    if parsed < min_val or parsed > max_val:
+        raise ValueError(
+            f"Invalid {param_name}: must be between {min_val} and {max_val}"
+        )
+    return parsed
+
+
+def _validate_query_string(query: str, max_length: int = 10000) -> None:
+    """Validate query string length."""
+    if len(query) > max_length:
+        raise ValueError(f"Query too long: maximum {max_length} characters")
+
+
+async def get_server_status(request: Request) -> JSONResponse:
+    """GET /api/v1/status - Server status and version.
+
+    Returns basic server information including version, auth mode,
+    vector sync status, and uptime.
+
+    Public endpoint - no authentication required.
+    """
+    # Public endpoint - no authentication required
+
+    # Get configuration
+    from nextcloud_mcp_server.config import get_settings
+
+    settings = get_settings()
+
+    # Calculate uptime
+    uptime_seconds = int(time.time() - _server_start_time)
+
+    # Determine auth mode using proper mode detection
+    from nextcloud_mcp_server.config_validators import AuthMode, detect_auth_mode
+
+    mode = detect_auth_mode(settings)
+
+    # Map deployment mode to auth_mode for API response
+    # This helps clients (like Astrolabe) determine which auth flow to use
+    if mode == AuthMode.OAUTH_SINGLE_AUDIENCE or mode == AuthMode.OAUTH_TOKEN_EXCHANGE:
+        auth_mode = "oauth"
+    elif mode == AuthMode.MULTI_USER_BASIC:
+        auth_mode = "multi_user_basic"
+    elif mode == AuthMode.SINGLE_USER_BASIC:
+        auth_mode = "basic"
+    elif mode == AuthMode.SMITHERY_STATELESS:
+        auth_mode = "smithery"
+    else:
+        auth_mode = "unknown"
+
+    response_data = {
+        "version": __version__,
+        "auth_mode": auth_mode,
+        "vector_sync_enabled": settings.vector_sync_enabled,
+        "uptime_seconds": uptime_seconds,
+        "management_api_version": "1.0",
+    }
+
+    # Add app password support indicator for multi-user BasicAuth mode
+    if mode == AuthMode.MULTI_USER_BASIC:
+        response_data["supports_app_passwords"] = settings.enable_offline_access
+
+    # Include OIDC configuration if OAuth is available
+    # This includes OAuth mode AND hybrid mode (multi_user_basic + offline_access)
+    # Astrolabe needs OIDC config to discover IdP for OAuth flow in hybrid mode
+    oauth_provisioning_available = auth_mode == "oauth" or (
+        mode == AuthMode.MULTI_USER_BASIC and settings.enable_offline_access
+    )
+    if oauth_provisioning_available:
+        # Provide IdP discovery information for NC PHP app
+        oidc_config = {}
+
+        if settings.oidc_discovery_url:
+            oidc_config["discovery_url"] = settings.oidc_discovery_url
+
+        if settings.oidc_issuer:
+            oidc_config["issuer"] = settings.oidc_issuer
+
+        if oidc_config:
+            response_data["oidc"] = oidc_config
+
+    return JSONResponse(response_data)
+
+
+async def get_vector_sync_status(request: Request) -> JSONResponse:
+    """GET /api/v1/vector-sync/status - Vector sync metrics.
+
+    Returns real-time indexing status and metrics.
+
+    Requires: VECTOR_SYNC_ENABLED=true
+
+    Public endpoint - no authentication required.
+    """
+    # Public endpoint - no authentication required
+
+    from nextcloud_mcp_server.config import get_settings
+
+    settings = get_settings()
+    if not settings.vector_sync_enabled:
+        return JSONResponse(
+            {"error": "Vector sync is disabled on this server"},
+            status_code=404,
+        )
+
+    try:
+        # Get document receive stream from app state (set by starlette_lifespan in app.py)
+        document_receive_stream = getattr(
+            request.app.state, "document_receive_stream", None
+        )
+
+        if document_receive_stream is None:
+            logger.debug("document_receive_stream not available in app state")
+            return JSONResponse(
+                {
+                    "status": "unknown",
+                    "indexed_documents": 0,
+                    "pending_documents": 0,
+                    "message": "Vector sync stream not initialized",
+                }
+            )
+
+        # Get pending count from stream statistics
+        stream_stats = document_receive_stream.statistics()
+        pending_count = stream_stats.current_buffer_used
+
+        # Get Qdrant client and query indexed count
+        indexed_count = 0
+        try:
+            from qdrant_client.models import Filter
+
+            from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
+            from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+            qdrant_client = await get_qdrant_client()
+
+            # Count documents in collection, excluding placeholders
+            count_result = await qdrant_client.count(
+                collection_name=settings.get_collection_name(),
+                count_filter=Filter(must=[get_placeholder_filter()]),
+            )
+            indexed_count = count_result.count
+
+        except Exception as e:
+            logger.warning(f"Failed to query Qdrant for indexed count: {e}")
+            # Continue with indexed_count = 0
+
+        # Determine status
+        status = "syncing" if pending_count > 0 else "idle"
+
+        return JSONResponse(
+            {
+                "status": status,
+                "indexed_documents": indexed_count,
+                "pending_documents": pending_count,
+            }
+        )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "get_vector_sync_status")
+        return JSONResponse(
+            {"error": error_msg},
+            status_code=500,
+        )
+
+
+async def get_user_session(request: Request) -> JSONResponse:
+    """GET /api/v1/users/{user_id}/session - User session details.
+
+    Returns information about the user's MCP session including:
+    - Background access status (offline_access)
+    - IdP profile information
+
+    Requires OAuth bearer token. The user_id in the path must match
+    the user_id in the token.
+    """
+    try:
+        # Validate OAuth token and extract user
+        token_user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "get_user_session_auth")
+        return JSONResponse(
+            {"error": error_msg},
+            status_code=401,
+        )
+
+    # Get user_id from path
+    path_user_id = request.path_params.get("user_id")
+
+    # Verify token user matches requested user
+    if token_user_id != path_user_id:
+        logger.warning(
+            f"User {token_user_id} attempted to access session for {path_user_id}"
+        )
+        return JSONResponse(
+            {
+                "error": "Forbidden",
+                "message": "Cannot access another user's session",
+            },
+            status_code=403,
+        )
+
+    # Check if offline access is enabled
+    # Use settings.enable_offline_access which handles both ENABLE_BACKGROUND_OPERATIONS (new)
+    # and ENABLE_OFFLINE_ACCESS (deprecated) environment variables
+    from nextcloud_mcp_server.config import get_settings
+
+    settings = get_settings()
+    enable_offline_access = settings.enable_offline_access
+
+    if not enable_offline_access:
+        # Offline access disabled - return minimal session info
+        return JSONResponse(
+            {
+                "session_id": token_user_id,
+                "background_access_granted": False,
+            }
+        )
+
+    # Get refresh token storage from app state
+    storage = request.app.state.oauth_context.get("storage")
+    if not storage:
+        logger.error("Refresh token storage not available in app state")
+        return JSONResponse(
+            {
+                "session_id": token_user_id,
+                "background_access_granted": False,
+                "error": "Storage not configured",
+            }
+        )
+
+    try:
+        # Check if user has refresh token stored
+        refresh_token_data = await storage.get_refresh_token(token_user_id)
+
+        if not refresh_token_data:
+            # No refresh token - user hasn't provisioned background access
+            return JSONResponse(
+                {
+                    "session_id": token_user_id,
+                    "background_access_granted": False,
+                }
+            )
+
+        # User has background access - get profile info
+        profile = await storage.get_user_profile(token_user_id)
+
+        response_data = {
+            "session_id": token_user_id,
+            "background_access_granted": True,
+            "background_access_details": {
+                "granted_at": refresh_token_data.get("created_at"),
+                "scopes": refresh_token_data.get("scope", "").split(),
+            },
+        }
+
+        if profile:
+            response_data["idp_profile"] = profile
+
+        return JSONResponse(response_data)
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "get_user_session")
+        return JSONResponse(
+            {"error": error_msg},
+            status_code=500,
+        )
+
+
+async def revoke_user_access(request: Request) -> JSONResponse:
+    """POST /api/v1/users/{user_id}/revoke - Revoke user's background access.
+
+    Deletes the user's stored refresh token, removing their offline access.
+
+    Requires OAuth bearer token. The user_id in the path must match
+    the user_id in the token.
+    """
+    try:
+        # Validate OAuth token and extract user
+        token_user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/users/{{user_id}}/revoke: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "revoke_user_access"),
+            },
+            status_code=401,
+        )
+
+    # Get user_id from path
+    path_user_id = request.path_params.get("user_id")
+
+    # Verify token user matches requested user
+    if token_user_id != path_user_id:
+        logger.warning(
+            f"User {token_user_id} attempted to revoke access for {path_user_id}"
+        )
+        return JSONResponse(
+            {
+                "error": "Forbidden",
+                "message": "Cannot revoke another user's access",
+            },
+            status_code=403,
+        )
+
+    # Get token broker from app state
+    oauth_context = request.app.state.oauth_context
+    if oauth_context is None:
+        logger.error("OAuth context not initialized")
+        return JSONResponse(
+            {"error": "OAuth not enabled"},
+            status_code=500,
+        )
+
+    token_broker = oauth_context.get("token_broker")
+    if not token_broker:
+        logger.error("Token broker not available in app state")
+        return JSONResponse(
+            {"error": "Token broker not configured"},
+            status_code=500,
+        )
+
+    try:
+        # Delete refresh token from storage
+        await token_broker.storage.delete_refresh_token(token_user_id)
+
+        # CRITICAL: Invalidate all cached tokens for this user
+        await token_broker.cache.invalidate(token_user_id)
+
+        logger.info(
+            f"Revoked background access for user {token_user_id} (cache and storage cleared)"
+        )
+
+        return JSONResponse(
+            {
+                "success": True,
+                "message": f"Background access revoked for {token_user_id}",
+            }
+        )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "revoke_user_access")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )

nextcloud_mcp_server/api/passwords.py

@@ -0,0 +1,435 @@
+"""App password management API endpoints.
+
+Provides REST API endpoints for app password provisioning in multi-user BasicAuth mode.
+These endpoints are used by the Nextcloud PHP app (Astrolabe) to:
+- Store app passwords for background sync operations
+- Check app password status
+- Delete stored app passwords
+
+Authentication is via BasicAuth with the user's Nextcloud credentials.
+Passwords are validated against Nextcloud before being stored.
+"""
+
+import base64
+import logging
+import re
+import time
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+import httpx
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from ..http import nextcloud_httpx_client
+
+if TYPE_CHECKING:
+    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+from nextcloud_mcp_server.api.management import _sanitize_error_for_client
+
+logger = logging.getLogger(__name__)
+
+# App password format regex (Nextcloud format: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx)
+APP_PASSWORD_PATTERN = re.compile(
+    r"^[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}$"
+)
+
+# Timeout for Nextcloud API validation requests (seconds)
+NEXTCLOUD_VALIDATION_TIMEOUT = 10.0
+
+# Rate limiting configuration for app password provisioning
+# Limits: 5 attempts per user per hour
+RATE_LIMIT_MAX_ATTEMPTS = 5
+RATE_LIMIT_WINDOW_SECONDS = 3600  # 1 hour
+
+# In-memory rate limiter storage
+# Structure: {user_id: [(timestamp, success), ...]}
+_rate_limit_attempts: dict[str, list[tuple[float, bool]]] = defaultdict(list)
+
+
+def _check_rate_limit(user_id: str) -> tuple[bool, int]:
+    """Check if user is rate limited for app password operations.
+
+    Implements a sliding window rate limiter to prevent brute-force attacks
+    on the app password provisioning endpoint.
+
+    Args:
+        user_id: User identifier to check
+
+    Returns:
+        Tuple of (is_allowed, seconds_until_retry)
+        - is_allowed: True if request should be allowed
+        - seconds_until_retry: Seconds to wait if rate limited (0 if allowed)
+    """
+    current_time = time.time()
+    window_start = current_time - RATE_LIMIT_WINDOW_SECONDS
+
+    # Clean up old attempts outside the window
+    _rate_limit_attempts[user_id] = [
+        (ts, success)
+        for ts, success in _rate_limit_attempts[user_id]
+        if ts > window_start
+    ]
+
+    # Count recent attempts (both successful and failed)
+    recent_attempts = len(_rate_limit_attempts[user_id])
+
+    if recent_attempts >= RATE_LIMIT_MAX_ATTEMPTS:
+        # Find when the oldest attempt in the window will expire
+        oldest_attempt = min(ts for ts, _ in _rate_limit_attempts[user_id])
+        seconds_until_retry = int(
+            oldest_attempt + RATE_LIMIT_WINDOW_SECONDS - current_time
+        )
+        return False, max(1, seconds_until_retry)
+
+    return True, 0
+
+
+def _record_rate_limit_attempt(user_id: str, success: bool) -> None:
+    """Record an app password provisioning attempt for rate limiting.
+
+    Args:
+        user_id: User identifier
+        success: Whether the attempt was successful
+    """
+    _rate_limit_attempts[user_id].append((time.time(), success))
+
+
+def _extract_basic_auth(
+    request: Request, path_user_id: str
+) -> tuple[str, str, JSONResponse | None]:
+    """Extract and validate BasicAuth credentials from request.
+
+    Validates:
+    1. Authorization header is present and valid BasicAuth format
+    2. Username in credentials matches the path user_id
+
+    Args:
+        request: Starlette request with Authorization header
+        path_user_id: User ID from the URL path to verify against
+
+    Returns:
+        Tuple of (username, password, error_response)
+        - If successful: (username, password, None)
+        - If failed: ("", "", JSONResponse with error)
+    """
+    auth_header = request.headers.get("Authorization")
+
+    if not auth_header or not auth_header.startswith("Basic "):
+        return (
+            "",
+            "",
+            JSONResponse(
+                {"success": False, "error": "Missing BasicAuth credentials"},
+                status_code=401,
+            ),
+        )
+
+    try:
+        # Decode BasicAuth
+        encoded = auth_header.split(" ", 1)[1]
+        decoded = base64.b64decode(encoded).decode("utf-8")
+        username, password = decoded.split(":", 1)
+    except Exception:
+        return (
+            "",
+            "",
+            JSONResponse(
+                {"success": False, "error": "Invalid BasicAuth format"},
+                status_code=401,
+            ),
+        )
+
+    # Verify username matches path user_id
+    if username != path_user_id:
+        logger.warning(
+            f"Username mismatch in app password operation for path user {path_user_id}"
+        )
+        return (
+            "",
+            "",
+            JSONResponse(
+                {"success": False, "error": "Username does not match path user_id"},
+                status_code=403,
+            ),
+        )
+
+    return username, password, None
+
+
+async def _get_app_password_storage(request: Request) -> "RefreshTokenStorage":
+    """Get or initialize RefreshTokenStorage for app password operations.
+
+    Checks app.state.storage first, then falls back to creating from environment.
+    This helper avoids repeated storage initialization logic across endpoints.
+
+    Args:
+        request: Starlette request with app state
+
+    Returns:
+        Initialized RefreshTokenStorage instance
+    """
+    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+    storage = getattr(request.app.state, "storage", None)
+
+    if not storage:
+        # Multi-user BasicAuth mode may not have oauth_context
+        # Initialize storage from environment
+        storage = RefreshTokenStorage.from_env()
+        await storage.initialize()
+
+    return storage
+
+
+async def provision_app_password(request: Request) -> JSONResponse:
+    """POST /api/v1/users/{user_id}/app-password - Store app password for background sync.
+
+    This endpoint is used by Astrolabe (Nextcloud PHP app) to provision app passwords
+    for multi-user BasicAuth mode background sync.
+
+    The request must include BasicAuth credentials where:
+    - username: Nextcloud user ID (must match path user_id)
+    - password: The app password being provisioned
+
+    The MCP server validates the app password against Nextcloud before storing it.
+    This proves the user owns the password and has access to Nextcloud.
+
+    Security model:
+    - User identity is verified via BasicAuth against Nextcloud
+    - App password is encrypted before storage
+    - Only the user who owns the password can provision it
+    - Rate limited to prevent brute-force attacks
+    """
+    from nextcloud_mcp_server.config import get_settings
+
+    # Get user_id from path
+    path_user_id = request.path_params.get("user_id")
+    if not path_user_id:
+        return JSONResponse(
+            {"success": False, "error": "Missing user_id in path"},
+            status_code=400,
+        )
+
+    # Check rate limit before processing
+    is_allowed, retry_after = _check_rate_limit(path_user_id)
+    if not is_allowed:
+        logger.warning(
+            f"Rate limit exceeded for app password provisioning: {path_user_id}"
+        )
+        return JSONResponse(
+            {
+                "success": False,
+                "error": f"Rate limit exceeded. Try again in {retry_after} seconds.",
+            },
+            status_code=429,
+            headers={"Retry-After": str(retry_after)},
+        )
+
+    # Extract and validate BasicAuth credentials
+    username, app_password, error_response = _extract_basic_auth(request, path_user_id)
+    if error_response is not None:
+        _record_rate_limit_attempt(path_user_id, success=False)
+        return error_response
+
+    # Validate app password format
+    if not APP_PASSWORD_PATTERN.match(app_password):
+        _record_rate_limit_attempt(path_user_id, success=False)
+        return JSONResponse(
+            {"success": False, "error": "Invalid app password format"},
+            status_code=400,
+        )
+
+    # Get Nextcloud host from settings
+    settings = get_settings()
+    nextcloud_host = settings.nextcloud_host
+
+    if not nextcloud_host:
+        logger.error("NEXTCLOUD_HOST not configured")
+        return JSONResponse(
+            {"success": False, "error": "Server not configured"},
+            status_code=500,
+        )
+
+    # Validate app password against Nextcloud
+    try:
+        async with nextcloud_httpx_client(
+            timeout=NEXTCLOUD_VALIDATION_TIMEOUT
+        ) as client:
+            # Use OCS API to verify credentials
+            test_url = f"{nextcloud_host}/ocs/v1.php/cloud/user"
+            response = await client.get(
+                test_url,
+                auth=(username, app_password),
+                params={"format": "json"},
+                headers={"OCS-APIRequest": "true"},
+            )
+
+            if response.status_code != 200:
+                logger.warning(
+                    f"App password validation failed for user: HTTP {response.status_code}"
+                )
+                _record_rate_limit_attempt(path_user_id, success=False)
+                return JSONResponse(
+                    {"success": False, "error": "Invalid app password"},
+                    status_code=401,
+                )
+
+            # Verify the user ID from response matches
+            data = response.json()
+            ocs_user_id = data.get("ocs", {}).get("data", {}).get("id")
+            if ocs_user_id != username:
+                logger.warning("User ID mismatch in OCS response")
+                _record_rate_limit_attempt(path_user_id, success=False)
+                return JSONResponse(
+                    {"success": False, "error": "User ID mismatch"},
+                    status_code=403,
+                )
+
+    except httpx.RequestError as e:
+        logger.error(f"Failed to validate app password: {e}")
+        return JSONResponse(
+            {"success": False, "error": "Failed to validate credentials"},
+            status_code=500,
+        )
+
+    # Store the validated app password
+    try:
+        storage = await _get_app_password_storage(request)
+        await storage.store_app_password(username, app_password)
+
+        _record_rate_limit_attempt(path_user_id, success=True)
+        logger.info(f"Provisioned app password for user: {username}")
+
+        return JSONResponse(
+            {
+                "success": True,
+                "message": f"App password stored for {username}",
+            }
+        )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "provision_app_password")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )
+
+
+async def get_app_password_status(request: Request) -> JSONResponse:
+    """GET /api/v1/users/{user_id}/app-password - Check if user has provisioned app password.
+
+    Returns status of background sync access for multi-user BasicAuth mode.
+
+    Requires BasicAuth with the user's app password for authentication.
+    """
+    # Get user_id from path
+    path_user_id = request.path_params.get("user_id")
+    if not path_user_id:
+        return JSONResponse(
+            {"success": False, "error": "Missing user_id in path"},
+            status_code=400,
+        )
+
+    # Extract and validate BasicAuth credentials
+    username, _, error_response = _extract_basic_auth(request, path_user_id)
+    if error_response is not None:
+        return error_response
+
+    try:
+        storage = await _get_app_password_storage(request)
+        app_password = await storage.get_app_password(username)
+
+        return JSONResponse(
+            {
+                "success": True,
+                "user_id": username,
+                "has_app_password": app_password is not None,
+            }
+        )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "get_app_password_status")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )
+
+
+async def delete_app_password(request: Request) -> JSONResponse:
+    """DELETE /api/v1/users/{user_id}/app-password - Delete stored app password.
+
+    Removes the user's app password from MCP server storage.
+
+    Requires BasicAuth with the user's credentials.
+    """
+    from nextcloud_mcp_server.config import get_settings
+
+    # Get user_id from path
+    path_user_id = request.path_params.get("user_id")
+    if not path_user_id:
+        return JSONResponse(
+            {"success": False, "error": "Missing user_id in path"},
+            status_code=400,
+        )
+
+    # Extract and validate BasicAuth credentials
+    username, password, error_response = _extract_basic_auth(request, path_user_id)
+    if error_response is not None:
+        return error_response
+
+    # Validate credentials against Nextcloud
+    settings = get_settings()
+    nextcloud_host = settings.nextcloud_host
+
+    try:
+        async with nextcloud_httpx_client(
+            timeout=NEXTCLOUD_VALIDATION_TIMEOUT
+        ) as client:
+            test_url = f"{nextcloud_host}/ocs/v1.php/cloud/user"
+            response = await client.get(
+                test_url,
+                auth=(username, password),
+                params={"format": "json"},
+                headers={"OCS-APIRequest": "true"},
+            )
+
+            if response.status_code != 200:
+                return JSONResponse(
+                    {"success": False, "error": "Invalid credentials"},
+                    status_code=401,
+                )
+    except httpx.RequestError as e:
+        logger.error(f"Failed to validate credentials: {e}")
+        return JSONResponse(
+            {"success": False, "error": "Failed to validate credentials"},
+            status_code=500,
+        )
+
+    try:
+        storage = await _get_app_password_storage(request)
+        deleted = await storage.delete_app_password(username)
+
+        if deleted:
+            logger.info(f"Deleted app password for user: {username}")
+            return JSONResponse(
+                {
+                    "success": True,
+                    "message": f"App password deleted for {username}",
+                }
+            )
+        else:
+            return JSONResponse(
+                {
+                    "success": True,
+                    "message": "No app password found to delete",
+                }
+            )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "delete_app_password")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )

nextcloud_mcp_server/api/visualization.py

@@ -0,0 +1,813 @@
+"""Visualization API endpoints for search and PDF preview.
+
+ADR-018: Provides REST API endpoints for the Nextcloud PHP app (Astrolabe) to:
+- Execute unified search with semantic/BM25/hybrid algorithms
+- Execute vector search with PCA visualization coordinates
+- Fetch chunk context with surrounding text
+- Render PDF pages server-side (avoiding CSP/worker issues)
+
+All endpoints require OAuth bearer token authentication via UnifiedTokenVerifier.
+"""
+
+import base64
+import logging
+from typing import TYPE_CHECKING, Any
+
+import pymupdf
+
+if TYPE_CHECKING:
+    pass
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from nextcloud_mcp_server.api.management import (
+    _parse_float_param,
+    _parse_int_param,
+    _sanitize_error_for_client,
+    _validate_query_string,
+    extract_bearer_token,
+    validate_token_and_get_user,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def unified_search(request: Request) -> JSONResponse:
+    """POST /api/v1/search - Search endpoint for Nextcloud Unified Search.
+
+    Optimized search endpoint for the Nextcloud Unified Search provider
+    and other PHP app integrations. Returns results with metadata needed
+    for navigation to source documents.
+
+    Request body:
+    {
+        "query": "search query",
+        "algorithm": "semantic|bm25|hybrid",  // default: hybrid
+        "limit": 20,  // max: 100
+        "offset": 0,  // pagination offset
+        "include_pca": false,  // optional PCA coordinates
+        "include_chunks": true  // include text snippets
+    }
+
+    Response:
+    {
+        "results": [{
+            "id": "doc123",
+            "doc_type": "note",
+            "title": "Document Title",
+            "excerpt": "Matching text snippet...",
+            "score": 0.85,
+            "path": "/path/to/file.txt",  // for files
+            "board_id": 1,  // for deck cards
+            "card_id": 42
+        }],
+        "total_found": 150,
+        "algorithm_used": "hybrid"
+    }
+
+    Requires OAuth bearer token for user filtering.
+    """
+    from nextcloud_mcp_server.config import get_settings
+
+    settings = get_settings()
+    if not settings.vector_sync_enabled:
+        return JSONResponse(
+            {"error": "Vector sync is disabled on this server"},
+            status_code=404,
+        )
+
+    # Validate OAuth token and extract user
+    try:
+        user_id, _validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/search: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "unified_search"),
+            },
+            status_code=401,
+        )
+
+    try:
+        # Parse request body
+        body = await request.json()
+
+        # Validate and parse parameters
+        try:
+            query = body.get("query", "")
+            _validate_query_string(query, max_length=10000)
+
+            limit = _parse_int_param(
+                str(body.get("limit")) if body.get("limit") is not None else None,
+                20,
+                1,
+                100,
+                "limit",
+            )
+
+            offset = _parse_int_param(
+                str(body.get("offset")) if body.get("offset") is not None else None,
+                0,
+                0,
+                1000000,
+                "offset",
+            )
+
+            score_threshold = _parse_float_param(
+                body.get("score_threshold"),
+                0.0,
+                0.0,
+                1.0,
+                "score_threshold",
+            )
+        except ValueError as e:
+            return JSONResponse({"error": str(e)}, status_code=400)
+
+        algorithm = body.get("algorithm", "hybrid")
+        fusion = body.get("fusion", "rrf")
+        include_pca = body.get("include_pca", False)
+        include_chunks = body.get("include_chunks", True)
+        doc_types = body.get("doc_types")  # Optional filter
+
+        if not query:
+            return JSONResponse({"results": [], "total_found": 0})
+
+        # Validate algorithm
+        valid_algorithms = {"semantic", "bm25", "hybrid"}
+        if algorithm not in valid_algorithms:
+            algorithm = "hybrid"
+
+        # Validate fusion method
+        valid_fusions = {"rrf", "dbsf"}
+        if fusion not in valid_fusions:
+            fusion = "rrf"
+
+        # Execute search using the appropriate algorithm
+        from nextcloud_mcp_server.search import (
+            BM25HybridSearchAlgorithm,
+            SemanticSearchAlgorithm,
+        )
+
+        # Select search algorithm
+        if algorithm == "semantic":
+            search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
+        else:
+            search_algo = BM25HybridSearchAlgorithm(
+                score_threshold=score_threshold, fusion=fusion
+            )
+
+        # Request extra results to handle offset
+        search_limit = limit + offset
+
+        # Execute search
+        all_results = []
+        if doc_types and isinstance(doc_types, list):
+            for doc_type in doc_types:
+                if doc_type:
+                    results = await search_algo.search(
+                        query=query,
+                        user_id=user_id,
+                        limit=search_limit,
+                        doc_type=doc_type,
+                    )
+                    all_results.extend(results)
+            all_results.sort(key=lambda r: r.score, reverse=True)
+        else:
+            all_results = await search_algo.search(
+                query=query,
+                user_id=user_id,
+                limit=search_limit,
+            )
+
+        # Sort results by score (no deduplication - show all chunks)
+        sorted_results = sorted(all_results, key=lambda r: r.score, reverse=True)
+
+        # Calculate total and apply pagination
+        total_found = len(sorted_results)
+        paginated_results = sorted_results[offset : offset + limit]
+
+        # Format results for Unified Search
+        formatted_results = []
+        for result in paginated_results:
+            # Get document ID (prefer note_id for notes)
+            doc_id = result.id
+            if result.metadata and "note_id" in result.metadata:
+                doc_id = result.metadata["note_id"]
+
+            result_data: dict[str, Any] = {
+                "id": doc_id,
+                "doc_type": result.doc_type,
+                "title": result.title,
+                "score": result.score,
+            }
+
+            # Include excerpt/chunk if requested (full content, no truncation)
+            if include_chunks and result.excerpt:
+                result_data["excerpt"] = result.excerpt
+
+            # Include navigation metadata from result.metadata
+            if result.metadata:
+                # File path and mimetype for files
+                if "path" in result.metadata:
+                    result_data["path"] = result.metadata["path"]
+                if "mime_type" in result.metadata:
+                    result_data["mime_type"] = result.metadata["mime_type"]
+
+                # Deck card navigation
+                if "board_id" in result.metadata:
+                    result_data["board_id"] = result.metadata["board_id"]
+                if "card_id" in result.metadata:
+                    result_data["card_id"] = result.metadata["card_id"]
+
+                # Calendar event metadata
+                if "calendar_id" in result.metadata:
+                    result_data["calendar_id"] = result.metadata["calendar_id"]
+                if "event_uid" in result.metadata:
+                    result_data["event_uid"] = result.metadata["event_uid"]
+
+            # Add PDF page metadata
+            if result.page_number is not None:
+                result_data["page_number"] = result.page_number
+            if result.page_count is not None:
+                result_data["page_count"] = result.page_count
+
+            # Add chunk metadata (always present, defaults to 0 and 1)
+            result_data["chunk_index"] = result.chunk_index
+            result_data["total_chunks"] = result.total_chunks
+
+            # Add chunk offsets for modal navigation
+            if result.chunk_start_offset is not None:
+                result_data["chunk_start_offset"] = result.chunk_start_offset
+            if result.chunk_end_offset is not None:
+                result_data["chunk_end_offset"] = result.chunk_end_offset
+
+            formatted_results.append(result_data)
+
+        response_data: dict[str, Any] = {
+            "results": formatted_results,
+            "total_found": total_found,
+            "algorithm_used": algorithm,
+        }
+
+        # Optional PCA coordinates
+        if include_pca and len(paginated_results) >= 2:
+            try:
+                from nextcloud_mcp_server.vector.visualization import (
+                    compute_pca_coordinates,
+                )
+
+                if search_algo.query_embedding is not None:
+                    query_embedding = search_algo.query_embedding
+                else:
+                    from nextcloud_mcp_server.embedding.service import (
+                        get_embedding_service,
+                    )
+
+                    embedding_service = get_embedding_service()
+                    query_embedding = await embedding_service.embed(query)
+
+                pca_data = await compute_pca_coordinates(
+                    paginated_results, query_embedding
+                )
+                response_data["pca_data"] = pca_data
+            except Exception as e:
+                logger.warning(f"Failed to compute PCA for unified search: {e}")
+
+        return JSONResponse(response_data)
+
+    except Exception as e:
+        logger.error(f"Error in unified search: {e}")
+        return JSONResponse(
+            {
+                "error": "Internal error",
+                "message": _sanitize_error_for_client(e, "unified_search"),
+            },
+            status_code=500,
+        )
+
+
+async def vector_search(request: Request) -> JSONResponse:
+    """POST /api/v1/vector-viz/search - Vector search for visualization.
+
+    Executes semantic search and returns results with optional PCA coordinates
+    for 2D visualization.
+
+    Request body:
+    {
+        "query": "search query",
+        "algorithm": "semantic|bm25|hybrid",  // default: hybrid
+        "limit": 10,  // max: 50
+        "include_pca": true,  // whether to include 2D coordinates
+        "doc_types": ["note", "file"]  // optional filter by document types
+    }
+
+    Requires OAuth bearer token for user filtering.
+    """
+    from nextcloud_mcp_server.config import get_settings
+
+    settings = get_settings()
+    if not settings.vector_sync_enabled:
+        return JSONResponse(
+            {"error": "Vector sync is disabled on this server"},
+            status_code=404,
+        )
+
+    # Validate OAuth token and extract user
+    try:
+        user_id, _validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/vector-viz/search: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "vector_search"),
+            },
+            status_code=401,
+        )
+
+    try:
+        # Parse request body
+        body = await request.json()
+        query = body.get("query", "")
+        algorithm = body.get("algorithm", "hybrid")
+        fusion = body.get("fusion", "rrf")
+        score_threshold = body.get("score_threshold", 0.0)
+        limit = min(body.get("limit", 10), 50)  # Enforce max limit
+        include_pca = body.get("include_pca", True)
+        doc_types = body.get("doc_types")  # Optional list of document types
+
+        if not query:
+            return JSONResponse(
+                {"error": "Missing required parameter: query"},
+                status_code=400,
+            )
+
+        # Validate algorithm
+        valid_algorithms = {"semantic", "bm25", "hybrid"}
+        if algorithm not in valid_algorithms:
+            algorithm = "hybrid"
+
+        # Validate fusion method
+        valid_fusions = {"rrf", "dbsf"}
+        if fusion not in valid_fusions:
+            fusion = "rrf"
+
+        # Execute search using the appropriate algorithm
+        from nextcloud_mcp_server.search import (
+            BM25HybridSearchAlgorithm,
+            SemanticSearchAlgorithm,
+        )
+
+        # Select search algorithm
+        if algorithm == "semantic":
+            search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
+        else:
+            # Both "hybrid" and "bm25" use the BM25HybridSearchAlgorithm
+            # which combines dense semantic and sparse BM25 vectors
+            search_algo = BM25HybridSearchAlgorithm(
+                score_threshold=score_threshold, fusion=fusion
+            )
+
+        # Execute search for each doc_type if specified, otherwise search all
+        all_results = []
+        if doc_types and isinstance(doc_types, list):
+            # Search each doc_type separately and merge results
+            for doc_type in doc_types:
+                if doc_type:  # Skip empty strings
+                    results = await search_algo.search(
+                        query=query,
+                        user_id=user_id,
+                        limit=limit,
+                        doc_type=doc_type,
+                    )
+                    all_results.extend(results)
+            # Sort merged results by score and limit
+            all_results.sort(key=lambda r: r.score, reverse=True)
+            all_results = all_results[:limit]
+        else:
+            # Search all document types
+            all_results = await search_algo.search(
+                query=query,
+                user_id=user_id,
+                limit=limit,
+            )
+
+        # Format results for PHP client
+        formatted_results = []
+        for result in all_results:
+            formatted_result = {
+                "id": result.id,
+                "doc_type": result.doc_type,
+                "title": result.title,
+                "excerpt": result.excerpt[:200] if result.excerpt else "",
+                "score": result.score,
+                "metadata": result.metadata,
+                # Chunk information for context display
+                "chunk_index": result.chunk_index,
+                "total_chunks": result.total_chunks,
+            }
+            # Include optional fields if present
+            if result.chunk_start_offset is not None:
+                formatted_result["chunk_start_offset"] = result.chunk_start_offset
+            if result.chunk_end_offset is not None:
+                formatted_result["chunk_end_offset"] = result.chunk_end_offset
+            if result.page_number is not None:
+                formatted_result["page_number"] = result.page_number
+            if result.page_count is not None:
+                formatted_result["page_count"] = result.page_count
+            formatted_results.append(formatted_result)
+
+        response_data: dict[str, Any] = {
+            "results": formatted_results,
+            "algorithm_used": algorithm,
+            "total_documents": len(formatted_results),
+        }
+
+        # Compute PCA coordinates for visualization using shared function
+        if include_pca and len(all_results) >= 2:
+            try:
+                from nextcloud_mcp_server.vector.visualization import (
+                    compute_pca_coordinates,
+                )
+
+                # Get query embedding from search algorithm or generate it
+                if search_algo.query_embedding is not None:
+                    query_embedding = search_algo.query_embedding
+                else:
+                    from nextcloud_mcp_server.embedding.service import (
+                        get_embedding_service,
+                    )
+
+                    embedding_service = get_embedding_service()
+                    query_embedding = await embedding_service.embed(query)
+
+                pca_data = await compute_pca_coordinates(all_results, query_embedding)
+                response_data["coordinates_3d"] = pca_data["coordinates_3d"]
+                response_data["query_coords"] = pca_data["query_coords"]
+                if "pca_variance" in pca_data:
+                    response_data["pca_variance"] = pca_data["pca_variance"]
+            except Exception as e:
+                logger.warning(f"Failed to compute PCA coordinates: {e}")
+                response_data["coordinates_3d"] = []
+                response_data["query_coords"] = []
+        elif include_pca:
+            # Not enough results for PCA
+            response_data["coordinates_3d"] = []
+            response_data["query_coords"] = []
+
+        return JSONResponse(response_data)
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "vector_search")
+        return JSONResponse(
+            {"error": error_msg},
+            status_code=500,
+        )
+
+
+async def get_chunk_context(request: Request) -> JSONResponse:
+    """GET /api/v1/chunk-context - Fetch chunk text with context.
+
+    Retrieves the matched chunk along with surrounding text and metadata.
+    Used by clients to display chunk context and highlighted PDFs.
+
+    Query parameters:
+        doc_type: Document type (e.g., "note")
+        doc_id: Document ID
+        start: Chunk start offset (character position)
+        end: Chunk end offset (character position)
+        context: Characters of context before/after (default: 500)
+
+    Requires OAuth bearer token for authentication.
+    """
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/chunk-context: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "get_chunk_context"),
+            },
+            status_code=401,
+        )
+
+    try:
+        # Get query parameters
+        doc_type = request.query_params.get("doc_type")
+        doc_id = request.query_params.get("doc_id")
+        start_str = request.query_params.get("start")
+        end_str = request.query_params.get("end")
+
+        # Validate required parameters
+        if not all([doc_type, doc_id, start_str, end_str]):
+            return JSONResponse(
+                {
+                    "success": False,
+                    "error": "Missing required parameters: doc_type, doc_id, start, end",
+                },
+                status_code=400,
+            )
+
+        # Type narrowing: we already checked these are not None above
+        assert start_str is not None
+        assert end_str is not None
+        assert doc_id is not None
+        assert doc_type is not None
+
+        # Parse and validate integer parameters with bounds checking
+        try:
+            context_chars = _parse_int_param(
+                request.query_params.get("context"),
+                500,
+                0,
+                10000,
+                "context_chars",
+            )
+            start = _parse_int_param(start_str, 0, 0, 10000000, "start")
+            end = _parse_int_param(end_str, 0, 0, 10000000, "end")
+            if end <= start:
+                raise ValueError("end must be greater than start")
+        except ValueError as e:
+            return JSONResponse({"success": False, "error": str(e)}, status_code=400)
+        # Convert doc_id to int if possible (most IDs are int)
+        doc_id_val: str | int = int(doc_id) if doc_id.isdigit() else doc_id
+
+        # Get bearer token for client initialization
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing token")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Initialize authenticated Nextcloud client
+        from nextcloud_mcp_server.client import NextcloudClient
+        from nextcloud_mcp_server.search.context import get_chunk_with_context
+
+        async with NextcloudClient.from_token(
+            base_url=nextcloud_host, token=token, username=user_id
+        ) as nc_client:
+            chunk_context = await get_chunk_with_context(
+                nc_client=nc_client,
+                user_id=user_id,
+                doc_id=doc_id_val,
+                doc_type=doc_type,
+                chunk_start=start,
+                chunk_end=end,
+                context_chars=context_chars,
+            )
+
+        if chunk_context is None:
+            return JSONResponse(
+                {
+                    "success": False,
+                    "error": f"Failed to fetch chunk context for {doc_type} {doc_id}",
+                },
+                status_code=404,
+            )
+
+        # For PDF files, also fetch the highlighted page image from Qdrant if available
+        # This is useful for clients that want to show a pre-rendered image
+        highlighted_page_image = None
+        page_number = chunk_context.page_number
+
+        if doc_type == "file":
+            try:
+                from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+                from nextcloud_mcp_server.config import get_settings
+                from nextcloud_mcp_server.vector.placeholder import (
+                    get_placeholder_filter,
+                )
+                from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+                settings = get_settings()
+                qdrant_client = await get_qdrant_client()
+
+                # Query for this specific chunk's highlighted image
+                points_response = await qdrant_client.scroll(
+                    collection_name=settings.get_collection_name(),
+                    scroll_filter=Filter(
+                        must=[
+                            get_placeholder_filter(),
+                            FieldCondition(
+                                key="doc_id", match=MatchValue(value=doc_id_val)
+                            ),
+                            FieldCondition(
+                                key="user_id", match=MatchValue(value=user_id)
+                            ),
+                            FieldCondition(
+                                key="chunk_start_offset", match=MatchValue(value=start)
+                            ),
+                            FieldCondition(
+                                key="chunk_end_offset", match=MatchValue(value=end)
+                            ),
+                        ]
+                    ),
+                    limit=1,
+                    with_vectors=False,
+                    with_payload=["highlighted_page_image", "page_number"],
+                )
+
+                if points_response[0]:
+                    payload = points_response[0][0].payload
+                    if payload:
+                        highlighted_page_image = payload.get("highlighted_page_image")
+                        # Trust Qdrant page number if available (might be more accurate than context expansion logic)
+                        if payload.get("page_number") is not None:
+                            page_number = payload.get("page_number")
+
+            except Exception as e:
+                logger.warning(f"Failed to fetch highlighted image: {e}")
+
+        # Build response
+        response_data = {
+            "success": True,
+            "chunk_text": chunk_context.chunk_text,
+            "before_context": chunk_context.before_context,
+            "after_context": chunk_context.after_context,
+            "has_more_before": chunk_context.has_before_truncation,
+            "has_more_after": chunk_context.has_after_truncation,
+            "page_number": page_number,
+            "chunk_index": chunk_context.chunk_index,
+            "total_chunks": chunk_context.total_chunks,
+        }
+
+        if highlighted_page_image:
+            response_data["highlighted_page_image"] = highlighted_page_image
+
+        return JSONResponse(response_data)
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "get_chunk_context")
+        return JSONResponse(
+            {"error": error_msg},
+            status_code=500,
+        )
+
+
+async def get_pdf_preview(request: Request) -> JSONResponse:
+    """GET /api/v1/pdf-preview - Render PDF page to PNG image.
+
+    Server-side PDF rendering using PyMuPDF. This endpoint allows Astrolabe
+    to display PDF pages without requiring client-side PDF.js, avoiding CSP
+    worker restrictions and ES private field issues in Chromium.
+
+    Query parameters:
+        file_path: WebDAV path to PDF file (e.g., "/Documents/report.pdf")
+        page: Page number (1-indexed, default: 1)
+        scale: Zoom factor for rendering (default: 2.0 = 144 DPI)
+
+    Returns:
+        {
+            "success": true,
+            "image": "<base64-encoded-png>",
+            "page_number": 1,
+            "total_pages": 10
+        }
+
+    Requires OAuth bearer token for authentication.
+    """
+    # Log incoming request
+    file_path_param = request.query_params.get("file_path", "<not provided>")
+    page_param = request.query_params.get("page", "1")
+    logger.info(f"PDF preview request: file_path={file_path_param}, page={page_param}")
+
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+        logger.info(f"PDF preview authenticated for user: {user_id}")
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/pdf-preview: {e}")
+        return JSONResponse(
+            {
+                "success": False,
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "get_pdf_preview"),
+            },
+            status_code=401,
+        )
+
+    try:
+        # Parse and validate parameters
+        file_path = request.query_params.get("file_path")
+        if not file_path:
+            return JSONResponse(
+                {"success": False, "error": "Missing required parameter: file_path"},
+                status_code=400,
+            )
+
+        # Validate no path traversal sequences
+        if ".." in file_path:
+            return JSONResponse(
+                {"success": False, "error": "Invalid file path"},
+                status_code=400,
+            )
+
+        try:
+            page_num = _parse_int_param(
+                request.query_params.get("page"), 1, 1, 10000, "page"
+            )
+            scale = _parse_float_param(
+                request.query_params.get("scale"), 2.0, 0.5, 5.0, "scale"
+            )
+        except ValueError as e:
+            return JSONResponse({"success": False, "error": str(e)}, status_code=400)
+
+        # Get bearer token for WebDAV authentication
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing token")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Download PDF via WebDAV using user's token
+        from nextcloud_mcp_server.client import NextcloudClient
+
+        async with NextcloudClient.from_token(
+            base_url=nextcloud_host, token=token, username=user_id
+        ) as nc_client:
+            pdf_bytes, _ = await nc_client.webdav.read_file(file_path)
+
+        # Check file size limit (50 MB)
+        max_pdf_size = 50 * 1024 * 1024
+        if len(pdf_bytes) > max_pdf_size:
+            return JSONResponse(
+                {
+                    "success": False,
+                    "error": f"PDF file exceeds maximum size limit ({max_pdf_size // (1024 * 1024)} MB)",
+                },
+                status_code=413,
+            )
+
+        # Render page with PyMuPDF
+        doc = pymupdf.open(stream=pdf_bytes, filetype="pdf")
+        try:
+            total_pages = doc.page_count
+
+            # Validate page number
+            if page_num > total_pages:
+                return JSONResponse(
+                    {
+                        "success": False,
+                        "error": f"Page {page_num} does not exist (document has {total_pages} pages)",
+                    },
+                    status_code=400,
+                )
+
+            page = doc[page_num - 1]  # 0-indexed
+            mat = pymupdf.Matrix(scale, scale)
+            pix = page.get_pixmap(matrix=mat, alpha=False)
+            png_bytes = pix.tobytes("png")
+        finally:
+            doc.close()
+
+        # Encode as base64
+        image_b64 = base64.b64encode(png_bytes).decode("ascii")
+
+        logger.info(
+            f"Rendered PDF preview: {file_path} page {page_num}/{total_pages}, "
+            f"{len(png_bytes):,} bytes"
+        )
+
+        return JSONResponse(
+            {
+                "success": True,
+                "image": image_b64,
+                "page_number": page_num,
+                "total_pages": total_pages,
+            }
+        )
+
+    except FileNotFoundError:
+        logger.warning(f"PDF file not found: {file_path_param}")
+        return JSONResponse(
+            {"success": False, "error": "PDF file not found"},
+            status_code=404,
+        )
+    except (pymupdf.FileDataError, pymupdf.EmptyFileError):
+        logger.warning(f"Invalid or corrupted PDF file: {file_path_param}")
+        return JSONResponse(
+            {"success": False, "error": "Invalid or corrupted PDF file"},
+            status_code=400,
+        )
+    except Exception as e:
+        logger.error(f"PDF preview error: {e}", exc_info=True)
+        error_msg = _sanitize_error_for_client(e, "get_pdf_preview")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )

nextcloud_mcp_server/api/webhooks.py

@@ -0,0 +1,309 @@
+"""Webhook management API endpoints.
+
+Provides REST API endpoints for managing webhook registrations with Nextcloud.
+These endpoints are used by the Nextcloud PHP app (Astrolabe) to:
+- List installed Nextcloud apps
+- Create, list, and delete webhook registrations
+
+All endpoints require OAuth bearer token authentication via UnifiedTokenVerifier.
+"""
+
+import logging
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from nextcloud_mcp_server.api.management import (
+    _sanitize_error_for_client,
+    extract_bearer_token,
+    validate_token_and_get_user,
+)
+
+from ..http import nextcloud_httpx_client
+
+logger = logging.getLogger(__name__)
+
+
+async def get_installed_apps(request: Request) -> JSONResponse:
+    """GET /api/v1/apps - Get list of installed Nextcloud apps.
+
+    Returns a list of installed app IDs for filtering webhook presets.
+
+    Requires OAuth bearer token for authentication.
+    """
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/apps: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "get_installed_apps"),
+            },
+            status_code=401,
+        )
+
+    try:
+        # Get Bearer token from request
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing Authorization header")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Create authenticated HTTP client
+        async with nextcloud_httpx_client(
+            base_url=nextcloud_host,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30.0,
+        ) as client:
+            # Get installed apps using OCS API
+            # Notes, Calendar, Deck, Tables, etc. are apps that support webhooks
+            # We check which ones are installed and enabled
+            ocs_url = "/ocs/v1.php/cloud/apps"
+            params = {"filter": "enabled"}
+
+            response = await client.get(
+                ocs_url,
+                params=params,
+                headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+            )
+
+            if response.status_code != 200:
+                raise ValueError(f"OCS API returned status {response.status_code}")
+
+            data = response.json()
+            apps = data.get("ocs", {}).get("data", {}).get("apps", [])
+
+            return JSONResponse({"apps": apps})
+
+    except Exception as e:
+        logger.error(f"Error getting installed apps for user {user_id}: {e}")
+        return JSONResponse(
+            {
+                "error": "Internal error",
+                "message": _sanitize_error_for_client(e, "get_installed_apps"),
+            },
+            status_code=500,
+        )
+
+
+async def list_webhooks(request: Request) -> JSONResponse:
+    """GET /api/v1/webhooks - List all registered webhooks.
+
+    Returns list of webhook registrations for the authenticated user.
+
+    Requires OAuth bearer token for authentication.
+    """
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/webhooks: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "list_webhooks"),
+            },
+            status_code=401,
+        )
+
+    try:
+        from nextcloud_mcp_server.client.webhooks import WebhooksClient
+
+        # Get Bearer token from request
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing Authorization header")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Create authenticated HTTP client
+        async with nextcloud_httpx_client(
+            base_url=nextcloud_host,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30.0,
+        ) as client:
+            # Use WebhooksClient to list webhooks
+            webhooks_client = WebhooksClient(client, user_id)
+            webhooks = await webhooks_client.list_webhooks()
+
+            return JSONResponse({"webhooks": webhooks})
+
+    except Exception as e:
+        logger.error(f"Error listing webhooks for user {user_id}: {e}")
+        return JSONResponse(
+            {
+                "error": "Internal error",
+                "message": _sanitize_error_for_client(e, "list_webhooks"),
+            },
+            status_code=500,
+        )
+
+
+async def create_webhook(request: Request) -> JSONResponse:
+    """POST /api/v1/webhooks - Create a new webhook registration.
+
+    Request body:
+    {
+        "event": "OCP\\Files\\Events\\Node\\NodeCreatedEvent",
+        "uri": "http://mcp:8000/webhooks/nextcloud",
+        "eventFilter": {"event.node.path": "/^\\/.*\\/files\\/Notes\\//"}
+    }
+
+    Returns the created webhook data including the webhook ID.
+
+    Requires OAuth bearer token for authentication.
+    """
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/webhooks: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "create_webhook"),
+            },
+            status_code=401,
+        )
+
+    try:
+        from nextcloud_mcp_server.client.webhooks import WebhooksClient
+
+        # Parse request body
+        body = await request.json()
+        event = body.get("event")
+        uri = body.get("uri")
+        # Accept both camelCase (eventFilter) and snake_case (event_filter)
+        event_filter = body.get("eventFilter") or body.get("event_filter")
+
+        if not event or not uri:
+            return JSONResponse(
+                {
+                    "error": "Bad request",
+                    "message": "Missing required fields: event, uri",
+                },
+                status_code=400,
+            )
+
+        # Get Bearer token from request
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing Authorization header")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Create authenticated HTTP client
+        async with nextcloud_httpx_client(
+            base_url=nextcloud_host,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30.0,
+        ) as client:
+            # Use WebhooksClient to create webhook
+            webhooks_client = WebhooksClient(client, user_id)
+            webhook_data = await webhooks_client.create_webhook(
+                event=event, uri=uri, event_filter=event_filter
+            )
+
+            return JSONResponse({"webhook": webhook_data})
+
+    except Exception as e:
+        logger.error(f"Error creating webhook for user {user_id}: {e}")
+        return JSONResponse(
+            {
+                "error": "Internal error",
+                "message": _sanitize_error_for_client(e, "create_webhook"),
+            },
+            status_code=500,
+        )
+
+
+async def delete_webhook(request: Request) -> JSONResponse:
+    """DELETE /api/v1/webhooks/{webhook_id} - Delete a webhook registration.
+
+    Returns success/failure status.
+
+    Requires OAuth bearer token for authentication.
+    """
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/webhooks: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "delete_webhook"),
+            },
+            status_code=401,
+        )
+
+    try:
+        from nextcloud_mcp_server.client.webhooks import WebhooksClient
+
+        # Get webhook_id from path parameter
+        webhook_id = request.path_params.get("webhook_id")
+        if not webhook_id:
+            return JSONResponse(
+                {"error": "Bad request", "message": "Missing webhook_id"},
+                status_code=400,
+            )
+
+        try:
+            webhook_id = int(webhook_id)
+        except ValueError:
+            return JSONResponse(
+                {"error": "Bad request", "message": "Invalid webhook_id"},
+                status_code=400,
+            )
+
+        # Get Bearer token from request
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing Authorization header")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Create authenticated HTTP client
+        async with nextcloud_httpx_client(
+            base_url=nextcloud_host,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30.0,
+        ) as client:
+            # Use WebhooksClient to delete webhook
+            webhooks_client = WebhooksClient(client, user_id)
+            await webhooks_client.delete_webhook(webhook_id=webhook_id)
+
+            return JSONResponse({"success": True, "message": "Webhook deleted"})
+
+    except Exception as e:
+        logger.error(f"Error deleting webhook for user {user_id}: {e}")
+        return JSONResponse(
+            {
+                "error": "Internal error",
+                "message": _sanitize_error_for_client(e, "delete_webhook"),
+            },
+            status_code=500,
+        )

nextcloud_mcp_server/auth/astrolabe_client.py

@@ -0,0 +1,152 @@
+"""
+Client for querying Astrolabe Management API for background sync credentials.
+
+This client uses OAuth client credentials flow to authenticate to Nextcloud
+and retrieve user app passwords for background sync operations.
+"""
+
+import logging
+import time
+from typing import Optional
+
+from ..http import nextcloud_httpx_client
+
+logger = logging.getLogger(__name__)
+
+
+class AstrolabeClient:
+    """Client for querying Astrolabe API for background sync credentials.
+
+    Uses OAuth client credentials flow to authenticate as the MCP server
+    and retrieve user app passwords that are stored in Nextcloud.
+    """
+
+    def __init__(
+        self,
+        nextcloud_host: str,
+        client_id: str,
+        client_secret: str,
+    ):
+        """
+        Initialize Astrolabe client.
+
+        Args:
+            nextcloud_host: Nextcloud base URL (e.g., https://cloud.example.com)
+            client_id: OAuth client ID for MCP server
+            client_secret: OAuth client secret
+        """
+        self.nextcloud_host = nextcloud_host.rstrip("/")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._token_cache: Optional[dict] = None  # {access_token, expires_at}
+
+    async def get_access_token(self) -> str:
+        """
+        Get access token using OAuth client credentials flow.
+
+        Tokens are cached with 1-minute early refresh to avoid expiration.
+
+        Returns:
+            Access token string
+
+        Raises:
+            httpx.HTTPError: If token request fails
+        """
+        # Check cache
+        if self._token_cache and time.time() < self._token_cache["expires_at"]:
+            logger.debug("Using cached OAuth token for Astrolabe API")
+            return self._token_cache["access_token"]
+
+        # Discover token endpoint
+        discovery_url = f"{self.nextcloud_host}/.well-known/openid-configuration"
+
+        async with nextcloud_httpx_client() as client:
+            logger.debug(f"Discovering token endpoint from {discovery_url}")
+            discovery_resp = await client.get(discovery_url)
+            discovery_resp.raise_for_status()
+            token_endpoint = discovery_resp.json()["token_endpoint"]
+
+            logger.debug(f"Requesting client credentials token from {token_endpoint}")
+
+            # Request token using client credentials grant
+            token_resp = await client.post(
+                token_endpoint,
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": self.client_id,
+                    "client_secret": self.client_secret,
+                    "scope": "openid",  # Minimal scope
+                },
+            )
+            token_resp.raise_for_status()
+            data = token_resp.json()
+
+            # Cache with 1-minute early refresh
+            expires_in = data.get("expires_in", 3600)
+            self._token_cache = {
+                "access_token": data["access_token"],
+                "expires_at": time.time() + expires_in - 60,
+            }
+
+            logger.info(f"Obtained Astrolabe API token (expires in {expires_in}s)")
+            return data["access_token"]
+
+    async def get_user_app_password(self, user_id: str) -> Optional[str]:
+        """
+        Retrieve user's app password for background sync.
+
+        Args:
+            user_id: Nextcloud user ID
+
+        Returns:
+            App password string, or None if user hasn't provisioned
+
+        Raises:
+            httpx.HTTPError: If API request fails (except 404)
+        """
+        token = await self.get_access_token()
+        url = f"{self.nextcloud_host}/apps/astrolabe/api/v1/background-sync/credentials/{user_id}"
+
+        async with nextcloud_httpx_client() as client:
+            logger.debug(f"Retrieving app password for user: {user_id}")
+
+            response = await client.get(
+                url,
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=10.0,
+            )
+
+            if response.status_code == 404:
+                logger.debug(f"No app password configured for user: {user_id}")
+                return None
+
+            response.raise_for_status()
+            data = response.json()
+
+            logger.info(
+                f"Retrieved app password for user: {user_id} (type: {data.get('credential_type')})"
+            )
+            return data.get("app_password")
+
+    async def get_background_sync_status(self, user_id: str) -> dict:
+        """
+        Get background sync status for a user.
+
+        Args:
+            user_id: Nextcloud user ID
+
+        Returns:
+            Dict with keys: has_access, credential_type, provisioned_at
+
+        Raises:
+            httpx.HTTPError: If API request fails
+        """
+        # For now, check if app password exists
+        # In the future, this could query a dedicated status endpoint
+        app_password = await self.get_user_app_password(user_id)
+
+        return {
+            "has_access": app_password is not None,
+            "credential_type": "app_password" if app_password else None,
+            "provisioned_at": None,  # TODO: Get from API if available
+        }

nextcloud_mcp_server/auth/browser_oauth_routes.py

@@ -8,6 +8,7 @@ import hashlib
 import logging
 import os
 import secrets
+import time
 from base64 import urlsafe_b64encode
 from urllib.parse import urlencode
 
@@ -21,9 +22,31 @@ from nextcloud_mcp_server.auth.userinfo_routes import (
     _query_idp_userinfo,
 )
 
+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)
 
 
+def _should_use_secure_cookies() -> bool:
+    """Determine if cookies should have secure flag.
+
+    Checks COOKIE_SECURE env var first, then auto-detects from NEXTCLOUD_HOST.
+
+    Returns:
+        True if cookies should be secure (HTTPS), False otherwise
+    """
+    # Explicit configuration takes precedence
+    explicit = os.getenv("COOKIE_SECURE", "").lower()
+    if explicit == "true":
+        return True
+    if explicit == "false":
+        return False
+
+    # Auto-detect from NEXTCLOUD_HOST protocol
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST", "")
+    return nextcloud_host.startswith("https://")
+
+
 async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
     """Browser OAuth login endpoint - redirects to IdP for authentication.
 
@@ -50,6 +73,10 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
     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}")
 
+    # Get redirect URL from query params (default to /app)
+    next_url = request.query_params.get("next", "/app")
+    logger.info(f"oauth_login - next_url: {next_url}")
+
     # Generate state for CSRF protection
     state = secrets.token_urlsafe(32)
 
@@ -71,7 +98,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
     await storage.store_oauth_session(
         session_id=state,  # Use state as session ID
         client_id="browser-ui",
-        client_redirect_uri="/app",
+        client_redirect_uri=next_url,  # Store the redirect URL for after auth
         state=state,
         code_challenge=code_challenge,
         code_challenge_method="S256",
@@ -85,6 +112,11 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
         if not oauth_client.authorization_endpoint:
             await oauth_client.discover()
 
+        # Get Nextcloud resource URI for audience (background sync needs Nextcloud-scoped tokens)
+        nextcloud_resource_uri = oauth_config.get(
+            "nextcloud_resource_uri", oauth_config.get("nextcloud_host")
+        )
+
         idp_params = {
             "client_id": oauth_client.client_id,
             "redirect_uri": callback_uri,
@@ -94,6 +126,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
             "code_challenge": code_challenge,
             "code_challenge_method": "S256",
             "prompt": "consent",  # Ensure refresh token
+            "resource": nextcloud_resource_uri,  # Request tokens for Nextcloud API access
         }
 
         auth_url = f"{oauth_client.authorization_endpoint}?{urlencode(idp_params)}"
@@ -111,7 +144,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
             )
 
         # Fetch authorization endpoint
-        async with httpx.AsyncClient() as http_client:
+        async with nextcloud_httpx_client() as http_client:
             response = await http_client.get(discovery_url)
             response.raise_for_status()
             discovery = response.json()
@@ -131,6 +164,11 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
                     f"{public_parsed.scheme}://{public_parsed.netloc}{auth_parsed.path}"
                 )
 
+        # Get Nextcloud resource URI for audience (background sync needs Nextcloud-scoped tokens)
+        nextcloud_resource_uri = oauth_config.get(
+            "nextcloud_resource_uri", oauth_config.get("nextcloud_host")
+        )
+
         idp_params = {
             "client_id": oauth_config["client_id"],
             "redirect_uri": callback_uri,
@@ -140,6 +178,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
             "code_challenge": code_challenge,
             "code_challenge_method": "S256",
             "prompt": "consent",  # Ensure refresh token
+            "resource": nextcloud_resource_uri,  # Request tokens for Nextcloud API access
         }
 
         # Debug: Log full parameters
@@ -214,12 +253,15 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
     oauth_client = oauth_ctx["oauth_client"]
     oauth_config = oauth_ctx["config"]
 
-    # Retrieve code_verifier from session storage (PKCE required for all modes)
+    # Retrieve code_verifier and redirect URL from session storage
     code_verifier = ""
+    next_url = "/app"  # Default redirect
     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", "")
+        # next_url was stored in client_redirect_uri field
+        next_url = oauth_session.get("client_redirect_uri", "/app")
         # Clean up the temporary session
         # Note: We don't have delete_oauth_session method, but it will expire after TTL
 
@@ -246,7 +288,7 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
             if code_verifier:
                 token_params["code_verifier"] = code_verifier
 
-            async with httpx.AsyncClient() as http_client:
+            async with nextcloud_httpx_client() as http_client:
                 response = await http_client.post(
                     oauth_client.token_endpoint,
                     data=token_params,
@@ -256,7 +298,7 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
         else:
             # Integrated mode (Nextcloud OIDC)
             discovery_url = oauth_config.get("discovery_url")
-            async with httpx.AsyncClient() as http_client:
+            async with nextcloud_httpx_client() as http_client:
                 response = await http_client.get(discovery_url)
                 response.raise_for_status()
                 discovery = response.json()
@@ -274,7 +316,7 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
             if code_verifier:
                 token_params["code_verifier"] = code_verifier
 
-            async with httpx.AsyncClient() as http_client:
+            async with nextcloud_httpx_client() as http_client:
                 response = await http_client.post(
                     token_endpoint,
                     data=token_params,
@@ -338,16 +380,33 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
         user_id = f"user-{secrets.token_hex(8)}"
         username = "unknown"
 
+    # Calculate refresh token expiration from token response
+    refresh_expires_in = token_data.get("refresh_expires_in")
+    refresh_expires_at = None
+    if refresh_expires_in:
+        refresh_expires_at = int(time.time()) + refresh_expires_in
+        logger.info(
+            f"Refresh token expires in {refresh_expires_in}s (at timestamp {refresh_expires_at})"
+        )
+
+    # Extract granted scopes
+    granted_scopes = (
+        token_data.get("scope", "").split() if token_data.get("scope") else None
+    )
+
     # 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]}...")
+        logger.info(f"  Granted scopes: {granted_scopes}")
+        logger.info(f"  Expires at: {refresh_expires_at}")
         await storage.store_refresh_token(
             user_id=user_id,
             refresh_token=refresh_token,
-            expires_at=None,
+            expires_at=refresh_expires_at,
             flow_type="browser",  # Browser-based login flow
             provisioning_client_id=state,  # Store state for unified session lookup
+            scopes=granted_scopes,
         )
         logger.info(f"✓ Refresh token stored successfully for user_id: {user_id}")
         logger.info(
@@ -383,13 +442,14 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
             # Continue anyway - profile cache is optional for browser UI
 
     # Create response and set session cookie
-    response = RedirectResponse("/app", status_code=302)
+    # Redirect to stored next_url (from OAuth session) or /app as default
+    response = RedirectResponse(next_url, 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
+        secure=_should_use_secure_cookies(),
         samesite="lax",
     )
 

nextcloud_mcp_server/auth/client_registration.py

@@ -10,6 +10,8 @@ import httpx
 
 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 
+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)
 
 
@@ -132,7 +134,7 @@ async def register_client(
     logger.info(f"Registering OAuth client with Nextcloud: {client_name}")
     logger.debug(f"Registration endpoint: {registration_endpoint}")
 
-    async with httpx.AsyncClient(timeout=30.0) as client:
+    async with nextcloud_httpx_client(timeout=30.0) as client:
         try:
             response = await client.post(
                 registration_endpoint,
@@ -229,7 +231,7 @@ async def delete_client(
     logger.info(f"Deleting OAuth client: {client_id[:16]}...")
     logger.debug(f"Deletion endpoint: {deletion_endpoint}")
 
-    async with httpx.AsyncClient(timeout=30.0) as http_client:
+    async with nextcloud_httpx_client(timeout=30.0) as http_client:
         for attempt in range(max_retries):
             try:
                 # Prefer RFC 7592 Bearer token authentication

nextcloud_mcp_server/auth/keycloak_oauth.py

@@ -8,6 +8,7 @@ Handles OAuth flows with Keycloak as the identity provider, including:
 - Integration with RefreshTokenStorage
 """
 
+import base64
 import hashlib
 import logging
 import os
@@ -17,6 +18,8 @@ from urllib.parse import urlencode, urlparse
 
 import httpx
 
+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)
 
 
@@ -106,7 +109,7 @@ class KeycloakOAuthClient:
     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)
+            self._http_client = nextcloud_httpx_client(timeout=30.0)
         return self._http_client
 
     async def close(self) -> None:
@@ -155,7 +158,6 @@ class KeycloakOAuthClient:
         Returns:
             Tuple of (code_verifier, code_challenge)
         """
-        import base64
 
         # Generate code verifier (43-128 characters)
         code_verifier = secrets.token_urlsafe(32)

nextcloud_mcp_server/auth/oauth_routes.py

@@ -23,10 +23,10 @@ import hashlib
 import logging
 import os
 import secrets
+import time
 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
@@ -34,6 +34,8 @@ 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
 
+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)
 
 
@@ -217,7 +219,7 @@ async def oauth_authorize(request: Request) -> RedirectResponse | JSONResponse:
             )
 
         # Fetch authorization endpoint from discovery
-        async with httpx.AsyncClient() as http_client:
+        async with nextcloud_httpx_client() as http_client:
             response = await http_client.get(discovery_url)
             response.raise_for_status()
             discovery = response.json()
@@ -353,7 +355,7 @@ async def oauth_authorize_nextcloud(
             status_code=500,
         )
 
-    async with httpx.AsyncClient() as http_client:
+    async with nextcloud_httpx_client() as http_client:
         response = await http_client.get(discovery_url)
         response.raise_for_status()
         discovery = response.json()
@@ -461,7 +463,7 @@ async def oauth_callback_nextcloud(request: Request):
     callback_uri = f"{mcp_server_url}/oauth/callback"
 
     discovery_url = oauth_config.get("discovery_url")
-    async with httpx.AsyncClient() as http_client:
+    async with nextcloud_httpx_client() as http_client:
         response = await http_client.get(discovery_url)
         response.raise_for_status()
         discovery = response.json()
@@ -481,7 +483,7 @@ async def oauth_callback_nextcloud(request: Request):
         token_params["code_verifier"] = code_verifier
 
     # Exchange code for tokens
-    async with httpx.AsyncClient() as http_client:
+    async with nextcloud_httpx_client() as http_client:
         response = await http_client.post(
             token_endpoint,
             data=token_params,
@@ -517,12 +519,21 @@ async def oauth_callback_nextcloud(request: Request):
             token_data.get("scope", "").split() if token_data.get("scope") else None
         )
 
+        # Calculate refresh token expiration from token response
+        refresh_expires_in = token_data.get("refresh_expires_in")
+        refresh_expires_at = None
+        if refresh_expires_in:
+            refresh_expires_at = int(time.time()) + refresh_expires_in
+            logger.info(f"  refresh_expires_in: {refresh_expires_in}s")
+            logger.info(f"  refresh_expires_at: {refresh_expires_at}")
+
         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}")
+        logger.info(f"  expires_at: {refresh_expires_at}")
 
         await storage.store_refresh_token(
             user_id=user_id,
@@ -531,7 +542,7 @@ async def oauth_callback_nextcloud(request: Request):
             token_audience="nextcloud",
             provisioning_client_id=state,  # Store which client initiated provisioning
             scopes=granted_scopes,
-            expires_at=None,  # Refresh tokens typically don't expire
+            expires_at=refresh_expires_at,
         )
         logger.info(f"✓ Stored Flow 2 master refresh token for user {user_id}")
         logger.info("=" * 60)

nextcloud_mcp_server/auth/provisioning_decorator.py

@@ -9,6 +9,7 @@ import functools
 import logging
 from typing import Callable
 
+import jwt
 from mcp.server.fastmcp import Context
 from mcp.shared.exceptions import McpError
 from mcp.types import ErrorData
@@ -78,8 +79,6 @@ def require_provisioning(func: Callable) -> Callable:
         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")
@@ -163,8 +162,6 @@ def require_provisioning_or_suggest(func: Callable) -> Callable:
                 # 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")

nextcloud_mcp_server/auth/scope_authorization.py

@@ -1,7 +1,6 @@
 """Scope-based authorization for MCP tools."""
 
 import logging
-import os
 from functools import wraps
 from typing import Any, Callable
 
@@ -131,9 +130,12 @@ def require_scopes(*required_scopes: str):
             required_scopes_set = set(required_scopes)
 
             # Check if offline access is enabled
-            enable_offline_access = (
-                os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
-            )
+            # Use settings.enable_offline_access which handles both ENABLE_BACKGROUND_OPERATIONS (new)
+            # and ENABLE_OFFLINE_ACCESS (deprecated) environment variables
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            enable_offline_access = settings.enable_offline_access
 
             # In offline access mode, check if Nextcloud scopes require provisioning
             if enable_offline_access:

nextcloud_mcp_server/auth/static/vector-viz.css

@@ -190,3 +190,30 @@
     color: var(--color-text-maxcontrast);
     font-style: italic;
 }
+
+/* PDF highlighted image styles */
+.chunk-image-container {
+    margin-bottom: 16px;
+    border: 1px solid var(--color-border);
+    border-radius: var(--border-radius);
+    overflow: hidden;
+    background: #fff;
+}
+.chunk-image-header {
+    background: var(--color-background-dark);
+    padding: 8px 12px;
+    font-size: 12px;
+    font-weight: 500;
+    color: var(--color-text-maxcontrast);
+    border-bottom: 1px solid var(--color-border);
+    font-family: var(--font-face);
+}
+.chunk-highlighted-image {
+    display: block;
+    max-width: 100%;
+    height: auto;
+    cursor: zoom-in;
+}
+.chunk-highlighted-image:hover {
+    opacity: 0.95;
+}

nextcloud_mcp_server/auth/static/vector-viz.js

@@ -201,8 +201,15 @@ function vizApp() {
                     return `${baseUrl}/apps/calendar`;
                 case 'contact':
                     return `${baseUrl}/apps/contacts`;
-                case 'deck':
+                case 'deck_card':
+                    // URL pattern: /apps/deck/board/:boardId/card/:cardId
+                    if (result.metadata && result.metadata.board_id) {
+                        return `${baseUrl}/apps/deck/board/${result.metadata.board_id}/card/${result.id}`;
+                    }
+                    // Fallback if board_id not available
                     return `${baseUrl}/apps/deck`;
+                case 'news_item':
+                    return `${baseUrl}/apps/news/item/${result.id}`;
                 default:
                     return `${baseUrl}`;
             }
@@ -217,7 +224,7 @@ function vizApp() {
         },
 
         async toggleChunk(result) {
-            const resultKey = `${result.doc_type}_${result.id}`;
+            const resultKey = `${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`;
 
             if (this.isChunkExpanded(resultKey)) {
                 delete this.expandedChunks[resultKey];

nextcloud_mcp_server/auth/storage.py

@@ -28,6 +28,7 @@ Sensitive data (tokens, secrets) is encrypted at rest using Fernet symmetric enc
 import json
 import logging
 import os
+import socket
 import time
 from pathlib import Path
 from typing import Any, Optional
@@ -117,7 +118,14 @@ class RefreshTokenStorage:
         return cls(db_path=db_path, encryption_key=encryption_key)
 
     async def initialize(self) -> None:
-        """Initialize database schema"""
+        """
+        Initialize database schema using Alembic migrations.
+
+        This method handles three scenarios:
+        1. New database: Run migrations from scratch
+        2. Pre-Alembic database: Stamp with initial revision (no changes)
+        3. Alembic-managed database: Upgrade to latest version
+        """
         if self._initialized:
             return
 
@@ -125,137 +133,59 @@ class RefreshTokenStorage:
         db_dir = Path(self.db_path).parent
         db_dir.mkdir(parents=True, exist_ok=True)
 
-        # Set restrictive permissions on database file
+        # Set restrictive permissions on database file if it exists
         if Path(self.db_path).exists():
             os.chmod(self.db_path, 0o600)
 
+        # Check database state and run appropriate migration strategy
         async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS refresh_tokens (
-                    user_id TEXT PRIMARY KEY,
-                    encrypted_token BLOB NOT NULL,
-                    expires_at INTEGER,
-                    created_at INTEGER NOT NULL,
-                    updated_at INTEGER NOT NULL,
-                    -- ADR-004 Progressive Consent fields
-                    flow_type TEXT DEFAULT 'hybrid',  -- 'hybrid', 'flow1', 'flow2'
-                    token_audience TEXT DEFAULT 'nextcloud',  -- 'mcp-server' or 'nextcloud'
-                    provisioned_at INTEGER,  -- When Flow 2 was completed
-                    provisioning_client_id TEXT,  -- Which MCP client initiated Flow 1
-                    scopes TEXT,  -- JSON array of granted scopes
-                    -- Browser session profile cache
-                    user_profile TEXT,  -- JSON cache of IdP user profile (for browser UI only)
-                    profile_cached_at INTEGER  -- When profile was last cached
+            # Check if database is managed by Alembic
+            cursor = await db.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='alembic_version'"
+            )
+            has_alembic = await cursor.fetchone() is not None
+
+            if not has_alembic:
+                # Check if this is a pre-Alembic database with existing schema
+                cursor = await db.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table' AND name='refresh_tokens'"
                 )
-                """
-            )
+                has_schema = await cursor.fetchone() is not None
 
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS audit_logs (
-                    id INTEGER PRIMARY KEY AUTOINCREMENT,
-                    timestamp INTEGER NOT NULL,
-                    event TEXT NOT NULL,
-                    user_id TEXT NOT NULL,
-                    resource_type TEXT,
-                    resource_id TEXT,
-                    auth_method TEXT,
-                    hostname TEXT
+                if has_schema:
+                    logger.info(
+                        f"Detected pre-Alembic database at {self.db_path}, "
+                        "stamping with initial revision"
+                    )
+                else:
+                    logger.info(
+                        f"Initializing new database at {self.db_path} with migrations"
+                    )
+
+        # Run migrations in a worker thread using anyio.to_thread
+        # This allows Alembic to run its own async operations in a separate context
+        from anyio import to_thread
+
+        from nextcloud_mcp_server.migrations import stamp_database, upgrade_database
+
+        if not has_alembic:
+            if has_schema:
+                # Stamp existing database without running migrations
+                await to_thread.run_sync(stamp_database, self.db_path, "001")
+                logger.info(
+                    "Pre-Alembic database stamped successfully. "
+                    "Future schema changes will use migrations."
                 )
-                """
-            )
+            else:
+                # New database - run migrations
+                await to_thread.run_sync(upgrade_database, self.db_path, "head")
+                logger.info("Database initialized with migrations")
+        else:
+            # Alembic-managed database - upgrade to latest
+            await to_thread.run_sync(upgrade_database, self.db_path, "head")
+            logger.info("Database upgraded to latest version")
 
-            # Create index on audit logs for efficient queries
-            await db.execute(
-                "CREATE INDEX IF NOT EXISTS idx_audit_user_timestamp "
-                "ON audit_logs(user_id, timestamp)"
-            )
-
-            # OAuth client credentials storage
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS oauth_clients (
-                    id INTEGER PRIMARY KEY,
-                    client_id TEXT UNIQUE NOT NULL,
-                    encrypted_client_secret BLOB NOT NULL,
-                    client_id_issued_at INTEGER NOT NULL,
-                    client_secret_expires_at INTEGER NOT NULL,
-                    redirect_uris TEXT NOT NULL,
-                    encrypted_registration_access_token BLOB,
-                    registration_client_uri TEXT,
-                    created_at INTEGER NOT NULL,
-                    updated_at INTEGER NOT NULL
-                )
-                """
-            )
-
-            # OAuth flow sessions (ADR-004 Progressive Consent)
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS oauth_sessions (
-                    session_id TEXT PRIMARY KEY,
-                    client_id TEXT,
-                    client_redirect_uri TEXT NOT NULL,
-                    state TEXT,
-                    code_challenge TEXT,
-                    code_challenge_method TEXT,
-                    mcp_authorization_code TEXT UNIQUE,
-                    idp_access_token TEXT,
-                    idp_refresh_token TEXT,
-                    user_id TEXT,
-                    created_at INTEGER NOT NULL,
-                    expires_at INTEGER NOT NULL,
-                    -- ADR-004 Progressive Consent fields
-                    flow_type TEXT DEFAULT 'hybrid',  -- 'hybrid', 'flow1', 'flow2'
-                    requested_scopes TEXT,  -- JSON array of requested scopes
-                    granted_scopes TEXT,  -- JSON array of granted scopes
-                    is_provisioning BOOLEAN DEFAULT FALSE  -- True if this is a Flow 2 provisioning session
-                )
-                """
-            )
-
-            # Create index for MCP authorization code lookups
-            await db.execute(
-                "CREATE INDEX IF NOT EXISTS idx_oauth_sessions_mcp_code "
-                "ON oauth_sessions(mcp_authorization_code)"
-            )
-
-            # Schema version tracking
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS schema_version (
-                    version INTEGER PRIMARY KEY,
-                    applied_at REAL NOT NULL
-                )
-                """
-            )
-
-            # Registered webhooks tracking (both BasicAuth and OAuth modes)
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS registered_webhooks (
-                    id INTEGER PRIMARY KEY AUTOINCREMENT,
-                    webhook_id INTEGER NOT NULL UNIQUE,
-                    preset_id TEXT NOT NULL,
-                    created_at REAL NOT NULL
-                )
-                """
-            )
-
-            # Create indexes for efficient webhook queries
-            await db.execute(
-                "CREATE INDEX IF NOT EXISTS idx_webhooks_preset "
-                "ON registered_webhooks(preset_id)"
-            )
-            await db.execute(
-                "CREATE INDEX IF NOT EXISTS idx_webhooks_created "
-                "ON registered_webhooks(created_at)"
-            )
-
-            await db.commit()
-
-        # Set restrictive permissions after creation
+        # Set restrictive permissions after initialization
         os.chmod(self.db_path, 0o600)
 
         self._initialized = True
@@ -287,6 +217,8 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
         encrypted_token = self.cipher.encrypt(refresh_token.encode())
         now = int(time.time())
         scopes_json = json.dumps(scopes) if scopes else None
@@ -432,6 +364,9 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
+
         start_time = time.time()
         try:
             async with aiosqlite.connect(self.db_path) as db:
@@ -516,6 +451,9 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
+
         async with aiosqlite.connect(self.db_path) as db:
             async with db.execute(
                 """
@@ -687,6 +625,9 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
+
         # Encrypt sensitive data
         encrypted_secret = self.cipher.encrypt(client_secret.encode())
         encrypted_reg_token = (
@@ -757,6 +698,9 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
+
         async with aiosqlite.connect(self.db_path) as db:
             async with db.execute(
                 """
@@ -887,7 +831,6 @@ class RefreshTokenStorage:
             resource_id: Resource identifier
             auth_method: Authentication method used
         """
-        import socket
 
         hostname = socket.gethostname()
         timestamp = int(time.time())
@@ -1297,6 +1240,180 @@ class RefreshTokenStorage:
 
         return deleted
 
+    # ============================================================================
+    # App Password Storage (multi-user BasicAuth mode)
+    # ============================================================================
+
+    async def store_app_password(
+        self,
+        user_id: str,
+        app_password: str,
+    ) -> None:
+        """
+        Store encrypted app password for background sync (multi-user BasicAuth mode).
+
+        Args:
+            user_id: Nextcloud user ID
+            app_password: Nextcloud app password to store
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        if not self.cipher:
+            raise RuntimeError(
+                "Encryption key not configured. "
+                "Set TOKEN_ENCRYPTION_KEY for app password storage."
+            )
+
+        encrypted_password = self.cipher.encrypt(app_password.encode())
+        now = int(time.time())
+
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                await db.execute(
+                    """
+                    INSERT OR REPLACE INTO app_passwords
+                    (user_id, encrypted_password, created_at, updated_at)
+                    VALUES (
+                        ?,
+                        ?,
+                        COALESCE((SELECT created_at FROM app_passwords WHERE user_id = ?), ?),
+                        ?
+                    )
+                    """,
+                    (user_id, encrypted_password, user_id, now, now),
+                )
+                await db.commit()
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "insert", duration, "success")
+            logger.info(f"Stored app password for user {user_id}")
+
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "insert", duration, "error")
+            raise
+
+        # Audit log
+        await self._audit_log(
+            event="store_app_password",
+            user_id=user_id,
+            auth_method="app_password",
+        )
+
+    async def get_app_password(self, user_id: str) -> Optional[str]:
+        """
+        Retrieve and decrypt app password for a user.
+
+        Args:
+            user_id: Nextcloud user ID
+
+        Returns:
+            Decrypted app password, or None if not found
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        if not self.cipher:
+            raise RuntimeError(
+                "Encryption key not configured. "
+                "Set TOKEN_ENCRYPTION_KEY for app password retrieval."
+            )
+
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                async with db.execute(
+                    "SELECT encrypted_password FROM app_passwords WHERE user_id = ?",
+                    (user_id,),
+                ) as cursor:
+                    row = await cursor.fetchone()
+
+            if not row:
+                logger.debug(f"No app password found for user {user_id}")
+                duration = time.time() - start_time
+                record_db_operation("sqlite", "select", duration, "success")
+                return None
+
+            encrypted_password = row[0]
+            decrypted_password = self.cipher.decrypt(encrypted_password).decode()
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "select", duration, "success")
+            logger.debug(f"Retrieved app password for user {user_id}")
+
+            return decrypted_password
+
+        except Exception as e:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "select", duration, "error")
+            logger.error(f"Failed to decrypt app password for user {user_id}: {e}")
+            return None
+
+    async def delete_app_password(self, user_id: str) -> bool:
+        """
+        Delete app password for a user.
+
+        Args:
+            user_id: Nextcloud user ID
+
+        Returns:
+            True if password was deleted, False if not found
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                cursor = await db.execute(
+                    "DELETE FROM app_passwords WHERE user_id = ?",
+                    (user_id,),
+                )
+                await db.commit()
+                deleted = cursor.rowcount > 0
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "delete", duration, "success")
+
+            if deleted:
+                logger.info(f"Deleted app password for user {user_id}")
+                await self._audit_log(
+                    event="delete_app_password",
+                    user_id=user_id,
+                    auth_method="app_password",
+                )
+            else:
+                logger.debug(f"No app password to delete for user {user_id}")
+
+            return deleted
+
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "delete", duration, "error")
+            raise
+
+    async def get_all_app_password_user_ids(self) -> list[str]:
+        """
+        Get list of all user IDs with stored app passwords.
+
+        Returns:
+            List of user IDs
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            async with db.execute(
+                "SELECT user_id FROM app_passwords ORDER BY updated_at DESC"
+            ) as cursor:
+                rows = await cursor.fetchall()
+
+        user_ids = [row[0] for row in rows]
+        logger.debug(f"Found {len(user_ids)} users with app passwords")
+        return user_ids
+
 
 async def generate_encryption_key() -> str:
     """

nextcloud_mcp_server/auth/templates/vector_viz.html

@@ -65,8 +65,12 @@
                                     <span>Contacts</span>
                                 </label>
                                 <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="deck" style="margin-right: 4px;">
-                                    <span>Deck</span>
+                                    <input type="checkbox" x-model="docTypes" value="deck_card" style="margin-right: 4px;">
+                                    <span>Deck Cards</span>
+                                </label>
+                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
+                                    <input type="checkbox" x-model="docTypes" value="news_item" style="margin-right: 4px;">
+                                    <span>News</span>
                                 </label>
                             </div>
                         </div>
@@ -117,12 +121,13 @@
 
         <template x-if="!loading && results.length > 0">
             <div x-transition.opacity.duration.200ms>
-                <template x-for="result in results" :key="result.id">
+                <template x-for="result in results" :key="`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`">
                     <div style="padding: 12px; border-bottom: 1px solid #eee;">
                         <a :href="getNextcloudUrl(result)" target="_blank" style="font-weight: 500; color: #0066cc; text-decoration: none;">
                             <span x-text="result.title"></span>
                         </a>
-                        <div style="font-size: 14px; color: #666; margin-top: 4px;" x-text="result.excerpt"></div>
+                        <div style="font-size: 14px; color: #666; margin-top: 4px;"
+                             x-text="result.excerpt.length > 200 ? result.excerpt.substring(0, 200) + '...' : result.excerpt"></div>
                         <div style="font-size: 12px; color: #999; margin-top: 4px;">
                             Raw Score: <span x-text="result.original_score.toFixed(3)"></span>
                             (<span x-text="(result.score * 100).toFixed(0)"></span>% relative) |
@@ -134,22 +139,36 @@
                             <button
                                 class="chunk-toggle-btn"
                                 @click="toggleChunk(result)"
-                                x-text="isChunkExpanded(`${result.doc_type}_${result.id}`) ? 'Hide Chunk' : 'Show Chunk'"
+                                x-text="isChunkExpanded(`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`) ? 'Hide Chunk' : 'Show Chunk'"
                             ></button>
                         </template>
 
                         <!-- Chunk context (expanded inline) -->
-                        <template x-if="isChunkExpanded(`${result.doc_type}_${result.id}`)">
+                        <template x-if="isChunkExpanded(`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`)">
                             <div class="chunk-context" x-transition.opacity.duration.200ms>
-                                <template x-if="chunkLoading[`${result.doc_type}_${result.id}`]">
+                                <template x-if="chunkLoading[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]">
                                     <div style="color: #666; font-style: italic;">Loading chunk...</div>
                                 </template>
-                                <template x-if="!chunkLoading[`${result.doc_type}_${result.id}`]">
+                                <template x-if="!chunkLoading[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]">
                                     <div>
-                                        <template x-if="expandedChunks[`${result.doc_type}_${result.id}`]?.has_more_before">
+                                        <!-- Highlighted page image for PDFs -->
+                                        <template x-if="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.highlighted_page_image">
+                                            <div class="chunk-image-container">
+                                                <div class="chunk-image-header">
+                                                    <span>Page <span x-text="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.page_number"></span></span>
+                                                </div>
+                                                <img
+                                                    :src="'data:image/png;base64,' + expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.highlighted_page_image"
+                                                    :alt="'Page ' + expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.page_number"
+                                                    class="chunk-highlighted-image"
+                                                />
+                                            </div>
+                                        </template>
+                                        <!-- Text context -->
+                                        <template x-if="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.has_more_before">
                                             <span class="chunk-ellipsis">...</span>
                                         </template>
-                                        <span class="chunk-text" x-text="expandedChunks[`${result.doc_type}_${result.id}`]?.before_context"></span><span class="chunk-matched" x-text="expandedChunks[`${result.doc_type}_${result.id}`]?.chunk_text"></span><span class="chunk-text" x-text="expandedChunks[`${result.doc_type}_${result.id}`]?.after_context"></span><template x-if="expandedChunks[`${result.doc_type}_${result.id}`]?.has_more_after">
+                                        <span class="chunk-text" x-text="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.before_context"></span><span class="chunk-matched" x-text="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.chunk_text"></span><span class="chunk-text" x-text="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.after_context"></span><template x-if="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.has_more_after">
                                             <span class="chunk-ellipsis">...</span>
                                         </template>
                                     </div>

nextcloud_mcp_server/auth/token_broker.py

@@ -21,11 +21,12 @@ from typing import Dict, Optional, Tuple
 import anyio
 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
 
+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)
 
 
@@ -104,7 +105,8 @@ class TokenBrokerService:
         storage: RefreshTokenStorage,
         oidc_discovery_url: str,
         nextcloud_host: str,
-        encryption_key: str,
+        client_id: str,
+        client_secret: str,
         cache_ttl: int = 300,
         cache_early_refresh: int = 30,
     ):
@@ -112,33 +114,53 @@ class TokenBrokerService:
         Initialize the Token Broker Service.
 
         Args:
-            storage: Database storage for refresh tokens
+            storage: Database storage for refresh tokens (handles encryption internally)
             oidc_discovery_url: OIDC provider discovery URL
             nextcloud_host: Nextcloud server URL
-            encryption_key: Fernet key for token encryption
+            client_id: OAuth client ID for token operations
+            client_secret: OAuth client secret for token operations
             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.client_id = client_id
+        self.client_secret = client_secret
         self.cache = TokenCache(cache_ttl, cache_early_refresh)
         self._oidc_config = None
+
+        # Per-user locks for token refresh operations (prevents race conditions)
+        self._user_refresh_locks: dict[str, anyio.Lock] = {}
+        self._locks_lock = anyio.Lock()  # Protects the locks dict itself
         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(
+            self._http_client = nextcloud_httpx_client(
                 timeout=httpx.Timeout(30.0), follow_redirects=True
             )
         return self._http_client
 
+    async def _get_user_refresh_lock(self, user_id: str) -> anyio.Lock:
+        """
+        Get or create a lock for a specific user's refresh operations.
+
+        This prevents race conditions when multiple concurrent requests
+        attempt to refresh the same user's token simultaneously.
+
+        Args:
+            user_id: User ID to get lock for
+
+        Returns:
+            anyio.Lock for this user's refresh operations
+        """
+        async with self._locks_lock:
+            if user_id not in self._user_refresh_locks:
+                self._user_refresh_locks[user_id] = anyio.Lock()
+            return self._user_refresh_locks[user_id]
+
     async def _get_oidc_config(self) -> dict:
         """Get OIDC configuration from discovery endpoint."""
         if self._oidc_config is None:
@@ -180,9 +202,8 @@ class TokenBrokerService:
             return None
 
         try:
-            # Decrypt refresh token
-            encrypted_token = refresh_data["refresh_token"]
-            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()
+            # storage.get_refresh_token() returns already-decrypted token
+            refresh_token = refresh_data["refresh_token"]
 
             # Exchange refresh token for new access token
             access_token, expires_in = await self._refresh_access_token(refresh_token)
@@ -271,41 +292,79 @@ class TokenBrokerService:
         """
         # Check cache first (background tokens can be cached)
         cache_key = f"{user_id}:background:{','.join(sorted(required_scopes))}"
+        refresh_in_progress_key = f"{user_id}:refresh_in_progress"
+
         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
+        # Acquire per-user lock BEFORE refresh operation to prevent race conditions
+        refresh_lock = await self._get_user_refresh_lock(user_id)
+        async with refresh_lock:
+            # Double-check cache after acquiring lock
+            # (another thread may have refreshed while we waited)
+            cached_token = await self.cache.get(cache_key)
+            if cached_token:
+                logger.debug(
+                    f"Token found in cache after lock acquisition for user {user_id}"
+                )
+                return cached_token
 
-        try:
-            # Decrypt refresh token
-            encrypted_token = refresh_data["refresh_token"]
-            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()
+            # Check if another thread is currently refreshing
+            if await self.cache.get(refresh_in_progress_key):
+                logger.debug(f"Refresh in progress for user {user_id}, waiting briefly")
+                await anyio.sleep(0.1)  # Brief wait for in-progress refresh
+                # Check cache one more time after wait
+                cached_token = await self.cache.get(cache_key)
+                if cached_token:
+                    logger.debug(
+                        f"Token refreshed by another thread for user {user_id}"
+                    )
+                    return cached_token
 
-            # Get token with specific scopes for background operation
-            access_token, expires_in = await self._refresh_access_token_with_scopes(
-                refresh_token, required_scopes
-            )
+            # Mark refresh as in-progress
+            await self.cache.set(refresh_in_progress_key, "true", expires_in=5)
 
-            # Cache the background token
-            await self.cache.set(cache_key, access_token, expires_in)
+            try:
+                # 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
 
-            logger.info(
-                f"Generated background token for user {user_id} with scopes: {required_scopes}"
-            )
+                # storage.get_refresh_token() returns already-decrypted token
+                refresh_token = refresh_data["refresh_token"]
 
-            return access_token
+                # Get token with specific scopes for background operation
+                # Pass user_id to enable refresh token rotation storage
+                access_token, expires_in = await self._refresh_access_token_with_scopes(
+                    refresh_token, required_scopes, user_id=user_id
+                )
 
-        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
+                # Cache the background token
+                await self.cache.set(cache_key, access_token, expires_in)
 
-    async def _refresh_access_token(self, refresh_token: str) -> Tuple[str, int]:
+                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}",
+                    exc_info=True,
+                )
+                await self.cache.invalidate(cache_key)
+                return None
+
+            finally:
+                # Always clear the in-progress marker
+                await self.cache.invalidate(refresh_in_progress_key)
+
+    async def _refresh_access_token(
+        self, refresh_token: str, user_id: str | None = None
+    ) -> Tuple[str, int]:
         """
         Exchange refresh token for new access token.
 
@@ -313,6 +372,7 @@ class TokenBrokerService:
 
         Args:
             refresh_token: The refresh token
+            user_id: If provided, store the rotated refresh token for this user
 
         Returns:
             Tuple of (access_token, expires_in_seconds)
@@ -323,10 +383,13 @@ class TokenBrokerService:
         client = await self._get_http_client()
 
         # Request new access token using refresh token
+        # Include client credentials as required by most OAuth servers
         data = {
             "grant_type": "refresh_token",
             "refresh_token": refresh_token,
-            "scope": "openid profile email notes:read notes:write calendar:read calendar:write",
+            "scope": "openid profile email offline_access notes:read notes:write calendar:read calendar:write",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
         }
 
         response = await client.post(
@@ -345,23 +408,41 @@ class TokenBrokerService:
         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")
+        # Handle refresh token rotation (Nextcloud OIDC rotates on every use)
+        new_refresh_token = token_data.get("refresh_token")
+        if user_id and new_refresh_token and new_refresh_token != refresh_token:
+            # Calculate expiry as Unix timestamp (90 days from now)
+            expires_at = int(
+                (datetime.now(timezone.utc) + timedelta(days=90)).timestamp()
+            )
+            await self.storage.store_refresh_token(
+                user_id=user_id,
+                refresh_token=new_refresh_token,
+                expires_at=expires_at,
+            )
+            logger.info(f"Stored rotated refresh token for user {user_id}")
+
+        # Note: Nextcloud validates token audience on API calls - no need to pre-validate here
 
         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]
+        self, refresh_token: str, required_scopes: list[str], user_id: str | None = None
     ) -> Tuple[str, int]:
         """
         Exchange refresh token for new access token with specific scopes.
 
         This method implements scope downscoping for least privilege.
 
+        IMPORTANT: Nextcloud OIDC rotates refresh tokens on every use (one-time use).
+        When user_id is provided, this method stores the new refresh token returned
+        by Nextcloud to ensure subsequent refresh operations succeed.
+
         Args:
             refresh_token: The refresh token
             required_scopes: Minimal scopes needed for this operation
+            user_id: If provided, store the rotated refresh token for this user
 
         Returns:
             Tuple of (access_token, expires_in_seconds)
@@ -371,16 +452,25 @@ class TokenBrokerService:
 
         client = await self._get_http_client()
 
-        # Always include basic OpenID scopes
-        scopes = list(set(["openid", "profile", "email"] + required_scopes))
+        # Always include basic OpenID scopes + offline_access to get new refresh token
+        scopes = list(
+            set(["openid", "profile", "email", "offline_access"] + required_scopes)
+        )
 
         # Request new access token with specific scopes
+        # Include client credentials as required by most OAuth servers
         data = {
             "grant_type": "refresh_token",
             "refresh_token": refresh_token,
             "scope": " ".join(scopes),
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
         }
 
+        logger.info(
+            f"Token refresh request to {token_endpoint} with client_id={self.client_id[:16]}..."
+        )
+
         response = await client.post(
             token_endpoint,
             data=data,
@@ -391,14 +481,29 @@ class TokenBrokerService:
             logger.error(
                 f"Token refresh with scopes failed: {response.status_code} - {response.text}"
             )
+            logger.error(f"  client_id used: {self.client_id[:16]}...")
             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")
+        # Handle refresh token rotation (Nextcloud OIDC rotates on every use)
+        new_refresh_token = token_data.get("refresh_token")
+        if user_id and new_refresh_token and new_refresh_token != refresh_token:
+            # Store the new refresh token for future use
+            # Calculate expiry as Unix timestamp (90 days from now)
+            expires_at = int(
+                (datetime.now(timezone.utc) + timedelta(days=90)).timestamp()
+            )
+            await self.storage.store_refresh_token(
+                user_id=user_id,
+                refresh_token=new_refresh_token,
+                expires_at=expires_at,
+            )
+            logger.info(f"Stored rotated refresh token for user {user_id}")
+
+        # Note: Nextcloud validates token audience on API calls - no need to pre-validate here
 
         logger.info(
             f"Refreshed access token with scopes {scopes} (expires in {expires_in}s)"
@@ -453,11 +558,8 @@ class TokenBrokerService:
             return False
 
         try:
-            # Decrypt current refresh token
-            encrypted_token = refresh_data["refresh_token"]
-            current_refresh_token = self.fernet.decrypt(
-                encrypted_token.encode()
-            ).decode()
+            # storage.get_refresh_token() returns already-decrypted token
+            current_refresh_token = refresh_data["refresh_token"]
 
             # Get OIDC configuration
             config = await self._get_oidc_config()
@@ -486,13 +588,15 @@ class TokenBrokerService:
             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()
+                # storage.store_refresh_token() handles encryption internally
+                # Convert datetime to Unix timestamp (int) for database storage
+                expires_at = int(
+                    (datetime.now(timezone.utc) + timedelta(days=90)).timestamp()
+                )
                 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
+                    refresh_token=new_refresh_token,
+                    expires_at=expires_at,
                 )
                 logger.info(f"Rotated master refresh token for user {user_id}")
 
@@ -536,11 +640,8 @@ class TokenBrokerService:
             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()
+                    # storage.get_refresh_token() returns already-decrypted token
+                    refresh_token = refresh_data["refresh_token"]
                     await self._revoke_token_at_idp(refresh_token)
                 except Exception as e:
                     logger.warning(f"Failed to revoke at IdP: {e}")

nextcloud_mcp_server/auth/token_exchange.py

@@ -20,6 +20,7 @@ import httpx
 import jwt
 
 from ..config import get_settings
+from ..http import nextcloud_httpx_client
 from .storage import RefreshTokenStorage
 
 logger = logging.getLogger(__name__)
@@ -68,7 +69,7 @@ class TokenExchangeService:
         self.storage: Optional[RefreshTokenStorage] = None
 
         # Create HTTP client
-        self.http_client = httpx.AsyncClient(
+        self.http_client = nextcloud_httpx_client(
             timeout=30.0,
             follow_redirects=True,
         )

nextcloud_mcp_server/auth/unified_verifier.py

@@ -31,6 +31,8 @@ from nextcloud_mcp_server.observability.metrics import (
     record_oauth_token_validation,
 )
 
+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)
 
 
@@ -61,7 +63,7 @@ class UnifiedTokenVerifier(TokenVerifier):
         self.mode = "exchange" if settings.enable_token_exchange else "multi-audience"
 
         # Common components for all modes
-        self.http_client = httpx.AsyncClient(timeout=10.0)
+        self.http_client = nextcloud_httpx_client(timeout=10.0)
 
         # JWT verification support
         self.jwks_client: PyJWKClient | None = None
@@ -117,6 +119,71 @@ class UnifiedTokenVerifier(TokenVerifier):
         # Both modes do the same validation (MCP audience only)
         return await self._verify_mcp_audience(token)
 
+    async def verify_token_for_management_api(self, token: str) -> AccessToken | None:
+        """
+        Verify token for management API access (ADR-018 NC PHP app integration).
+
+        This verification accepts ANY valid Nextcloud OIDC token, not just tokens
+        with MCP server audience. This is needed because:
+        - Astrolabe (NC PHP app) uses its own OAuth client with Nextcloud OIDC
+        - Tokens from Astrolabe have Astrolabe's client_id as audience
+        - MCP server's management API should accept these tokens
+
+        Security Model:
+        ~~~~~~~~~~~~~~~~
+        This relaxed audience validation is secure because:
+
+        1. **Authentication layer** (this method):
+           - Verifies token signature against Nextcloud's JWKS (cryptographic proof)
+           - Verifies token is not expired
+           - Extracts user identity from validated token claims
+
+        2. **Authorization layer** (management API endpoints):
+           - EVERY endpoint verifies: token.sub == requested_resource_owner
+           - Example: GET /users/{user_id}/session checks token_user_id == path_user_id
+           - Users can ONLY access their own resources, never another user's
+
+        3. **Attack scenario analysis**:
+           - Attacker with stolen token for App A cannot access user B's data
+           - Token's `sub` claim is cryptographically bound to a specific user
+           - Authorization layer rejects cross-user access attempts (403 Forbidden)
+
+        4. **Why audience validation isn't needed here**:
+           - Audience validation prevents token confusion attacks across services
+           - But management API authorization already gates access per-user
+           - A token valid for "astrolabe" is still bound to user X, not user Y
+
+        Args:
+            token: Bearer token to verify
+
+        Returns:
+            AccessToken if valid (regardless of audience), None otherwise
+        """
+        # Check cache first (using separate cache key to avoid mixing with MCP tokens)
+        cache_key = f"mgmt:{hashlib.sha256(token.encode()).hexdigest()}"
+        if cache_key in self._token_cache:
+            userinfo, expiry = self._token_cache[cache_key]
+            if time.time() < expiry:
+                logger.debug("Management API token found in cache")
+                oauth_token_cache_hits_total.labels(hit="true").inc()
+                username = userinfo.get("sub") or userinfo.get("preferred_username")
+                scope_string = userinfo.get("scope", "")
+                scopes = scope_string.split() if scope_string else []
+                return AccessToken(
+                    token=token,
+                    client_id=userinfo.get("client_id", ""),
+                    scopes=scopes,
+                    expires_at=int(expiry),
+                    resource=username,
+                )
+            else:
+                del self._token_cache[cache_key]
+
+        oauth_token_cache_hits_total.labels(hit="false").inc()
+
+        # Verify token without audience check
+        return await self._verify_without_audience_check(token, cache_key)
+
     async def _verify_mcp_audience(self, token: str) -> AccessToken | None:
         """
         Validate token has MCP audience.
@@ -186,6 +253,78 @@ class UnifiedTokenVerifier(TokenVerifier):
             record_oauth_token_validation(validation_method, "error")
             return None
 
+    async def _verify_without_audience_check(
+        self, token: str, cache_key: str
+    ) -> AccessToken | None:
+        """
+        Verify token validity without checking MCP audience or issuer.
+
+        Used for management API where tokens from Astrolabe (NC PHP app) need to
+        be accepted. These tokens are issued by Nextcloud OIDC to Astrolabe's
+        OAuth client, not MCP server's client.
+
+        What we verify:
+        - ✓ Token signature (cryptographic proof token is from Nextcloud OIDC)
+        - ✓ Token expiration (not expired)
+        - ✓ Token structure (valid JWT format)
+
+        What we skip:
+        - ✗ Audience check (token may have Astrolabe's audience, not MCP's)
+        - ✗ Issuer check (token may have internal Nextcloud URL as issuer)
+
+        Security guarantee:
+        - Authorization is enforced by management API endpoints
+        - Each endpoint verifies: token.sub == requested_resource_owner
+        - See verify_token_for_management_api() docstring for full security model
+
+        Args:
+            token: Bearer token to verify
+            cache_key: Cache key for storing validation result
+
+        Returns:
+            AccessToken if valid, None otherwise
+        """
+        validation_method = "unknown"
+        try:
+            # Attempt JWT verification first
+            # Skip issuer check for management API tokens (may have internal URL)
+            if self._is_jwt_format(token) and self.jwks_client:
+                validation_method = "jwt"
+                payload = await self._verify_jwt_signature(
+                    token, skip_issuer_check=True
+                )
+                if payload:
+                    record_oauth_token_validation("jwt", "valid")
+                else:
+                    record_oauth_token_validation("jwt", "invalid")
+                    return None
+            else:
+                # Fall back to introspection for opaque tokens
+                validation_method = "introspect"
+                payload = await self._introspect_token(token)
+                if payload:
+                    record_oauth_token_validation("introspect", "valid")
+                else:
+                    record_oauth_token_validation("introspect", "invalid")
+                    return None
+
+            # Check payload is valid
+            if not payload:
+                return None
+
+            # Skip audience validation - any valid Nextcloud token is accepted
+            logger.debug(
+                f"Management API token validated (no audience check) for user: {payload.get('sub')}"
+            )
+
+            # Cache and return the token
+            return self._create_access_token_with_cache_key(token, payload, cache_key)
+
+        except Exception as e:
+            logger.error(f"Management API token verification failed: {e}")
+            record_oauth_token_validation(validation_method, "error")
+            return None
+
     def _has_mcp_audience(self, payload: dict[str, Any]) -> bool:
         """
         Check if token has MCP audience.
@@ -230,12 +369,15 @@ class UnifiedTokenVerifier(TokenVerifier):
         """
         return "." in token and token.count(".") == 2
 
-    async def _verify_jwt_signature(self, token: str) -> dict[str, Any] | None:
+    async def _verify_jwt_signature(
+        self, token: str, skip_issuer_check: bool = False
+    ) -> dict[str, Any] | None:
         """
         Verify JWT token with signature validation using JWKS.
 
         Args:
             token: JWT token to verify
+            skip_issuer_check: If True, skip issuer validation (for management API tokens)
 
         Returns:
             Decoded payload if valid, None if invalid
@@ -248,25 +390,22 @@ class UnifiedTokenVerifier(TokenVerifier):
 
             # Verify and decode JWT
             # Note: We don't validate audience here - that's done separately based on mode
+            # Issuer validation can be skipped for management API tokens (from Astrolabe)
+            should_verify_issuer = (
+                not skip_issuer_check
+                and hasattr(self.settings, "oidc_issuer")
+                and self.settings.oidc_issuer
+            )
             payload = jwt.decode(
                 token,
                 signing_key.key,
                 algorithms=["RS256"],
-                issuer=(
-                    self.settings.oidc_issuer
-                    if hasattr(self.settings, "oidc_issuer")
-                    else None
-                ),
+                issuer=(self.settings.oidc_issuer if should_verify_issuer else None),
                 options={
                     "verify_signature": True,
                     "verify_exp": True,
                     "verify_iat": True,
-                    "verify_iss": (
-                        True
-                        if hasattr(self.settings, "oidc_issuer")
-                        and self.settings.oidc_issuer
-                        else False
-                    ),
+                    "verify_iss": should_verify_issuer,
                     "verify_aud": False,  # We handle audience validation separately
                 },
             )
@@ -303,10 +442,13 @@ class UnifiedTokenVerifier(TokenVerifier):
 
         try:
             # Introspection requires client authentication
+            client_id = self.settings.oidc_client_id
+            client_secret = self.settings.oidc_client_secret
+            assert client_id is not None and client_secret is not None
             response = await self.http_client.post(
                 self.introspection_uri,
                 data={"token": token},
-                auth=(self.settings.oidc_client_id, self.settings.oidc_client_secret),
+                auth=(client_id, client_secret),
             )
 
             if response.status_code == 200:
@@ -355,6 +497,24 @@ class UnifiedTokenVerifier(TokenVerifier):
             token: The bearer token
             payload: Validated token payload
 
+        Returns:
+            AccessToken object or None if required fields missing
+        """
+        # Use default cache key (hash of token)
+        cache_key = hashlib.sha256(token.encode()).hexdigest()
+        return self._create_access_token_with_cache_key(token, payload, cache_key)
+
+    def _create_access_token_with_cache_key(
+        self, token: str, payload: dict[str, Any], cache_key: str
+    ) -> AccessToken | None:
+        """
+        Create AccessToken object from validated token payload with custom cache key.
+
+        Args:
+            token: The bearer token
+            payload: Validated token payload
+            cache_key: Key to use for caching (allows separate caches for MCP vs management API)
+
         Returns:
             AccessToken object or None if required fields missing
         """
@@ -379,14 +539,13 @@ class UnifiedTokenVerifier(TokenVerifier):
             logger.warning("No 'exp' claim in token, using default TTL")
             exp = int(time.time() + self.cache_ttl)
 
-        # Cache the result
-        token_hash = hashlib.sha256(token.encode()).hexdigest()
+        # Cache the result with the provided key
         userinfo = {
             "sub": username,
             "scope": scope_string,
             **{k: v for k, v in payload.items() if k not in ["sub", "scope"]},
         }
-        self._token_cache[token_hash] = (userinfo, exp)
+        self._token_cache[cache_key] = (userinfo, exp)
 
         return AccessToken(
             token=token,

nextcloud_mcp_server/auth/userinfo_routes.py

@@ -9,15 +9,20 @@ For OAuth mode: Requires browser-based OAuth login to establish session.
 
 import logging
 import os
+import traceback
 from pathlib import Path
 from typing import Any
 
-import httpx
 from jinja2 import Environment, FileSystemLoader
 from starlette.authentication import requires
 from starlette.requests import Request
 from starlette.responses import HTMLResponse, JSONResponse
 
+from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.config import get_settings
+
+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)
 
 # Setup Jinja2 environment for templates
@@ -25,14 +30,20 @@ _template_dir = Path(__file__).parent / "templates"
 _jinja_env = Environment(loader=FileSystemLoader(_template_dir))
 
 
-async def _get_authenticated_client_for_userinfo(request: Request) -> httpx.AsyncClient:
-    """Get an authenticated HTTP client for user info page operations.
+async def _get_authenticated_client_for_userinfo(request: Request) -> NextcloudClient:
+    """Get an authenticated Nextcloud client for user info page operations.
+
+    This is a shared helper for authenticated routes that need to access
+    Nextcloud APIs. It handles both BasicAuth and OAuth authentication modes.
 
     Args:
         request: Starlette request object
 
     Returns:
-        Authenticated httpx.AsyncClient
+        Authenticated NextcloudClient
+
+    Raises:
+        RuntimeError: If credentials/session not configured
     """
     oauth_ctx = getattr(request.app.state, "oauth_context", None)
 
@@ -45,11 +56,15 @@ async def _get_authenticated_client_for_userinfo(request: Request) -> httpx.Asyn
         if not all([nextcloud_host, username, password]):
             raise RuntimeError("BasicAuth credentials not configured")
 
-        assert nextcloud_host is not None  # Type narrowing for type checker
-        return httpx.AsyncClient(
+        from httpx import BasicAuth
+
+        assert nextcloud_host is not None
+        assert username is not None
+        assert password is not None
+        return NextcloudClient(
             base_url=nextcloud_host,
-            auth=(username, password),
-            timeout=30.0,
+            username=username,
+            auth=BasicAuth(username, password),
         )
 
     # OAuth mode - get token from session
@@ -64,15 +79,14 @@ async def _get_authenticated_client_for_userinfo(request: Request) -> httpx.Asyn
         raise RuntimeError("No access token found in session")
 
     access_token = token_data["access_token"]
+    username = token_data.get("username")
     nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
 
-    if not nextcloud_host:
-        raise RuntimeError("Nextcloud host not configured")
+    if not nextcloud_host or not username:
+        raise RuntimeError("Nextcloud host or username not configured")
 
-    return httpx.AsyncClient(
-        base_url=nextcloud_host,
-        headers={"Authorization": f"Bearer {access_token}"},
-        timeout=30.0,
+    return NextcloudClient.from_token(
+        base_url=nextcloud_host, token=access_token, username=username
     )
 
 
@@ -94,9 +108,9 @@ async def _get_processing_status(request: Request) -> dict[str, Any] | None:
             "status": str,  # "syncing" or "idle"
         }
     """
-    # Check if vector sync is enabled
-    vector_sync_enabled = os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
-    if not vector_sync_enabled:
+    # Check if vector sync is enabled (supports both old and new env var names)
+    settings = get_settings()
+    if not settings.vector_sync_enabled:
         return None
 
     try:
@@ -115,10 +129,8 @@ async def _get_processing_status(request: Request) -> dict[str, Any] | None:
         # Get Qdrant client and query indexed count
         indexed_count = 0
         try:
-            from nextcloud_mcp_server.config import get_settings
             from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
 
-            settings = get_settings()
             qdrant_client = await get_qdrant_client()
 
             # Count documents in collection
@@ -246,7 +258,7 @@ async def _get_userinfo_endpoint(oauth_ctx: dict[str, Any]) -> str | None:
         return None
 
     try:
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with nextcloud_httpx_client(timeout=10.0) as client:
             response = await client.get(discovery_url)
             response.raise_for_status()
             discovery = response.json()
@@ -279,7 +291,7 @@ async def _query_idp_userinfo(
         User info dictionary from IdP, or None if query fails
     """
     try:
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with nextcloud_httpx_client(timeout=10.0) as client:
             response = await client.get(
                 userinfo_uri,
                 headers={"Authorization": f"Bearer {access_token_str}"},
@@ -374,8 +386,6 @@ async def _get_user_info(request: Request) -> dict[str, Any]:
         return user_context
 
     except Exception as e:
-        import traceback
-
         logger.error(f"Error retrieving user info: {e}")
         logger.error(f"Traceback: {traceback.format_exc()}")
         return {
@@ -423,10 +433,10 @@ async def user_info_html(request: Request) -> HTMLResponse:
     try:
         from nextcloud_mcp_server.auth.permissions import is_nextcloud_admin
 
-        # Get authenticated HTTP client
-        http_client = await _get_authenticated_client_for_userinfo(request)
-        is_admin = await is_nextcloud_admin(request, http_client)
-        await http_client.aclose()
+        # Get authenticated Nextcloud client
+        nc_client = await _get_authenticated_client_for_userinfo(request)
+        is_admin = await is_nextcloud_admin(request, nc_client._client)
+        await nc_client.close()
     except Exception as e:
         logger.warning(f"Failed to check admin status: {e}")
         # Default to not admin if check fails
@@ -624,7 +634,9 @@ async def user_info_html(request: Request) -> HTMLResponse:
         """
 
     # Check if vector sync is enabled (needed for Welcome tab)
-    vector_sync_enabled = os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
+    # Note: get_settings() supports both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED
+    settings = get_settings()
+    vector_sync_enabled = settings.vector_sync_enabled
 
     # Render template
     template = _jinja_env.get_template("user_info.html")

nextcloud_mcp_server/auth/viz_routes.py

@@ -15,6 +15,7 @@ import logging
 import time
 from pathlib import Path
 
+import anyio
 import numpy as np
 from jinja2 import Environment, FileSystemLoader
 from starlette.authentication import requires
@@ -22,11 +23,13 @@ from starlette.requests import Request
 from starlette.responses import HTMLResponse, JSONResponse
 
 from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.observability.tracing import trace_operation
 from nextcloud_mcp_server.search import (
     BM25HybridSearchAlgorithm,
     SemanticSearchAlgorithm,
 )
 from nextcloud_mcp_server.vector.pca import PCA
+from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
 from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
 
 logger = logging.getLogger(__name__)
@@ -138,7 +141,10 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             _get_authenticated_client_for_userinfo,
         )
 
-        async with await _get_authenticated_client_for_userinfo(request) as http_client:  # noqa: F841
+        with trace_operation("vector_viz.get_auth_client"):
+            auth_client_ctx = await _get_authenticated_client_for_userinfo(request)
+
+        async with auth_client_ctx as nc_client:  # noqa: F841
             # Create search algorithm (no client needed - verification removed)
             if algorithm == "semantic":
                 search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
@@ -158,24 +164,40 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             all_results = []
             if doc_types is None or len(doc_types) == 0:
                 # Cross-app search - search all indexed types
-                unverified_results = await search_algo.search(
-                    query=query,
-                    user_id=username,
-                    limit=limit * 2,  # Buffer for verification filtering
-                    doc_type=None,  # Search all types
-                    score_threshold=score_threshold,
-                )
-                all_results.extend(unverified_results)
-            else:
-                # Search each document type and combine
-                for doc_type in doc_types:
+                with trace_operation(
+                    "vector_viz.search_execute",
+                    attributes={
+                        "search.algorithm": algorithm,
+                        "search.limit": limit * 2,
+                        "search.doc_type": "all",
+                    },
+                ):
                     unverified_results = await search_algo.search(
                         query=query,
                         user_id=username,
                         limit=limit * 2,  # Buffer for verification filtering
-                        doc_type=doc_type,
+                        doc_type=None,  # Search all types
                         score_threshold=score_threshold,
                     )
+                all_results.extend(unverified_results)
+            else:
+                # Search each document type and combine
+                for doc_type in doc_types:
+                    with trace_operation(
+                        "vector_viz.search_execute",
+                        attributes={
+                            "search.algorithm": algorithm,
+                            "search.limit": limit * 2,
+                            "search.doc_type": doc_type,
+                        },
+                    ):
+                        unverified_results = await search_algo.search(
+                            query=query,
+                            user_id=username,
+                            limit=limit * 2,  # Buffer for verification filtering
+                            doc_type=doc_type,
+                            score_threshold=score_threshold,
+                        )
                     all_results.extend(unverified_results)
                 # Sort by score before verification
                 all_results.sort(key=lambda r: r.score, reverse=True)
@@ -189,22 +211,26 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
         # Store original scores and normalize for visualization
         # (best result = 1.0, worst result = 0.0 within THIS result set)
         # This makes visual encoding meaningful regardless of RRF normalization
-        if search_results:
-            scores = [r.score for r in search_results]
-            min_score, max_score = min(scores), max(scores)
-            score_range = max_score - min_score if max_score > min_score else 1.0
+        with trace_operation(
+            "vector_viz.score_normalize",
+            attributes={"normalize.num_results": len(search_results)},
+        ):
+            if search_results:
+                scores = [r.score for r in search_results]
+                min_score, max_score = min(scores), max(scores)
+                score_range = max_score - min_score if max_score > min_score else 1.0
 
-            logger.info(
-                f"Normalizing scores for viz: original range [{min_score:.3f}, {max_score:.3f}] "
-                f"→ [0.0, 1.0]"
-            )
+                logger.info(
+                    f"Normalizing scores for viz: original range [{min_score:.3f}, {max_score:.3f}] "
+                    f"→ [0.0, 1.0]"
+                )
 
-            # Store original score and rescale to 0-1 for visualization
-            for r in search_results:
-                # Store original score before normalization
-                r.original_score = r.score
-                # Rescale for visual encoding
-                r.score = (r.score - min_score) / score_range
+                # Store original score and rescale to 0-1 for visualization
+                for r in search_results:
+                    # Store original score before normalization
+                    r.original_score = r.score
+                    # Rescale for visual encoding
+                    r.score = (r.score - min_score) / score_range
 
         if not search_results:
             return JSONResponse(
@@ -212,75 +238,57 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
                     "success": True,
                     "results": [],
                     "coordinates_3d": [],
-                    "query_coords": None,
+                    "query_coords": [],
                     "message": "No results found",
                 }
             )
 
-        # Fetch vectors for matching results from Qdrant
+        # Fetch vectors for specific matching chunks from Qdrant using batch retrieve
         vector_fetch_start = time.perf_counter()
-        qdrant_client = await get_qdrant_client()
-        doc_ids = [r.id for r in search_results]
 
-        # Retrieve vectors for the matching documents
-        from qdrant_client.models import FieldCondition, Filter, MatchAny
+        with trace_operation("vector_viz.get_qdrant_client"):
+            qdrant_client = await get_qdrant_client()
 
-        points_response = await qdrant_client.scroll(
-            collection_name=settings.get_collection_name(),
-            scroll_filter=Filter(
-                must=[
-                    FieldCondition(
-                        key="doc_id",
-                        match=MatchAny(any=[str(doc_id) for doc_id in doc_ids]),
-                    ),
-                    FieldCondition(
-                        key="user_id",
-                        match={"value": username},
-                    ),
-                ]
-            ),
-            limit=len(doc_ids) * 2,  # Account for multiple chunks per doc
-            with_vectors=["dense"],  # Only fetch dense vectors for visualization
-            with_payload=["doc_id"],  # Need doc_id to map vectors to results
-        )
+        chunk_vectors_map = {}  # Map (doc_id, chunk_start, chunk_end) -> vector
 
-        points = points_response[0]
+        # Collect point IDs from search results for batch retrieval
+        # point_id is the Qdrant internal ID returned by search algorithms
+        point_ids = [r.point_id for r in search_results if r.point_id]
 
-        if not points:
-            return JSONResponse(
-                {
-                    "success": True,
-                    "results": [],
-                    "coordinates_2d": [],
-                    "message": "No vectors found for results",
-                }
-            )
+        if point_ids:
+            # Single batch retrieve call instead of N sequential scroll calls
+            # This is ~50x faster for 50 results (1 HTTP request vs 50)
+            with trace_operation(
+                "vector_viz.vector_retrieve",
+                attributes={"retrieve.num_points": len(point_ids)},
+            ):
+                points_response = await qdrant_client.retrieve(
+                    collection_name=settings.get_collection_name(),
+                    ids=point_ids,
+                    with_vectors=["dense"],
+                    with_payload=["doc_id", "chunk_start_offset", "chunk_end_offset"],
+                )
 
-        # Extract dense vectors and group by document
-        def extract_dense_vector(point):
-            if point.vector is None:
-                return None
-            # If named vectors (dict), extract "dense"
-            if isinstance(point.vector, dict):
-                return point.vector.get("dense")
-            # If unnamed vector (array), use directly
-            return point.vector
+            # Build chunk_vectors_map from batch response
+            for point in points_response:
+                if point.vector is not None:
+                    # Extract dense vector (handle both named and unnamed vectors)
+                    if isinstance(point.vector, dict):
+                        vector = point.vector.get("dense")
+                    else:
+                        vector = point.vector
 
-        # Group chunk vectors by doc_id
-        from collections import defaultdict
-
-        doc_chunks = defaultdict(list)
-        for point in points:
-            if point.payload:
-                doc_id = int(point.payload.get("doc_id", 0))
-                vector = extract_dense_vector(point)
-                if vector is not None:
-                    doc_chunks[doc_id].append(vector)
+                    if vector is not None and point.payload:
+                        doc_id = point.payload.get("doc_id")
+                        chunk_start = point.payload.get("chunk_start_offset")
+                        chunk_end = point.payload.get("chunk_end_offset")
+                        chunk_key = (doc_id, chunk_start, chunk_end)
+                        chunk_vectors_map[chunk_key] = vector
 
         vector_fetch_duration = time.perf_counter() - vector_fetch_start
 
-        if len(doc_chunks) < 2:
-            # Not enough documents for PCA
+        if len(chunk_vectors_map) < 2:
+            # Not enough chunks for PCA
             return JSONResponse(
                 {
                     "success": True,
@@ -291,20 +299,21 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
                             "title": r.title,
                             "excerpt": r.excerpt,
                             "score": r.score,
+                            "metadata": r.metadata,
                         }
                         for r in search_results
                     ],
                     "coordinates_3d": [[0, 0, 0]] * len(search_results),
                     "query_coords": [0, 0, 0],
-                    "message": "Not enough documents for PCA",
+                    "message": "Not enough chunks for PCA",
                 }
             )
 
         # Detect embedding dimension from first available vector
         embedding_dim = None
-        for chunks in doc_chunks.values():
-            if chunks:
-                embedding_dim = len(chunks[0])
+        for vector in chunk_vectors_map.values():
+            if vector is not None:
+                embedding_dim = len(vector)
                 break
 
         if embedding_dim is None:
@@ -318,37 +327,42 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
 
         logger.info(f"Detected embedding dimension: {embedding_dim}")
 
-        # Average chunk vectors per document to create document-level embeddings
-        # Maintain order of search_results for coordinate mapping
-        doc_vectors = []
+        # Build chunk vectors array in search_results order (1:1 mapping)
+        chunk_vectors = []
         for result in search_results:
-            if result.id in doc_chunks:
-                # Average all chunk embeddings for this document
-                chunk_vectors = np.array(doc_chunks[result.id])
-                avg_vector = np.mean(chunk_vectors, axis=0)
-                doc_vectors.append(avg_vector)
-                logger.debug(f"Doc {result.id}: averaged {len(chunk_vectors)} chunks")
+            chunk_key = (result.id, result.chunk_start_offset, result.chunk_end_offset)
+            if chunk_key in chunk_vectors_map:
+                chunk_vectors.append(chunk_vectors_map[chunk_key])
             else:
-                # Document not found in vectors (shouldn't happen)
-                logger.warning(f"Doc {result.id} not found in fetched vectors")
-                # Use zero vector as fallback with detected dimension
-                doc_vectors.append(np.zeros(embedding_dim))
+                # Chunk not found in vectors (shouldn't happen)
+                logger.warning(
+                    f"Chunk {chunk_key} not found in fetched vectors, using zero vector"
+                )
+                # Use zero vector as fallback
+                chunk_vectors.append(np.zeros(embedding_dim))
 
-        doc_vectors = np.array(doc_vectors)
+        chunk_vectors = np.array(chunk_vectors)
 
-        # Generate query embedding for visualization
+        # Reuse query embedding from search algorithm (avoids redundant embedding call)
         query_embed_start = time.perf_counter()
-        from nextcloud_mcp_server.embedding.service import get_embedding_service
+        if search_algo.query_embedding is not None:
+            query_embedding = search_algo.query_embedding
+            logger.info(
+                f"Reusing query embedding from search algorithm "
+                f"(dimension={len(query_embedding)})"
+            )
+        else:
+            # Fallback: generate embedding if not available from search
+            from nextcloud_mcp_server.embedding.service import get_embedding_service
 
-        embedding_service = get_embedding_service()
-        query_embedding = await embedding_service.embed(query)
+            embedding_service = get_embedding_service()
+            query_embedding = await embedding_service.embed(query)
+            logger.info(f"Generated query embedding (dimension={len(query_embedding)})")
         query_embed_duration = time.perf_counter() - query_embed_start
 
-        logger.info(f"Generated query embedding (dimension={len(query_embedding)})")
-
-        # Combine query vector with document vectors for PCA
+        # Combine query vector with chunk vectors for PCA
         # Query will be the last point in the array
-        all_vectors = np.vstack([doc_vectors, np.array([query_embedding])])
+        all_vectors = np.vstack([chunk_vectors, np.array([query_embedding])])
 
         # Normalize vectors to unit length (L2 normalization)
         # This is critical because Qdrant uses COSINE distance, which only measures
@@ -375,9 +389,24 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
         )
 
         # Apply PCA dimensionality reduction (768-dim → 3D) on normalized vectors
+        # Run in thread pool to avoid blocking the event loop (CPU-bound)
         pca_start = time.perf_counter()
-        pca = PCA(n_components=3)
-        coords_3d = pca.fit_transform(all_vectors_normalized)
+
+        def _compute_pca(vectors: np.ndarray) -> tuple[np.ndarray, PCA]:
+            pca = PCA(n_components=3)
+            coords = pca.fit_transform(vectors)
+            return coords, pca
+
+        with trace_operation(
+            "vector_viz.pca_compute",
+            attributes={
+                "pca.num_vectors": len(all_vectors_normalized),
+                "pca.embedding_dim": embedding_dim,
+            },
+        ):
+            coords_3d, pca = await anyio.to_thread.run_sync(  # type: ignore[attr-defined]
+                lambda: _compute_pca(all_vectors_normalized)
+            )
         pca_duration = time.perf_counter() - pca_start
 
         # After fit, these attributes are guaranteed to be set
@@ -394,17 +423,12 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             # Replace NaN with 0 to allow JSON serialization
             coords_3d = np.nan_to_num(coords_3d, nan=0.0)
 
-        # Split query coords from document coords
+        # Split query coords from chunk coords
         # Round to 2 decimal places for cleaner display
         query_coords_3d = [
             round(float(x), 2) for x in coords_3d[-1]
         ]  # Last point is query
-        doc_coords_3d = coords_3d[:-1]  # All but last are documents
-
-        total_chunks = sum(len(chunks) for chunks in doc_chunks.values())
-        avg_chunks_per_doc = (
-            total_chunks / len(doc_vectors) if doc_vectors.size > 0 else 0
-        )
+        chunk_coords_3d = coords_3d[:-1]  # All but last are chunks
 
         logger.info(
             f"PCA explained variance: PC1={pca.explained_variance_ratio_[0]:.3f}, "
@@ -412,13 +436,14 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             f"PC3={pca.explained_variance_ratio_[2]:.3f}"
         )
         logger.info(
-            f"Embedding stats: documents={len(doc_vectors)}, "
-            f"total_chunks={total_chunks}, avg_chunks_per_doc={avg_chunks_per_doc:.1f}, "
-            f"query_dim={len(query_embedding)}, doc_vector_dim={doc_vectors.shape[1] if doc_vectors.size > 0 else 0}"
+            f"Embedding stats: chunks={len(chunk_vectors)}, "
+            f"query_dim={len(query_embedding)}, chunk_vector_dim={chunk_vectors.shape[1] if chunk_vectors.size > 0 else 0}"
         )
 
         # Coordinates already match search_results order (1:1 mapping)
-        result_coords = [[round(float(x), 2) for x in coord] for coord in doc_coords_3d]
+        result_coords = [
+            [round(float(x), 2) for x in coord] for coord in chunk_coords_3d
+        ]
 
         # Build response
         response_results = [
@@ -433,6 +458,7 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
                 ),  # Raw score from algorithm
                 "chunk_start_offset": r.chunk_start_offset,
                 "chunk_end_offset": r.chunk_end_offset,
+                "metadata": r.metadata,  # Include metadata (e.g., board_id for deck_card)
             }
             for r in search_results
         ]
@@ -447,7 +473,7 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             f"vector_fetch={vector_fetch_duration * 1000:.1f}ms ({vector_fetch_duration / total_duration * 100:.1f}%), "
             f"query_embed={query_embed_duration * 1000:.1f}ms ({query_embed_duration / total_duration * 100:.1f}%), "
             f"pca={pca_duration * 1000:.1f}ms ({pca_duration / total_duration * 100:.1f}%), "
-            f"results={len(search_results)}, doc_vectors={len(doc_vectors)}"
+            f"results={len(search_results)}, chunk_vectors={len(chunk_vectors)}"
         )
 
         return JSONResponse(
@@ -468,7 +494,7 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
                     "query_embed_ms": round(query_embed_duration * 1000, 2),
                     "pca_ms": round(pca_duration * 1000, 2),
                     "num_results": len(search_results),
-                    "num_doc_vectors": len(doc_vectors),
+                    "num_chunk_vectors": len(chunk_vectors),
                 },
             }
         )
@@ -517,77 +543,118 @@ async def chunk_context_endpoint(request: Request) -> JSONResponse:
                 status_code=400,
             )
 
+        # Type assertions - we validated these above
+        assert doc_type is not None
+        assert doc_id is not None
+        assert start_str is not None
+        assert end_str is not None
+
         start = int(start_str)
         end = int(end_str)
+        # Convert doc_id to int (all document types use int IDs)
+        doc_id_int = int(doc_id)
 
-        # Currently only support notes
-        if doc_type != "note":
-            return JSONResponse(
-                {"success": False, "error": f"Unsupported doc_type: {doc_type}"},
-                status_code=400,
-            )
-
-        # Get authenticated HTTP client and fetch note
+        # Get authenticated Nextcloud client
         from nextcloud_mcp_server.auth.userinfo_routes import (
             _get_authenticated_client_for_userinfo,
         )
-        from nextcloud_mcp_server.client.notes import NotesClient
+        from nextcloud_mcp_server.search.context import get_chunk_with_context
 
-        # Get username from request auth
-        username = (
-            request.user.display_name
-            if hasattr(request.user, "display_name")
-            else "unknown"
-        )
+        # Use context expansion module to fetch chunk with surrounding context
+        async with await _get_authenticated_client_for_userinfo(request) as nc_client:
+            chunk_context = await get_chunk_with_context(
+                nc_client=nc_client,
+                user_id=request.user.display_name,  # User ID from auth
+                doc_id=doc_id_int,
+                doc_type=doc_type,
+                chunk_start=start,
+                chunk_end=end,
+                context_chars=context_chars,
+            )
 
-        # Create notes client with authenticated HTTP client
-        http_client = await _get_authenticated_client_for_userinfo(request)
-        notes_client = NotesClient(http_client, username)
-
-        # Fetch full note content
-        note = await notes_client.get_note(int(doc_id))
-        full_content = f"{note['title']}\n\n{note['content']}"
-
-        # Validate offsets
-        if start < 0 or end > len(full_content) or start >= end:
+        # Check if context expansion succeeded
+        if chunk_context is None:
             return JSONResponse(
                 {
                     "success": False,
-                    "error": f"Invalid offsets: start={start}, end={end}, content_length={len(full_content)}",
+                    "error": f"Failed to fetch chunk context for {doc_type} {doc_id}",
                 },
-                status_code=400,
+                status_code=404,
             )
 
-        # Extract chunk
-        chunk_text = full_content[start:end]
-
-        # Extract context before and after
-        before_start = max(0, start - context_chars)
-        before_context = full_content[before_start:start]
-
-        after_end = min(len(full_content), end + context_chars)
-        after_context = full_content[end:after_end]
-
-        # Determine if there's more content
-        has_more_before = before_start > 0
-        has_more_after = after_end < len(full_content)
-
         logger.info(
             f"Fetched chunk context for {doc_type}_{doc_id}: "
-            f"chunk_len={len(chunk_text)}, before_len={len(before_context)}, "
-            f"after_len={len(after_context)}"
+            f"chunk_len={len(chunk_context.chunk_text)}, "
+            f"before_len={len(chunk_context.before_context)}, "
+            f"after_len={len(chunk_context.after_context)}"
         )
 
-        return JSONResponse(
-            {
-                "success": True,
-                "chunk_text": chunk_text,
-                "before_context": before_context,
-                "after_context": after_context,
-                "has_more_before": has_more_before,
-                "has_more_after": has_more_after,
-            }
-        )
+        # For PDF files, also fetch the highlighted page image from Qdrant
+        highlighted_page_image = None
+        page_number = None
+        if doc_type == "file":
+            try:
+                from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+                settings = get_settings()
+                qdrant_client = await get_qdrant_client()
+                username = request.user.display_name
+
+                # Query for this specific chunk's highlighted image
+                points_response = await qdrant_client.scroll(
+                    collection_name=settings.get_collection_name(),
+                    scroll_filter=Filter(
+                        must=[
+                            get_placeholder_filter(),
+                            FieldCondition(
+                                key="doc_id", match=MatchValue(value=doc_id_int)
+                            ),
+                            FieldCondition(
+                                key="user_id", match=MatchValue(value=username)
+                            ),
+                            FieldCondition(
+                                key="chunk_start_offset", match=MatchValue(value=start)
+                            ),
+                            FieldCondition(
+                                key="chunk_end_offset", match=MatchValue(value=end)
+                            ),
+                        ]
+                    ),
+                    limit=1,
+                    with_vectors=False,
+                    with_payload=["highlighted_page_image", "page_number"],
+                )
+
+                points = points_response[0]
+                if points and points[0].payload:
+                    highlighted_page_image = points[0].payload.get(
+                        "highlighted_page_image"
+                    )
+                    page_number = points[0].payload.get("page_number")
+                    if highlighted_page_image:
+                        logger.info(
+                            f"Found highlighted image for chunk: "
+                            f"page={page_number}, image_size={len(highlighted_page_image)}"
+                        )
+            except Exception as e:
+                logger.warning(f"Failed to fetch highlighted image: {e}")
+
+        # Return response compatible with frontend expectations
+        response_data: dict = {
+            "success": True,
+            "chunk_text": chunk_context.chunk_text,
+            "before_context": chunk_context.before_context,
+            "after_context": chunk_context.after_context,
+            "has_more_before": chunk_context.has_before_truncation,
+            "has_more_after": chunk_context.has_after_truncation,
+        }
+
+        # Add image data if available
+        if highlighted_page_image:
+            response_data["highlighted_page_image"] = highlighted_page_image
+            response_data["page_number"] = page_number
+
+        return JSONResponse(response_data)
 
     except ValueError as e:
         logger.error(f"Invalid parameter format: {e}")

nextcloud_mcp_server/auth/webhook_routes.py

@@ -20,6 +20,8 @@ from nextcloud_mcp_server.server.webhook_presets import (
     get_preset,
 )
 
+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)
 
 
@@ -139,7 +141,8 @@ async def _get_authenticated_client(request: Request) -> httpx.AsyncClient:
             raise RuntimeError("BasicAuth credentials not configured")
 
         assert nextcloud_host is not None  # Type narrowing for type checker
-        return httpx.AsyncClient(
+        assert username is not None and password is not None  # Type narrowing
+        return nextcloud_httpx_client(
             base_url=nextcloud_host,
             auth=(username, password),
             timeout=30.0,
@@ -162,7 +165,7 @@ async def _get_authenticated_client(request: Request) -> httpx.AsyncClient:
     if not nextcloud_host:
         raise RuntimeError("Nextcloud host not configured")
 
-    return httpx.AsyncClient(
+    return nextcloud_httpx_client(
         base_url=nextcloud_host,
         headers={"Authorization": f"Bearer {access_token}"},
         timeout=30.0,

nextcloud_mcp_server/cli.py

@@ -29,9 +29,9 @@ from .app import get_app
 @click.option(
     "--transport",
     "-t",
-    default="sse",
+    default="streamable-http",
     show_default=True,
-    type=click.Choice(["sse", "streamable-http", "http"]),
+    type=click.Choice(["streamable-http", "http"]),
     help="MCP transport protocol",
 )
 @click.option(
@@ -253,5 +253,195 @@ def run(
     )
 
 
+@click.group()
+def db():
+    """Database migration management commands."""
+    pass
+
+
+@db.command()
+@click.option(
+    "--database-path",
+    "-d",
+    envvar="TOKEN_STORAGE_DB",
+    default="/app/data/tokens.db",
+    show_default=True,
+    help="Path to token storage database (can also use TOKEN_STORAGE_DB env var)",
+)
+@click.option(
+    "--revision",
+    "-r",
+    default="head",
+    show_default=True,
+    help="Target revision (default: head for latest)",
+)
+def upgrade(database_path: str, revision: str):
+    """Upgrade database to a specific revision.
+
+    \b
+    Examples:
+      # Upgrade to latest version
+      $ nextcloud-mcp-server db upgrade
+
+      # Upgrade to specific revision
+      $ nextcloud-mcp-server db upgrade --revision 001
+
+      # Use custom database path
+      $ nextcloud-mcp-server db upgrade -d /path/to/tokens.db
+    """
+    from nextcloud_mcp_server.migrations import upgrade_database
+
+    try:
+        click.echo(f"Upgrading database to revision: {revision}")
+        upgrade_database(database_path, revision)
+        click.echo(click.style("✓ Database upgraded successfully", fg="green"))
+    except Exception as e:
+        click.echo(click.style(f"✗ Upgrade failed: {e}", fg="red"), err=True)
+        raise click.ClickException(str(e))
+
+
+@db.command()
+@click.option(
+    "--database-path",
+    "-d",
+    envvar="TOKEN_STORAGE_DB",
+    default="/app/data/tokens.db",
+    show_default=True,
+    help="Path to token storage database",
+)
+@click.option(
+    "--revision",
+    "-r",
+    default="-1",
+    show_default=True,
+    help="Target revision (default: -1 for previous version)",
+)
+@click.confirmation_option(
+    prompt="Are you sure you want to downgrade the database? This may result in data loss."
+)
+def downgrade(database_path: str, revision: str):
+    """Downgrade database to a specific revision.
+
+    WARNING: This may result in data loss! Use with caution.
+
+    \b
+    Examples:
+      # Downgrade by one version
+      $ nextcloud-mcp-server db downgrade
+
+      # Downgrade to specific revision
+      $ nextcloud-mcp-server db downgrade --revision 001
+
+      # Downgrade to base (empty database)
+      $ nextcloud-mcp-server db downgrade --revision base
+    """
+    from nextcloud_mcp_server.migrations import downgrade_database
+
+    try:
+        click.echo(f"Downgrading database to revision: {revision}")
+        downgrade_database(database_path, revision)
+        click.echo(click.style("✓ Database downgraded successfully", fg="green"))
+    except Exception as e:
+        click.echo(click.style(f"✗ Downgrade failed: {e}", fg="red"), err=True)
+        raise click.ClickException(str(e))
+
+
+@db.command()
+@click.option(
+    "--database-path",
+    "-d",
+    envvar="TOKEN_STORAGE_DB",
+    default="/app/data/tokens.db",
+    show_default=True,
+    help="Path to token storage database",
+)
+def current(database_path: str):
+    """Show current database revision.
+
+    \b
+    Example:
+      $ nextcloud-mcp-server db current
+    """
+    from nextcloud_mcp_server.migrations import get_current_revision
+
+    try:
+        revision = get_current_revision(database_path)
+        if revision:
+            click.echo(f"Current revision: {click.style(revision, fg='cyan')}")
+        else:
+            click.echo(
+                click.style(
+                    "Database is not versioned (no alembic_version table)", fg="yellow"
+                )
+            )
+    except Exception as e:
+        click.echo(
+            click.style(f"✗ Failed to get current revision: {e}", fg="red"), err=True
+        )
+        raise click.ClickException(str(e))
+
+
+@db.command()
+@click.option(
+    "--database-path",
+    "-d",
+    envvar="TOKEN_STORAGE_DB",
+    default="/app/data/tokens.db",
+    show_default=True,
+    help="Path to token storage database",
+)
+def history(database_path: str):
+    """Show migration history.
+
+    \b
+    Example:
+      $ nextcloud-mcp-server db history
+    """
+    from nextcloud_mcp_server.migrations import show_migration_history
+
+    try:
+        click.echo("Migration history:")
+        show_migration_history(database_path)
+    except Exception as e:
+        click.echo(click.style(f"✗ Failed to show history: {e}", fg="red"), err=True)
+        raise click.ClickException(str(e))
+
+
+@db.command()
+@click.argument("message")
+def migrate(message: str):
+    """Create a new migration script (developers only).
+
+    The MESSAGE argument describes the changes in this migration.
+
+    \b
+    Examples:
+      $ nextcloud-mcp-server db migrate "add user preferences table"
+      $ nextcloud-mcp-server db migrate "add index on refresh_tokens.user_id"
+
+    Note: You must manually edit the generated migration file to add SQL statements.
+    """
+    from nextcloud_mcp_server.migrations import create_migration
+
+    try:
+        click.echo(f"Creating new migration: {message}")
+        create_migration(message)
+        click.echo(click.style("✓ Migration created successfully", fg="green"))
+        click.echo(
+            "Edit the migration file in alembic/versions/ to add upgrade/downgrade SQL."
+        )
+    except Exception as e:
+        click.echo(
+            click.style(f"✗ Failed to create migration: {e}", fg="red"), err=True
+        )
+        raise click.ClickException(str(e))
+
+
+# Create CLI group with subcommands
+cli = click.Group()
+cli.add_command(run)
+cli.add_command(db)
+
+
 if __name__ == "__main__":
-    run()
+    cli()

nextcloud_mcp_server/client/__init__.py

@@ -4,7 +4,6 @@ import os
 from httpx import (
     AsyncBaseTransport,
     AsyncClient,
-    AsyncHTTPTransport,
     Auth,
     BasicAuth,
     Request,
@@ -13,11 +12,13 @@ from httpx import (
 )
 
 from ..controllers.notes_search import NotesSearchController
+from ..http import nextcloud_httpx_transport
 from .calendar import CalendarClient
 from .contacts import ContactsClient
 from .cookbook import CookbookClient
 from .deck import DeckClient
 from .groups import GroupsClient
+from .news import NewsClient
 from .notes import NotesClient
 from .sharing import SharingClient
 from .tables import TablesClient
@@ -66,7 +67,7 @@ class NextcloudClient:
         self._client = AsyncClient(
             base_url=base_url,
             auth=auth,
-            transport=AsyncDisableCookieTransport(AsyncHTTPTransport()),
+            transport=AsyncDisableCookieTransport(nextcloud_httpx_transport()),
             event_hooks={"request": [log_request], "response": [log_response]},
             timeout=Timeout(timeout=30, connect=5),
         )
@@ -81,6 +82,7 @@ class NextcloudClient:
         self.contacts = ContactsClient(self._client, username)
         self.cookbook = CookbookClient(self._client, username)
         self.deck = DeckClient(self._client, username)
+        self.news = NewsClient(self._client, username)
         self.users = UsersClient(self._client, username)
         self.groups = GroupsClient(self._client, username)
         self.sharing = SharingClient(self._client, username)
@@ -130,10 +132,75 @@ class NextcloudClient:
         all_notes = self.notes.get_all_notes()
         return await self._notes_search.search_notes(all_notes, query)
 
+    async def find_files_by_tag(
+        self, tag_name: str, mime_type_filter: str | None = None
+    ) -> list[dict]:
+        """Find files by system tag name, optionally filtered by MIME type.
+
+        This method coordinates tag lookup and file retrieval via WebDAV:
+        1. Look up the tag ID by name
+        2. Get all files with that tag (via REPORT with full metadata)
+        3. Optionally filter by MIME type
+
+        Args:
+            tag_name: Name of the system tag to search for (e.g., "vector-index")
+            mime_type_filter: Optional MIME type filter (e.g., "application/pdf")
+
+        Returns:
+            List of file dictionaries with WebDAV properties (path, size, content_type, etc.)
+
+        Raises:
+            RuntimeError: If tag lookup or file query fails
+
+        Examples:
+            # Find all files with "vector-index" tag
+            files = await nc_client.find_files_by_tag("vector-index")
+
+            # Find only PDFs with the tag
+            pdfs = await nc_client.find_files_by_tag("vector-index", "application/pdf")
+        """
+        # Look up tag by name using WebDAV
+        tag = await self.webdav.get_tag_by_name(tag_name)
+        if not tag:
+            logger.debug(f"Tag '{tag_name}' not found, returning empty list")
+            return []
+
+        # Get files with this tag (returns full file info from REPORT)
+        files = await self.webdav.get_files_by_tag(tag["id"])
+        if not files:
+            logger.debug(f"No files found with tag '{tag_name}'")
+            return []
+
+        logger.debug(f"Found {len(files)} files with tag '{tag_name}'")
+
+        # Apply MIME type filter if specified
+        if mime_type_filter:
+            filtered_files = [
+                f
+                for f in files
+                if f.get("content_type", "").startswith(mime_type_filter)
+            ]
+            logger.info(
+                f"Returning {len(filtered_files)} files with tag '{tag_name}' (filtered by {mime_type_filter})"
+            )
+            return filtered_files
+
+        logger.info(f"Returning {len(files)} files with tag '{tag_name}'")
+        return files
+
     def _get_webdav_base_path(self) -> str:
         """Helper to get the base WebDAV path for the authenticated user."""
         return f"/remote.php/dav/files/{self.username}"
 
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit - closes all clients."""
+        await self.close()
+        return False  # Don't suppress exceptions
+
     async def close(self):
         """Close the HTTP client and CalDAV client."""
         await self._client.aclose()

nextcloud_mcp_server/client/calendar.py

@@ -13,6 +13,8 @@ from icalendar import Alarm, Calendar, vRecur
 from icalendar import Event as ICalEvent
 from icalendar import Todo as ICalTodo
 
+from ..config import get_nextcloud_ssl_verify
+
 logger = logging.getLogger(__name__)
 
 
@@ -34,6 +36,7 @@ class CalendarClient:
             url=f"{base_url}/remote.php/dav/",
             username=username,
             auth=auth,
+            ssl_verify_cert=get_nextcloud_ssl_verify(),  # type: ignore[arg-type]  # caldav types say bool|str but passes through to httpx which accepts SSLContext
         )
         self._calendar_home_url = f"{base_url}/remote.php/dav/calendars/{username}/"
 
@@ -255,18 +258,35 @@ class CalendarClient:
         """List events in a calendar within date range."""
         calendar = self._get_calendar(calendar_name)
 
-        # Get all events using caldav library (now with proper filter)
-        events = await calendar.events()
+        if start_datetime or end_datetime:
+            # Build CalDAV REPORT with time-range filter for server-side filtering
+            events = await self._search_events_by_date(
+                calendar, start_datetime, end_datetime
+            )
+            # Expand is only used when both bounds are provided
+            expanded = bool(start_datetime and end_datetime)
+        else:
+            # No date filter — fetch all events
+            events = await calendar.events()
+            expanded = False
 
         result = []
         for event in events:
             await event.load(only_if_unloaded=True)
             if event.data:
-                event_dict = self._parse_ical_event(event.data)
-                if event_dict:
-                    event_dict["href"] = str(event.url)
-                    event_dict["etag"] = ""
-                    result.append(event_dict)
+                if expanded:
+                    # Server-side expansion: each response resource may contain
+                    # multiple VEVENTs (one per recurrence occurrence)
+                    for event_dict in self._parse_all_ical_events(event.data):
+                        event_dict["href"] = str(event.url)
+                        event_dict["etag"] = ""
+                        result.append(event_dict)
+                else:
+                    event_dict = self._parse_ical_event(event.data)
+                    if event_dict:
+                        event_dict["href"] = str(event.url)
+                        event_dict["etag"] = ""
+                        result.append(event_dict)
 
             if len(result) >= limit:
                 break
@@ -274,6 +294,57 @@ class CalendarClient:
         logger.debug(f"Found {len(result)} events")
         return result
 
+    async def _search_events_by_date(
+        self,
+        calendar: AsyncCalendar,
+        start_datetime: Optional[dt.datetime] = None,
+        end_datetime: Optional[dt.datetime] = None,
+    ) -> list:
+        """Execute a CalDAV REPORT with time-range filter."""
+        from caldav.async_collection import AsyncEvent
+        from caldav.elements import cdav, dav
+        from lxml import etree  # type: ignore[import-untyped]
+
+        # Ensure naive datetimes are treated as UTC
+        if start_datetime and start_datetime.tzinfo is None:
+            start_datetime = start_datetime.replace(tzinfo=dt.UTC)
+        if end_datetime and end_datetime.tzinfo is None:
+            end_datetime = end_datetime.replace(tzinfo=dt.UTC)
+
+        # Build comp-filter with time-range (mirrors sync Calendar.build_search_xml_query)
+        inner_comp_filter = cdav.CompFilter(name="VEVENT")
+        inner_comp_filter += cdav.TimeRange(start_datetime, end_datetime)
+        outer_comp_filter = cdav.CompFilter(name="VCALENDAR") + inner_comp_filter
+        filter_element = cdav.Filter() + outer_comp_filter
+
+        # When both bounds are provided, request server-side expansion of
+        # recurring events (RFC 4791 §9.6.5). Each occurrence is returned as
+        # a separate VEVENT with its own DTSTART, with RRULE stripped.
+        data = cdav.CalendarData()
+        if start_datetime and end_datetime:
+            data += cdav.Expand(start_datetime, end_datetime)
+
+        query = cdav.CalendarQuery() + [dav.Prop() + data] + filter_element
+
+        body = etree.tostring(
+            query.xmlelement(), encoding="utf-8", xml_declaration=True
+        )
+        assert calendar.client is not None
+        response = await calendar.client.report(str(calendar.url), body, depth=1)
+
+        # Parse response (same pattern as AsyncCalendar.search)
+        objects = []
+        response_data = response.expand_simple_props([cdav.CalendarData()])
+        for href, props in response_data.items():
+            if href == str(calendar.url):
+                continue
+            cal_data = props.get(cdav.CalendarData.tag)
+            if cal_data:
+                obj = AsyncEvent(client=calendar.client, data=cal_data, parent=calendar)
+                objects.append(obj)
+
+        return objects
+
     async def create_event(
         self, calendar_name: str, event_data: Dict[str, Any]
     ) -> Dict[str, Any]:
@@ -583,7 +654,7 @@ class CalendarClient:
         # Add categories
         categories = event_data.get("categories", "")
         if categories:
-            event.add("categories", categories.split(","))
+            event.add("categories", [c.strip() for c in categories.split(",")])
 
         # Add priority and status
         priority = event_data.get("priority", 5)
@@ -633,75 +704,92 @@ class CalendarClient:
         cal.add_component(event)
         return cal.to_ical().decode("utf-8")
 
+    def _extract_vevent_data(self, component) -> Dict[str, Any]:
+        """Extract event data from a single VEVENT component.
+
+        Shared helper used by both _parse_ical_event() and _parse_all_ical_events().
+        """
+        event_data: Dict[str, Any] = {
+            "uid": str(component.get("uid", "")),
+            "title": str(component.get("summary", "")),
+            "description": str(component.get("description", "")),
+            "location": str(component.get("location", "")),
+            "status": str(component.get("status", "CONFIRMED")),
+            "priority": int(component.get("priority", 5)),
+            "privacy": str(component.get("class", "PUBLIC")),
+            "url": str(component.get("url", "")),
+        }
+
+        # Handle dates
+        dtstart = component.get("dtstart")
+        if dtstart:
+            if isinstance(dtstart.dt, dt.date) and not isinstance(
+                dtstart.dt, dt.datetime
+            ):
+                event_data["start_datetime"] = dtstart.dt.isoformat()
+                event_data["all_day"] = True
+            else:
+                event_data["start_datetime"] = dtstart.dt.isoformat()
+                event_data["all_day"] = False
+
+        dtend = component.get("dtend")
+        if dtend:
+            if isinstance(dtend.dt, dt.date) and not isinstance(dtend.dt, dt.datetime):
+                event_data["end_datetime"] = dtend.dt.isoformat()
+            else:
+                event_data["end_datetime"] = dtend.dt.isoformat()
+
+        # Handle categories
+        categories = component.get("categories")
+        if categories:
+            event_data["categories"] = self._extract_categories(categories)
+
+        # Handle recurrence
+        rrule = component.get("rrule")
+        if rrule:
+            event_data["recurring"] = True
+            event_data["recurrence_rule"] = str(rrule)
+
+        # Handle attendees
+        attendees = []
+        for attendee in component.get("attendee", []):
+            if isinstance(attendee, list):
+                attendees.extend(str(a).replace("mailto:", "") for a in attendee)
+            else:
+                attendees.append(str(attendee).replace("mailto:", ""))
+        if attendees:
+            event_data["attendees"] = ",".join(attendees)
+
+        return event_data
+
     def _parse_ical_event(self, ical_text: str) -> Optional[Dict[str, Any]]:
-        """Parse iCalendar text and extract event data."""
+        """Parse iCalendar text and extract the first event."""
         try:
             cal = Calendar.from_ical(ical_text)
             for component in cal.walk():
                 if component.name == "VEVENT":
-                    event_data = {
-                        "uid": str(component.get("uid", "")),
-                        "title": str(component.get("summary", "")),
-                        "description": str(component.get("description", "")),
-                        "location": str(component.get("location", "")),
-                        "status": str(component.get("status", "CONFIRMED")),
-                        "priority": int(component.get("priority", 5)),
-                        "privacy": str(component.get("class", "PUBLIC")),
-                        "url": str(component.get("url", "")),
-                    }
-
-                    # Handle dates
-                    dtstart = component.get("dtstart")
-                    if dtstart:
-                        if isinstance(dtstart.dt, dt.date) and not isinstance(
-                            dtstart.dt, dt.datetime
-                        ):
-                            event_data["start_datetime"] = dtstart.dt.isoformat()
-                            event_data["all_day"] = True
-                        else:
-                            event_data["start_datetime"] = dtstart.dt.isoformat()
-                            event_data["all_day"] = False
-
-                    dtend = component.get("dtend")
-                    if dtend:
-                        if isinstance(dtend.dt, dt.date) and not isinstance(
-                            dtend.dt, dt.datetime
-                        ):
-                            event_data["end_datetime"] = dtend.dt.isoformat()
-                        else:
-                            event_data["end_datetime"] = dtend.dt.isoformat()
-
-                    # Handle categories
-                    categories = component.get("categories")
-                    if categories:
-                        event_data["categories"] = self._extract_categories(categories)
-
-                    # Handle recurrence
-                    rrule = component.get("rrule")
-                    if rrule:
-                        event_data["recurring"] = True
-                        event_data["recurrence_rule"] = str(rrule)
-
-                    # Handle attendees
-                    attendees = []
-                    for attendee in component.get("attendee", []):
-                        if isinstance(attendee, list):
-                            attendees.extend(
-                                str(a).replace("mailto:", "") for a in attendee
-                            )
-                        else:
-                            attendees.append(str(attendee).replace("mailto:", ""))
-                    if attendees:
-                        event_data["attendees"] = ",".join(attendees)
-
-                    return event_data
-
+                    return self._extract_vevent_data(component)
             return None
-
         except Exception as e:
             logger.error(f"Error parsing iCalendar event: {e}")
             return None
 
+    def _parse_all_ical_events(self, ical_text: str) -> list[Dict[str, Any]]:
+        """Parse iCalendar text and extract ALL event occurrences.
+
+        Used with server-side expansion where a single VCALENDAR contains
+        multiple VEVENT components (one per recurrence occurrence).
+        """
+        results: list[Dict[str, Any]] = []
+        try:
+            cal = Calendar.from_ical(ical_text)
+            for component in cal.walk():
+                if component.name == "VEVENT":
+                    results.append(self._extract_vevent_data(component))
+        except Exception as e:
+            logger.error(f"Error parsing iCalendar events: {e}")
+        return results
+
     def _merge_ical_properties(
         self, raw_ical: str, event_data: Dict[str, Any], event_uid: str
     ) -> str:
@@ -727,6 +815,50 @@ class CalendarClient:
                     if "url" in event_data:
                         component["URL"] = event_data["url"]
 
+                    # Handle categories
+                    if "categories" in event_data:
+                        categories_str = event_data["categories"]
+                        if categories_str:
+                            component["CATEGORIES"] = [
+                                c.strip() for c in categories_str.split(",")
+                            ]
+                        elif "CATEGORIES" in component:
+                            del component["CATEGORIES"]
+
+                    # Handle recurrence rule
+                    if "recurrence_rule" in event_data:
+                        rrule_str = event_data["recurrence_rule"]
+                        if rrule_str:
+                            component["RRULE"] = vRecur.from_ical(rrule_str)
+                        elif "RRULE" in component:
+                            del component["RRULE"]
+
+                    # Handle attendees
+                    if "attendees" in event_data:
+                        attendees_str = event_data["attendees"]
+                        # Remove all existing attendees first
+                        while "ATTENDEE" in component:
+                            del component["ATTENDEE"]
+                        if attendees_str:
+                            for email in attendees_str.split(","):
+                                if email.strip():
+                                    component.add("attendee", f"mailto:{email.strip()}")
+
+                    # Handle reminder (VALARM)
+                    if "reminder_minutes" in event_data:
+                        component.subcomponents = [
+                            sub
+                            for sub in component.subcomponents
+                            if sub.name != "VALARM"
+                        ]
+                        minutes = event_data["reminder_minutes"]
+                        if minutes > 0:
+                            alarm = Alarm()
+                            alarm.add("action", "DISPLAY")
+                            alarm.add("description", "Event reminder")
+                            alarm.add("trigger", dt.timedelta(minutes=-minutes))
+                            component.add_component(alarm)
+
                     # Handle dates
                     if "start_datetime" in event_data:
                         start_str = event_data["start_datetime"]
@@ -960,7 +1092,9 @@ class CalendarClient:
                     if "categories" in todo_data:
                         categories_str = todo_data["categories"]
                         if categories_str:
-                            component["CATEGORIES"] = categories_str.split(",")
+                            component["CATEGORIES"] = [
+                                c.strip() for c in categories_str.split(",")
+                            ]
                             logger.debug(f"Set CATEGORIES to {categories_str}")
 
                     # Update timestamps

nextcloud_mcp_server/client/deck.py

@@ -285,28 +285,23 @@ class DeckClient(BaseNextcloudClient):
         archived: Optional[bool] = None,
         done: Optional[str] = None,
     ) -> None:
-        # First, get the current card to use existing values for required fields
+        # Deck PUT API is a full replacement - all required fields must be sent.
+        # Fetch current card to preserve values for fields not being updated.
         current_card = await self.get_card(board_id, stack_id, card_id)
 
-        json_data = {}
-        if title is not None:
-            json_data["title"] = title
-        if description is not None:
-            json_data["description"] = description
-        # Type is required by the API, use provided or keep current
-        json_data["type"] = type if type is not None else current_card.type
-        # Owner is required by the API, use provided or keep current
-        json_data["owner"] = (
-            owner
-            if owner is not None
-            else (
-                current_card.owner
-                if isinstance(current_card.owner, str)
-                else current_card.owner.uid
-                if hasattr(current_card.owner, "uid")
-                else current_card.owner.primaryKey
-            )
-        )
+        # Build payload with required fields always included
+        json_data = {
+            # Title is required by the API
+            "title": title if title is not None else current_card.title,
+            # Type is required by the API
+            "type": type if type is not None else current_card.type,
+            # Owner is required by the API (model validator ensures it's a string)
+            "owner": owner if owner is not None else current_card.owner,
+            # Description must be sent to preserve it (PUT clears omitted fields)
+            "description": description
+            if description is not None
+            else (current_card.description or ""),
+        }
         if order is not None:
             json_data["order"] = order
         if duedate is not None:
@@ -391,11 +386,17 @@ class DeckClient(BaseNextcloudClient):
         order: int,
         target_stack_id: int,
     ) -> None:
+        # Use the non-API route /cards/{cardId}/reorder which correctly reads
+        # stackId from the body. The API route /api/.../stacks/{stackId}/cards/...
+        # has a parameter conflict where URL stackId overrides body stackId.
+        # See: https://github.com/cbcoutinho/nextcloud-mcp-server/issues/469
         json_data = {"order": order, "stackId": target_stack_id}
+        headers = self._get_deck_headers()
         await self._make_request(
             "PUT",
-            f"/apps/deck/api/v1.0/boards/{board_id}/stacks/{stack_id}/cards/{card_id}/reorder",
+            f"/apps/deck/cards/{card_id}/reorder",
             json=json_data,
+            headers=headers,
         )
 
     # Labels

nextcloud_mcp_server/client/news.py

@@ -0,0 +1,394 @@
+"""Client for Nextcloud News app operations."""
+
+import logging
+from enum import IntEnum
+from typing import Any
+
+from .base import BaseNextcloudClient
+
+logger = logging.getLogger(__name__)
+
+
+class NewsItemType(IntEnum):
+    """Type constants for News API item queries."""
+
+    FEED = 0  # Single feed
+    FOLDER = 1  # Folder and its feeds
+    STARRED = 2  # All starred items
+    ALL = 3  # All items
+
+
+class NewsClient(BaseNextcloudClient):
+    """Client for Nextcloud News app operations."""
+
+    app_name = "news"
+    API_BASE = "/apps/news/api/v1-3"
+
+    # --- Folders ---
+
+    async def get_folders(self) -> list[dict[str, Any]]:
+        """Get all folders."""
+        response = await self._make_request("GET", f"{self.API_BASE}/folders")
+        return response.json().get("folders", [])
+
+    async def create_folder(self, name: str) -> dict[str, Any]:
+        """Create a new folder.
+
+        Args:
+            name: Folder name
+
+        Returns:
+            Created folder data
+
+        Raises:
+            HTTPStatusError: 409 if folder name already exists,
+                            422 if name is empty
+        """
+        response = await self._make_request(
+            "POST", f"{self.API_BASE}/folders", json={"name": name}
+        )
+        folders = response.json().get("folders", [])
+        return folders[0] if folders else {}
+
+    async def rename_folder(self, folder_id: int, name: str) -> None:
+        """Rename a folder.
+
+        Args:
+            folder_id: Folder ID
+            name: New folder name
+
+        Raises:
+            HTTPStatusError: 404 if folder not found, 409 if name exists
+        """
+        await self._make_request(
+            "PUT", f"{self.API_BASE}/folders/{folder_id}", json={"name": name}
+        )
+
+    async def delete_folder(self, folder_id: int) -> None:
+        """Delete a folder and all its feeds/items.
+
+        Args:
+            folder_id: Folder ID
+
+        Raises:
+            HTTPStatusError: 404 if folder not found
+        """
+        await self._make_request("DELETE", f"{self.API_BASE}/folders/{folder_id}")
+
+    async def mark_folder_read(self, folder_id: int, newest_item_id: int) -> None:
+        """Mark all items in a folder as read.
+
+        Args:
+            folder_id: Folder ID
+            newest_item_id: ID of newest item to mark read (prevents marking
+                           items user hasn't seen yet)
+
+        Raises:
+            HTTPStatusError: 404 if folder not found
+        """
+        await self._make_request(
+            "POST",
+            f"{self.API_BASE}/folders/{folder_id}/read",
+            json={"newestItemId": newest_item_id},
+        )
+
+    # --- Feeds ---
+
+    async def get_feeds(self) -> dict[str, Any]:
+        """Get all feeds with metadata.
+
+        Returns:
+            Dict with keys:
+                - feeds: List of feed objects
+                - starredCount: Number of starred items
+                - newestItemId: ID of newest item (omitted if no items)
+        """
+        response = await self._make_request("GET", f"{self.API_BASE}/feeds")
+        return response.json()
+
+    async def create_feed(
+        self, url: str, folder_id: int | None = None
+    ) -> dict[str, Any]:
+        """Subscribe to a new feed.
+
+        Args:
+            url: Feed URL
+            folder_id: Optional folder ID (None for root)
+
+        Returns:
+            Created feed data
+
+        Raises:
+            HTTPStatusError: 409 if feed already exists, 422 if URL is invalid
+        """
+        body: dict[str, Any] = {"url": url}
+        if folder_id is not None:
+            body["folderId"] = folder_id
+        response = await self._make_request("POST", f"{self.API_BASE}/feeds", json=body)
+        data = response.json()
+        feeds = data.get("feeds", [])
+        return feeds[0] if feeds else {}
+
+    async def delete_feed(self, feed_id: int) -> None:
+        """Unsubscribe from a feed (deletes all items).
+
+        Args:
+            feed_id: Feed ID
+
+        Raises:
+            HTTPStatusError: 404 if feed not found
+        """
+        await self._make_request("DELETE", f"{self.API_BASE}/feeds/{feed_id}")
+
+    async def move_feed(self, feed_id: int, folder_id: int | None) -> None:
+        """Move a feed to a different folder.
+
+        Args:
+            feed_id: Feed ID
+            folder_id: Target folder ID (None for root)
+
+        Raises:
+            HTTPStatusError: 404 if feed not found
+        """
+        await self._make_request(
+            "POST",
+            f"{self.API_BASE}/feeds/{feed_id}/move",
+            json={"folderId": folder_id},
+        )
+
+    async def rename_feed(self, feed_id: int, title: str) -> None:
+        """Rename a feed.
+
+        Args:
+            feed_id: Feed ID
+            title: New feed title
+
+        Raises:
+            HTTPStatusError: 404 if feed not found
+        """
+        await self._make_request(
+            "POST",
+            f"{self.API_BASE}/feeds/{feed_id}/rename",
+            json={"feedTitle": title},
+        )
+
+    async def mark_feed_read(self, feed_id: int, newest_item_id: int) -> None:
+        """Mark all items in a feed as read.
+
+        Args:
+            feed_id: Feed ID
+            newest_item_id: ID of newest item to mark read
+
+        Raises:
+            HTTPStatusError: 404 if feed not found
+        """
+        await self._make_request(
+            "POST",
+            f"{self.API_BASE}/feeds/{feed_id}/read",
+            json={"newestItemId": newest_item_id},
+        )
+
+    # --- Items ---
+
+    async def get_items(
+        self,
+        batch_size: int = 50,
+        offset: int = 0,
+        type_: int = NewsItemType.ALL,
+        id_: int = 0,
+        get_read: bool = True,
+        oldest_first: bool = False,
+    ) -> list[dict[str, Any]]:
+        """Get items (articles) with filtering.
+
+        Args:
+            batch_size: Number of items to return (-1 for all)
+            offset: Item ID to start after (for pagination)
+            type_: Item type filter (NewsItemType)
+            id_: Feed/folder ID (ignored for STARRED/ALL types)
+            get_read: Include read items
+            oldest_first: Sort oldest first instead of newest
+
+        Returns:
+            List of item objects
+        """
+        params: dict[str, Any] = {
+            "batchSize": batch_size,
+            "offset": offset,
+            "type": type_,
+            "id": id_,
+            "getRead": str(get_read).lower(),
+            "oldestFirst": str(oldest_first).lower(),
+        }
+        response = await self._make_request(
+            "GET", f"{self.API_BASE}/items", params=params
+        )
+        return response.json().get("items", [])
+
+    async def get_item(self, item_id: int) -> dict[str, Any]:
+        """Get a specific item by ID.
+
+        Note: The News API doesn't have a direct single-item endpoint,
+        so we fetch all items and filter. For efficiency, consider
+        caching or using get_items with specific feed if known.
+
+        Args:
+            item_id: Item ID
+
+        Returns:
+            Item data
+
+        Raises:
+            ValueError: If item not found
+        """
+        # Fetch all items and find the one we need
+        # This is inefficient but the API doesn't provide a direct endpoint
+        items = await self.get_items(batch_size=-1, get_read=True)
+        for item in items:
+            if item.get("id") == item_id:
+                return item
+        raise ValueError(f"Item {item_id} not found")
+
+    async def get_updated_items(
+        self,
+        last_modified: int,
+        type_: int = NewsItemType.ALL,
+        id_: int = 0,
+    ) -> list[dict[str, Any]]:
+        """Get items modified since a timestamp (for delta sync).
+
+        Args:
+            last_modified: Unix timestamp (seconds or microseconds)
+            type_: Item type filter
+            id_: Feed/folder ID
+
+        Returns:
+            List of modified items (includes deleted items)
+        """
+        params: dict[str, Any] = {
+            "lastModified": last_modified,
+            "type": type_,
+            "id": id_,
+        }
+        response = await self._make_request(
+            "GET", f"{self.API_BASE}/items/updated", params=params
+        )
+        return response.json().get("items", [])
+
+    async def mark_item_read(self, item_id: int) -> None:
+        """Mark a single item as read.
+
+        Args:
+            item_id: Item ID
+
+        Raises:
+            HTTPStatusError: 404 if item not found
+        """
+        await self._make_request("POST", f"{self.API_BASE}/items/{item_id}/read")
+
+    async def mark_item_unread(self, item_id: int) -> None:
+        """Mark a single item as unread.
+
+        Args:
+            item_id: Item ID
+
+        Raises:
+            HTTPStatusError: 404 if item not found
+        """
+        await self._make_request("POST", f"{self.API_BASE}/items/{item_id}/unread")
+
+    async def star_item(self, item_id: int) -> None:
+        """Star (favorite) a single item.
+
+        Args:
+            item_id: Item ID
+
+        Raises:
+            HTTPStatusError: 404 if item not found
+        """
+        await self._make_request("POST", f"{self.API_BASE}/items/{item_id}/star")
+
+    async def unstar_item(self, item_id: int) -> None:
+        """Unstar a single item.
+
+        Args:
+            item_id: Item ID
+
+        Raises:
+            HTTPStatusError: 404 if item not found
+        """
+        await self._make_request("POST", f"{self.API_BASE}/items/{item_id}/unstar")
+
+    async def mark_items_read(self, item_ids: list[int]) -> None:
+        """Mark multiple items as read.
+
+        Args:
+            item_ids: List of item IDs
+        """
+        await self._make_request(
+            "POST", f"{self.API_BASE}/items/read/multiple", json={"itemIds": item_ids}
+        )
+
+    async def mark_items_unread(self, item_ids: list[int]) -> None:
+        """Mark multiple items as unread.
+
+        Args:
+            item_ids: List of item IDs
+        """
+        await self._make_request(
+            "POST",
+            f"{self.API_BASE}/items/unread/multiple",
+            json={"itemIds": item_ids},
+        )
+
+    async def star_items(self, item_ids: list[int]) -> None:
+        """Star multiple items.
+
+        Args:
+            item_ids: List of item IDs
+        """
+        await self._make_request(
+            "POST", f"{self.API_BASE}/items/star/multiple", json={"itemIds": item_ids}
+        )
+
+    async def unstar_items(self, item_ids: list[int]) -> None:
+        """Unstar multiple items.
+
+        Args:
+            item_ids: List of item IDs
+        """
+        await self._make_request(
+            "POST",
+            f"{self.API_BASE}/items/unstar/multiple",
+            json={"itemIds": item_ids},
+        )
+
+    async def mark_all_read(self, newest_item_id: int) -> None:
+        """Mark all items as read.
+
+        Args:
+            newest_item_id: ID of newest item to mark read
+        """
+        await self._make_request(
+            "POST", f"{self.API_BASE}/items/read", json={"newestItemId": newest_item_id}
+        )
+
+    # --- Status ---
+
+    async def get_status(self) -> dict[str, Any]:
+        """Get News app status and configuration.
+
+        Returns:
+            Dict with version and warnings
+        """
+        response = await self._make_request("GET", f"{self.API_BASE}/status")
+        return response.json()
+
+    async def get_version(self) -> str:
+        """Get News app version.
+
+        Returns:
+            Version string (e.g., "25.0.0")
+        """
+        response = await self._make_request("GET", f"{self.API_BASE}/version")
+        return response.json().get("version", "")

nextcloud_mcp_server/client/webdav.py

@@ -821,6 +821,20 @@ class WebDAVClient(BaseNextcloudClient):
                     item["file_id"] = int(value) if value else None
                 elif tag == "favorite":
                     item["is_favorite"] = value == "1"
+                elif tag == "tags":
+                    # Tags can be comma-separated or have multiple child elements
+                    if value:
+                        # Handle comma-separated tags
+                        item["tags"] = [
+                            t.strip() for t in value.split(",") if t.strip()
+                        ]
+                    else:
+                        # Check for child tag elements (alternative format)
+                        tag_elements = child.findall(".//{http://owncloud.org/ns}tag")
+                        if tag_elements:
+                            item["tags"] = [t.text for t in tag_elements if t.text]
+                        else:
+                            item["tags"] = []
                 elif tag == "permissions":
                     item["permissions"] = value
                 elif tag == "size":
@@ -948,3 +962,576 @@ class WebDAVClient(BaseNextcloudClient):
             properties=properties,
             limit=limit,
         )
+
+    async def find_by_tag(
+        self, tag_name: str, scope: str = "", limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Find files by tag name.
+
+        DEPRECATED: Use NextcloudClient.find_files_by_tag() instead, which uses
+        the proper OCS Tags API rather than WebDAV SEARCH.
+
+        Args:
+            tag_name: Tag to filter by (e.g., "vector-index")
+            scope: Directory path to search in (empty string for user root)
+            limit: Maximum number of results to return
+
+        Returns:
+            List of files/directories with the specified tag
+
+        Examples:
+            # Find all files tagged with "vector-index"
+            results = await find_by_tag("vector-index")
+
+            # Find tagged files in a specific folder
+            results = await find_by_tag("vector-index", scope="Documents")
+        """
+        # Use LIKE for tag matching since tags can be comma-separated
+        where_conditions = f"""
+            <d:like>
+                <d:prop>
+                    <oc:tags/>
+                </d:prop>
+                <d:literal>%{tag_name}%</d:literal>
+            </d:like>
+        """
+
+        # Request tag property along with standard properties
+        properties = [
+            "displayname",
+            "getcontentlength",
+            "getcontenttype",
+            "getlastmodified",
+            "resourcetype",
+            "getetag",
+            "fileid",
+            "tags",
+        ]
+
+        return await self.search_files(
+            scope=scope,
+            where_conditions=where_conditions,
+            properties=properties,
+            limit=limit,
+        )
+
+    async def _get_file_info_by_id(self, file_id: int) -> Dict[str, Any]:
+        """Get file information by Nextcloud file ID using WebDAV.
+
+        Args:
+            file_id: Nextcloud internal file ID
+
+        Returns:
+            File information dictionary with path, size, content_type, etc.
+
+        Raises:
+            HTTPStatusError: If file not found or request fails
+        """
+        # Nextcloud allows accessing files by ID via special meta endpoint
+        meta_path = f"/remote.php/dav/meta/{file_id}/"
+
+        propfind_body = """<?xml version="1.0"?>
+        <d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">
+            <d:prop>
+                <d:displayname/>
+                <d:getcontentlength/>
+                <d:getcontenttype/>
+                <d:getlastmodified/>
+                <d:resourcetype/>
+                <d:getetag/>
+                <oc:fileid/>
+            </d:prop>
+        </d:propfind>"""
+
+        headers = {"Depth": "0", "Content-Type": "text/xml", "OCS-APIRequest": "true"}
+
+        response = await self._make_request(
+            "PROPFIND", meta_path, content=propfind_body, headers=headers
+        )
+        response.raise_for_status()
+
+        # Parse the XML response
+        root = ET.fromstring(response.content)
+        responses = root.findall(".//{DAV:}response")
+
+        if not responses:
+            raise RuntimeError(f"File ID {file_id} not found")
+
+        response_elem = responses[0]
+        href = response_elem.find(".//{DAV:}href")
+        if href is None:
+            raise RuntimeError(f"No href in response for file ID {file_id}")
+
+        propstat = response_elem.find(".//{DAV:}propstat")
+        if propstat is None:
+            raise RuntimeError(f"No propstat for file ID {file_id}")
+
+        prop = propstat.find(".//{DAV:}prop")
+        if prop is None:
+            raise RuntimeError(f"No prop for file ID {file_id}")
+
+        # Extract file path from displayname or construct from file ID
+        displayname_elem = prop.find(".//{DAV:}displayname")
+        name = (
+            displayname_elem.text if displayname_elem is not None else f"file_{file_id}"
+        )
+
+        # Get file properties
+        size_elem = prop.find(".//{DAV:}getcontentlength")
+        size = int(size_elem.text) if size_elem is not None and size_elem.text else 0
+
+        content_type_elem = prop.find(".//{DAV:}getcontenttype")
+        content_type = content_type_elem.text if content_type_elem is not None else None
+
+        modified_elem = prop.find(".//{DAV:}getlastmodified")
+        modified = modified_elem.text if modified_elem is not None else None
+
+        etag_elem = prop.find(".//{DAV:}getetag")
+        etag = (
+            etag_elem.text.strip('"')
+            if etag_elem is not None and etag_elem.text
+            else None
+        )
+
+        # Check if it's a directory
+        resourcetype = prop.find(".//{DAV:}resourcetype")
+        is_directory = (
+            resourcetype is not None
+            and resourcetype.find(".//{DAV:}collection") is not None
+        )
+
+        # Try to get actual file path - meta endpoint doesn't give us the real path
+        # so we'll construct a reasonable path from the name
+        # The calling code in NextcloudClient will have the context to determine the actual path
+        file_info = {
+            "name": name,
+            "path": f"/{name}",  # Placeholder - caller should use WebDAV to get real path if needed
+            "size": size,
+            "content_type": content_type,
+            "last_modified": modified,
+            "etag": etag,
+            "is_directory": is_directory,
+            "file_id": file_id,
+        }
+
+        logger.debug(f"Retrieved file info for ID {file_id}: {name}")
+        return file_info
+
+    async def get_tag_by_name(self, tag_name: str) -> dict[str, Any] | None:
+        """Get a system tag by its name via WebDAV.
+
+        Args:
+            tag_name: Name of the tag to find (case-sensitive)
+
+        Returns:
+            Tag dictionary if found, None otherwise
+        """
+        # Use WebDAV PROPFIND to list all systemtags
+        propfind_body = """<?xml version="1.0"?>
+<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">
+  <d:prop>
+    <oc:id/>
+    <oc:display-name/>
+    <oc:user-visible/>
+    <oc:user-assignable/>
+  </d:prop>
+</d:propfind>"""
+
+        response = await self._client.request(
+            "PROPFIND",
+            "/remote.php/dav/systemtags/",
+            headers={"Depth": "1"},
+            content=propfind_body,
+        )
+        response.raise_for_status()
+
+        # Parse XML response
+        root = ET.fromstring(response.content)
+        ns = {
+            "d": "DAV:",
+            "oc": "http://owncloud.org/ns",
+        }
+
+        for response_elem in root.findall("d:response", ns):
+            href = response_elem.find("d:href", ns)
+            if href is None or href.text == "/remote.php/dav/systemtags/":
+                # Skip the collection itself
+                continue
+
+            propstat = response_elem.find("d:propstat", ns)
+            if propstat is None:
+                continue
+
+            prop = propstat.find("d:prop", ns)
+            if prop is None:
+                continue
+
+            # Extract tag properties
+            tag_id_elem = prop.find("oc:id", ns)
+            display_name_elem = prop.find("oc:display-name", ns)
+            user_visible_elem = prop.find("oc:user-visible", ns)
+            user_assignable_elem = prop.find("oc:user-assignable", ns)
+
+            if display_name_elem is not None and display_name_elem.text == tag_name:
+                tag_info = {
+                    "id": int(tag_id_elem.text)
+                    if tag_id_elem is not None and tag_id_elem.text is not None
+                    else None,
+                    "name": display_name_elem.text,
+                    "userVisible": user_visible_elem.text.lower() == "true"
+                    if user_visible_elem is not None
+                    and user_visible_elem.text is not None
+                    else True,
+                    "userAssignable": user_assignable_elem.text.lower() == "true"
+                    if user_assignable_elem is not None
+                    and user_assignable_elem.text is not None
+                    else True,
+                }
+                logger.debug(f"Found tag '{tag_name}' with ID {tag_info['id']}")
+                return tag_info
+
+        logger.debug(f"Tag '{tag_name}' not found")
+        return None
+
+    async def get_files_by_tag(self, tag_id: int) -> list[dict[str, Any]]:
+        """Get all files tagged with a specific system tag via WebDAV REPORT.
+
+        Args:
+            tag_id: Numeric ID of the tag
+
+        Returns:
+            List of file info dictionaries with path, size, content_type, etc.
+        """
+        # Use WebDAV REPORT method with systemtag filter, requesting all properties
+        report_body = f"""<?xml version="1.0"?>
+<oc:filter-files xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
+  <d:prop>
+    <oc:fileid/>
+    <d:displayname/>
+    <d:getcontentlength/>
+    <d:getcontenttype/>
+    <d:getlastmodified/>
+    <d:getetag/>
+  </d:prop>
+  <oc:filter-rules>
+    <oc:systemtag>{tag_id}</oc:systemtag>
+  </oc:filter-rules>
+</oc:filter-files>"""
+
+        response = await self._client.request(
+            "REPORT",
+            f"{self._get_webdav_base_path()}/",
+            content=report_body,
+        )
+        response.raise_for_status()
+
+        # Parse XML response
+        root = ET.fromstring(response.content)
+        ns = {
+            "d": "DAV:",
+            "oc": "http://owncloud.org/ns",
+        }
+
+        files = []
+        for response_elem in root.findall("d:response", ns):
+            # Extract href (file path)
+            href_elem = response_elem.find("d:href", ns)
+            if href_elem is None or not href_elem.text:
+                continue
+
+            propstat = response_elem.find("d:propstat", ns)
+            if propstat is None:
+                continue
+
+            prop = propstat.find("d:prop", ns)
+            if prop is None:
+                continue
+
+            # Extract all properties
+            fileid_elem = prop.find("oc:fileid", ns)
+            displayname_elem = prop.find("d:displayname", ns)
+            contentlength_elem = prop.find("d:getcontentlength", ns)
+            contenttype_elem = prop.find("d:getcontenttype", ns)
+            lastmodified_elem = prop.find("d:getlastmodified", ns)
+            etag_elem = prop.find("d:getetag", ns)
+
+            if fileid_elem is None or not fileid_elem.text:
+                continue
+
+            # Decode href path and extract the file path
+            from urllib.parse import unquote
+
+            href_path = unquote(href_elem.text)
+            # Remove WebDAV prefix to get user-relative path
+            webdav_prefix = f"/remote.php/dav/files/{self.username}/"
+            file_path = href_path.replace(webdav_prefix, "/")
+
+            # Parse last modified timestamp
+            last_modified_timestamp = None
+            if lastmodified_elem is not None and lastmodified_elem.text:
+                from email.utils import parsedate_to_datetime
+
+                try:
+                    dt = parsedate_to_datetime(lastmodified_elem.text)
+                    last_modified_timestamp = int(dt.timestamp())
+                except Exception:
+                    pass
+
+            file_info = {
+                "id": int(fileid_elem.text),
+                "path": file_path,
+                "name": displayname_elem.text
+                if displayname_elem is not None
+                else file_path.split("/")[-1],
+                "size": int(contentlength_elem.text)
+                if contentlength_elem is not None and contentlength_elem.text
+                else 0,
+                "content_type": contenttype_elem.text
+                if contenttype_elem is not None
+                else "",
+                "last_modified": lastmodified_elem.text
+                if lastmodified_elem is not None
+                else None,
+                "last_modified_timestamp": last_modified_timestamp,
+                "etag": etag_elem.text if etag_elem is not None else None,
+            }
+            files.append(file_info)
+
+        logger.debug(f"Found {len(files)} files with tag ID {tag_id}")
+        return files
+
+    async def get_file_info(self, path: str) -> dict[str, Any] | None:
+        """Get file info including file ID via WebDAV PROPFIND.
+
+        Args:
+            path: Path to the file (relative to user's files directory)
+
+        Returns:
+            File info dictionary with id, name, size, content_type, etc.
+            Returns None if file not found.
+        """
+        webdav_path = f"{self._get_webdav_base_path()}/{path.lstrip('/')}"
+
+        propfind_body = """<?xml version="1.0"?>
+<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">
+  <d:prop>
+    <oc:fileid/>
+    <d:displayname/>
+    <d:getcontentlength/>
+    <d:getcontenttype/>
+    <d:getlastmodified/>
+    <d:getetag/>
+    <d:resourcetype/>
+  </d:prop>
+</d:propfind>"""
+
+        try:
+            response = await self._client.request(
+                "PROPFIND",
+                webdav_path,
+                headers={"Depth": "0"},
+                content=propfind_body,
+            )
+            response.raise_for_status()
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                logger.debug(f"File not found: {path}")
+                return None
+            raise
+
+        # Parse XML response
+        root = ET.fromstring(response.content)
+        ns = {
+            "d": "DAV:",
+            "oc": "http://owncloud.org/ns",
+        }
+
+        response_elem = root.find("d:response", ns)
+        if response_elem is None:
+            return None
+
+        propstat = response_elem.find("d:propstat", ns)
+        if propstat is None:
+            return None
+
+        prop = propstat.find("d:prop", ns)
+        if prop is None:
+            return None
+
+        # Extract properties
+        fileid_elem = prop.find("oc:fileid", ns)
+        displayname_elem = prop.find("d:displayname", ns)
+        contentlength_elem = prop.find("d:getcontentlength", ns)
+        contenttype_elem = prop.find("d:getcontenttype", ns)
+        lastmodified_elem = prop.find("d:getlastmodified", ns)
+        etag_elem = prop.find("d:getetag", ns)
+        resourcetype_elem = prop.find("d:resourcetype", ns)
+
+        is_directory = (
+            resourcetype_elem is not None
+            and resourcetype_elem.find("d:collection", ns) is not None
+        )
+
+        file_info = {
+            "id": int(fileid_elem.text)
+            if fileid_elem is not None and fileid_elem.text is not None
+            else None,
+            "path": path,
+            "name": displayname_elem.text
+            if displayname_elem is not None
+            else path.split("/")[-1],
+            "size": int(contentlength_elem.text)
+            if contentlength_elem is not None and contentlength_elem.text
+            else 0,
+            "content_type": contenttype_elem.text
+            if contenttype_elem is not None
+            else "",
+            "last_modified": lastmodified_elem.text
+            if lastmodified_elem is not None
+            else None,
+            "etag": etag_elem.text.strip('"')
+            if etag_elem is not None and etag_elem.text
+            else None,
+            "is_directory": is_directory,
+        }
+
+        logger.debug(f"Got file info for '{path}': id={file_info['id']}")
+        return file_info
+
+    async def create_tag(
+        self,
+        name: str,
+        user_visible: bool = True,
+        user_assignable: bool = True,
+    ) -> dict[str, Any]:
+        """Create a system tag via WebDAV.
+
+        Args:
+            name: Name of the tag to create
+            user_visible: Whether the tag is visible to users
+            user_assignable: Whether users can assign this tag
+
+        Returns:
+            Tag dictionary with id, name, userVisible, userAssignable
+
+        Raises:
+            HTTPStatusError: If tag creation fails (409 if already exists)
+        """
+        # Use WebDAV POST with JSON body to create tag
+        response = await self._client.post(
+            "/remote.php/dav/systemtags/",
+            headers={"Content-Type": "application/json"},
+            json={
+                "name": name,
+                "userVisible": user_visible,
+                "userAssignable": user_assignable,
+            },
+        )
+        response.raise_for_status()
+
+        # Extract tag ID from Content-Location header (e.g., /remote.php/dav/systemtags/42)
+        content_location = response.headers.get("Content-Location", "")
+        tag_id = None
+        if content_location:
+            # Extract the numeric ID from the path
+            try:
+                tag_id = int(content_location.rstrip("/").split("/")[-1])
+            except (ValueError, IndexError):
+                pass
+
+        tag_info = {
+            "id": tag_id,
+            "name": name,
+            "userVisible": user_visible,
+            "userAssignable": user_assignable,
+        }
+
+        logger.info(f"Created tag '{name}' with ID {tag_info['id']}")
+        return tag_info
+
+    async def get_or_create_tag(
+        self,
+        name: str,
+        user_visible: bool = True,
+        user_assignable: bool = True,
+    ) -> dict[str, Any]:
+        """Get a tag by name, creating it if it doesn't exist.
+
+        Args:
+            name: Name of the tag
+            user_visible: Whether the tag is visible to users (for creation)
+            user_assignable: Whether users can assign this tag (for creation)
+
+        Returns:
+            Tag dictionary with id, name, userVisible, userAssignable
+        """
+        # First try to get existing tag
+        existing_tag = await self.get_tag_by_name(name)
+        if existing_tag:
+            logger.debug(f"Tag '{name}' already exists with ID {existing_tag['id']}")
+            return existing_tag
+
+        # Create new tag
+        try:
+            return await self.create_tag(name, user_visible, user_assignable)
+        except HTTPStatusError as e:
+            if e.response.status_code == 409:
+                # Tag was created between our check and creation, fetch it
+                existing_tag = await self.get_tag_by_name(name)
+                if existing_tag:
+                    return existing_tag
+            raise
+
+    async def assign_tag_to_file(self, file_id: int, tag_id: int) -> bool:
+        """Assign a system tag to a file.
+
+        Args:
+            file_id: Numeric file ID
+            tag_id: Numeric tag ID
+
+        Returns:
+            True if tag was assigned successfully (or already assigned)
+
+        Raises:
+            HTTPStatusError: If tag assignment fails
+        """
+        response = await self._client.request(
+            "PUT",
+            f"/remote.php/dav/systemtags-relations/files/{file_id}/{tag_id}",
+            headers={"Content-Length": "0"},
+            content=b"",
+        )
+
+        # 201 = Created (new assignment), 409 = Conflict (already assigned)
+        if response.status_code in (201, 409):
+            logger.info(f"Tagged file {file_id} with tag {tag_id}")
+            return True
+
+        response.raise_for_status()
+        return True
+
+    async def remove_tag_from_file(self, file_id: int, tag_id: int) -> bool:
+        """Remove a system tag from a file.
+
+        Args:
+            file_id: Numeric file ID
+            tag_id: Numeric tag ID
+
+        Returns:
+            True if tag was removed successfully (or wasn't assigned)
+
+        Raises:
+            HTTPStatusError: If tag removal fails
+        """
+        response = await self._client.request(
+            "DELETE",
+            f"/remote.php/dav/systemtags-relations/files/{file_id}/{tag_id}",
+        )
+
+        # 204 = No Content (removed), 404 = Not Found (wasn't assigned)
+        if response.status_code in (204, 404):
+            logger.info(f"Removed tag {tag_id} from file {file_id}")
+            return True
+
+        response.raise_for_status()
+        return True

nextcloud_mcp_server/config.py

@@ -1,9 +1,40 @@
 import logging
 import logging.config
 import os
+import socket
+import ssl
 from dataclasses import dataclass
+from enum import Enum
 from typing import Any, Optional
 
+
+class DeploymentMode(Enum):
+    """Deployment mode for the MCP server.
+
+    SELF_HOSTED: Full features, environment-based configuration.
+                 Supports vector sync, semantic search, admin UI.
+
+    SMITHERY_STATELESS: Stateless mode for Smithery hosting.
+                        Session-based configuration, no persistent storage.
+                        Excludes semantic search, vector sync, admin UI.
+    """
+
+    SELF_HOSTED = "self_hosted"
+    SMITHERY_STATELESS = "smithery"
+
+
+def get_deployment_mode() -> DeploymentMode:
+    """Detect deployment mode from environment.
+
+    Returns:
+        DeploymentMode.SMITHERY_STATELESS if SMITHERY_DEPLOYMENT=true,
+        otherwise DeploymentMode.SELF_HOSTED (default).
+    """
+    if os.getenv("SMITHERY_DEPLOYMENT", "false").lower() == "true":
+        return DeploymentMode.SMITHERY_STATELESS
+    return DeploymentMode.SELF_HOSTED
+
+
 LOGGING_CONFIG = {
     "version": 1,
     "disable_existing_loggers": False,
@@ -102,6 +133,14 @@ def get_document_processor_config() -> dict[str, Any]:
             "lang": os.getenv("TESSERACT_LANG", "eng"),
         }
 
+    # PyMuPDF configuration (local PDF processing)
+    if os.getenv("ENABLE_PYMUPDF", "true").lower() == "true":  # Enabled by default
+        config["processors"]["pymupdf"] = {
+            "extract_images": os.getenv("PYMUPDF_EXTRACT_IMAGES", "true").lower()
+            == "true",
+            "image_dir": os.getenv("PYMUPDF_IMAGE_DIR"),  # None = use temp directory
+        }
+
     # Custom processor (via HTTP API)
     if os.getenv("ENABLE_CUSTOM_PROCESSOR", "false").lower() == "true":
         custom_url = os.getenv("CUSTOM_PROCESSOR_URL")
@@ -126,6 +165,12 @@ def get_document_processor_config() -> dict[str, Any]:
 class Settings:
     """Application settings from environment variables."""
 
+    # Deployment mode (ADR-021: explicit mode selection)
+    # Optional: If not set, mode is auto-detected from other settings
+    # Valid values: single_user_basic, multi_user_basic, oauth_single_audience,
+    #               oauth_token_exchange, smithery
+    deployment_mode: Optional[str] = None
+
     # OAuth/OIDC settings
     oidc_discovery_url: Optional[str] = None
     oidc_client_id: Optional[str] = None
@@ -137,6 +182,10 @@ class Settings:
     nextcloud_username: Optional[str] = None
     nextcloud_password: Optional[str] = None
 
+    # Nextcloud SSL/TLS settings
+    nextcloud_verify_ssl: bool = True
+    nextcloud_ca_bundle: Optional[str] = None
+
     # ADR-005: Token Audience Validation (required for OAuth mode)
     nextcloud_mcp_server_url: Optional[str] = None  # MCP server URL (used as audience)
     nextcloud_resource_uri: Optional[str] = None  # Nextcloud resource identifier
@@ -150,6 +199,11 @@ class Settings:
     enable_token_exchange: bool = False
     enable_offline_access: bool = False
 
+    # Multi-user BasicAuth pass-through mode (ADR-019 interim solution)
+    # When enabled, MCP server extracts BasicAuth credentials from request headers
+    # and passes them through to Nextcloud APIs (no storage, stateless)
+    enable_multi_user_basic_auth: bool = False
+
     # Token exchange cache settings
     token_exchange_cache_ttl: int = 300  # seconds (5 minutes default)
 
@@ -168,6 +222,7 @@ class Settings:
     vector_sync_scan_interval: int = 300  # seconds (5 minutes)
     vector_sync_processor_workers: int = 3
     vector_sync_queue_max_size: int = 10000
+    vector_sync_user_poll_interval: int = 60  # seconds - OAuth mode user discovery
 
     # Qdrant settings (mutually exclusive modes)
     qdrant_url: Optional[str] = None  # Network mode: http://qdrant:6333
@@ -180,6 +235,11 @@ class Settings:
     ollama_embedding_model: str = "nomic-embed-text"
     ollama_verify_ssl: bool = True
 
+    # OpenAI settings (for embeddings)
+    openai_api_key: Optional[str] = None
+    openai_base_url: Optional[str] = None
+    openai_embedding_model: str = "text-embedding-3-small"
+
     # Document chunking settings (for vector embeddings)
     document_chunk_size: int = 2048  # Characters per chunk
     document_chunk_overlap: int = 200  # Overlapping characters between chunks
@@ -197,9 +257,25 @@ class Settings:
     log_include_trace_context: bool = True
 
     def __post_init__(self):
-        """Validate Qdrant configuration and set defaults."""
+        """Validate configuration and set defaults."""
         logger = logging.getLogger(__name__)
 
+        # Validate SSL/TLS configuration
+        if not self.nextcloud_verify_ssl:
+            logger.warning(
+                "NEXTCLOUD_VERIFY_SSL is disabled. "
+                "TLS certificate verification is turned off for all Nextcloud connections. "
+                "This is insecure and should only be used for development/testing."
+            )
+        if self.nextcloud_ca_bundle:
+            import os as _os
+
+            if not _os.path.isfile(self.nextcloud_ca_bundle):
+                raise ValueError(
+                    f"NEXTCLOUD_CA_BUNDLE path does not exist: {self.nextcloud_ca_bundle}"
+                )
+            logger.info("Using custom CA bundle: %s", self.nextcloud_ca_bundle)
+
         # Ensure mutual exclusivity
         if self.qdrant_url and self.qdrant_location:
             raise ValueError(
@@ -238,6 +314,29 @@ class Settings:
                 f"DOCUMENT_CHUNK_OVERLAP ({self.document_chunk_overlap}) cannot be negative."
             )
 
+    def get_embedding_model_name(self) -> str:
+        """
+        Get the active embedding model name based on provider priority.
+
+        Priority order (same as ProviderRegistry):
+        1. OpenAI - if OPENAI_API_KEY is set
+        2. Ollama - if OLLAMA_BASE_URL is set
+        3. Simple - fallback (returns "simple-384")
+
+        Returns:
+            Active embedding model name
+        """
+        # Check OpenAI first (higher priority than Ollama in registry)
+        if self.openai_api_key:
+            return self.openai_embedding_model
+
+        # Check Ollama
+        if self.ollama_base_url:
+            return self.ollama_embedding_model
+
+        # Fallback to simple provider indicator
+        return "simple-384"
+
     def get_collection_name(self) -> str:
         """
         Get Qdrant collection name.
@@ -253,13 +352,13 @@ class Settings:
         Format: {deployment-id}-{model-name}
 
         Examples:
-            - "my-deployment-nomic-embed-text" (OTEL_SERVICE_NAME set)
-            - "mcp-container-all-minilm" (hostname fallback)
+            - "my-deployment-nomic-embed-text" (Ollama)
+            - "my-deployment-text-embedding-3-small" (OpenAI)
+            - "mcp-container-openai-text-embedding-3-small" (hostname fallback)
 
         Returns:
             Collection name string
         """
-        import socket
 
         # Use explicit override if user configured non-default value
         if self.qdrant_collection != "nextcloud_content":
@@ -274,10 +373,135 @@ class Settings:
 
         # Sanitize deployment ID and model name
         deployment_id = deployment_id.lower().replace(" ", "-").replace("_", "-")
-        model_name = self.ollama_embedding_model.replace("/", "-").replace(":", "-")
+        model_name = self.get_embedding_model_name().replace("/", "-").replace(":", "-")
 
         return f"{deployment_id}-{model_name}"
 
+    # ADR-021: Property aliases for new naming convention
+    # These provide the new names while maintaining backward compatibility with old field names
+
+    @property
+    def enable_semantic_search(self) -> bool:
+        """Semantic search enabled (ADR-021 alias for vector_sync_enabled)."""
+        return self.vector_sync_enabled
+
+    @property
+    def enable_background_operations(self) -> bool:
+        """Background operations enabled (ADR-021 alias for enable_offline_access)."""
+        return self.enable_offline_access
+
+
+def _get_semantic_search_enabled() -> bool:
+    """Get semantic search enabled status, supporting both old and new variable names.
+
+    Supports:
+    - ENABLE_SEMANTIC_SEARCH (new, preferred)
+    - VECTOR_SYNC_ENABLED (old, deprecated)
+
+    Returns:
+        True if semantic search should be enabled
+    """
+    logger = logging.getLogger(__name__)
+
+    new_value = os.getenv("ENABLE_SEMANTIC_SEARCH", "").lower() == "true"
+    old_value = os.getenv("VECTOR_SYNC_ENABLED", "").lower() == "true"
+
+    if new_value and old_value:
+        logger.warning(
+            "Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. "
+            "Using ENABLE_SEMANTIC_SEARCH. "
+            "VECTOR_SYNC_ENABLED is deprecated and will be removed in v1.0.0."
+        )
+    elif old_value and not new_value:
+        logger.warning(
+            "VECTOR_SYNC_ENABLED is deprecated. "
+            "Please use ENABLE_SEMANTIC_SEARCH instead. "
+            "Support for VECTOR_SYNC_ENABLED will be removed in v1.0.0."
+        )
+
+    return new_value or old_value
+
+
+def _is_multi_user_mode() -> bool:
+    """Detect if this is a multi-user deployment mode.
+
+    Multi-user modes are:
+    - Multi-user BasicAuth (ENABLE_MULTI_USER_BASIC_AUTH=true)
+    - OAuth Single-Audience (no username/password set)
+    - OAuth Token Exchange (ENABLE_TOKEN_EXCHANGE=true)
+
+    Single-user modes are:
+    - Single-user BasicAuth (username and password both set)
+    - Smithery Stateless (SMITHERY_DEPLOYMENT=true)
+
+    Returns:
+        True if multi-user mode detected
+    """
+    # Smithery is always single-user (stateless)
+    if os.getenv("SMITHERY_DEPLOYMENT", "false").lower() == "true":
+        return False
+
+    # Multi-user BasicAuth explicitly enabled
+    if os.getenv("ENABLE_MULTI_USER_BASIC_AUTH", "false").lower() == "true":
+        return True
+
+    # Token exchange implies OAuth multi-user
+    if os.getenv("ENABLE_TOKEN_EXCHANGE", "false").lower() == "true":
+        return True
+
+    # If both username and password are set, it's single-user BasicAuth
+    has_username = bool(os.getenv("NEXTCLOUD_USERNAME"))
+    has_password = bool(os.getenv("NEXTCLOUD_PASSWORD"))
+    if has_username and has_password:
+        return False
+
+    # Otherwise, assume OAuth multi-user (default when no credentials provided)
+    return True
+
+
+def _get_background_operations_enabled() -> bool:
+    """Get background operations enabled status with auto-enablement for semantic search.
+
+    Supports:
+    - ENABLE_BACKGROUND_OPERATIONS (new, preferred)
+    - ENABLE_OFFLINE_ACCESS (old, deprecated)
+    - Auto-enabled if ENABLE_SEMANTIC_SEARCH=true in multi-user modes
+
+    Returns:
+        True if background operations should be enabled
+    """
+    logger = logging.getLogger(__name__)
+
+    # Check new and old variable names
+    explicit = os.getenv("ENABLE_BACKGROUND_OPERATIONS", "").lower() == "true"
+    legacy = os.getenv("ENABLE_OFFLINE_ACCESS", "").lower() == "true"
+
+    if explicit and legacy:
+        logger.warning(
+            "Both ENABLE_BACKGROUND_OPERATIONS and ENABLE_OFFLINE_ACCESS are set. "
+            "Using ENABLE_BACKGROUND_OPERATIONS. "
+            "ENABLE_OFFLINE_ACCESS is deprecated and will be removed in v1.0.0."
+        )
+    elif legacy and not explicit:
+        logger.warning(
+            "ENABLE_OFFLINE_ACCESS is deprecated. "
+            "Please use ENABLE_BACKGROUND_OPERATIONS instead. "
+            "Support for ENABLE_OFFLINE_ACCESS will be removed in v1.0.0."
+        )
+
+    # Auto-enable if semantic search is enabled in multi-user mode
+    semantic_search_enabled = _get_semantic_search_enabled()
+    is_multi_user = _is_multi_user_mode()
+    auto_enabled = semantic_search_enabled and is_multi_user
+
+    if auto_enabled and not (explicit or legacy):
+        logger.info(
+            "Automatically enabled background operations for semantic search in multi-user mode. "
+            "Set ENABLE_BACKGROUND_OPERATIONS=false to disable (this will also disable semantic search)."
+        )
+
+    return explicit or legacy or auto_enabled
+
 
 def get_settings() -> Settings:
     """Get application settings from environment variables.
@@ -285,7 +509,13 @@ def get_settings() -> Settings:
     Returns:
         Settings object with configuration values
     """
+    # Get consolidated values with smart dependency resolution
+    enable_semantic_search = _get_semantic_search_enabled()
+    enable_background_operations = _get_background_operations_enabled()
+
     return Settings(
+        # Deployment mode (ADR-021)
+        deployment_mode=os.getenv("MCP_DEPLOYMENT_MODE"),
         # OAuth/OIDC settings
         oidc_discovery_url=os.getenv("OIDC_DISCOVERY_URL"),
         oidc_client_id=os.getenv("NEXTCLOUD_OIDC_CLIENT_ID"),
@@ -295,6 +525,11 @@ def get_settings() -> Settings:
         nextcloud_host=os.getenv("NEXTCLOUD_HOST"),
         nextcloud_username=os.getenv("NEXTCLOUD_USERNAME"),
         nextcloud_password=os.getenv("NEXTCLOUD_PASSWORD"),
+        # Nextcloud SSL/TLS settings
+        nextcloud_verify_ssl=(
+            os.getenv("NEXTCLOUD_VERIFY_SSL", "true").lower() == "true"
+        ),
+        nextcloud_ca_bundle=os.getenv("NEXTCLOUD_CA_BUNDLE"),
         # ADR-005: Token Audience Validation
         nextcloud_mcp_server_url=os.getenv("NEXTCLOUD_MCP_SERVER_URL"),
         nextcloud_resource_uri=os.getenv("NEXTCLOUD_RESOURCE_URI"),
@@ -306,8 +541,10 @@ def get_settings() -> Settings:
         enable_token_exchange=(
             os.getenv("ENABLE_TOKEN_EXCHANGE", "false").lower() == "true"
         ),
-        enable_offline_access=(
-            os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
+        enable_offline_access=enable_background_operations,  # Smart dependency resolution
+        # Multi-user BasicAuth pass-through mode
+        enable_multi_user_basic_auth=(
+            os.getenv("ENABLE_MULTI_USER_BASIC_AUTH", "false").lower() == "true"
         ),
         # Token exchange cache settings
         token_exchange_cache_ttl=int(os.getenv("TOKEN_EXCHANGE_CACHE_TTL", "300")),
@@ -315,9 +552,7 @@ def get_settings() -> Settings:
         token_encryption_key=os.getenv("TOKEN_ENCRYPTION_KEY"),
         token_storage_db=os.getenv("TOKEN_STORAGE_DB", "/tmp/tokens.db"),
         # Vector sync settings (ADR-007)
-        vector_sync_enabled=(
-            os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
-        ),
+        vector_sync_enabled=enable_semantic_search,  # Smart dependency resolution
         vector_sync_scan_interval=int(os.getenv("VECTOR_SYNC_SCAN_INTERVAL", "300")),
         vector_sync_processor_workers=int(
             os.getenv("VECTOR_SYNC_PROCESSOR_WORKERS", "3")
@@ -325,6 +560,9 @@ def get_settings() -> Settings:
         vector_sync_queue_max_size=int(
             os.getenv("VECTOR_SYNC_QUEUE_MAX_SIZE", "10000")
         ),
+        vector_sync_user_poll_interval=int(
+            os.getenv("VECTOR_SYNC_USER_POLL_INTERVAL", "60")
+        ),
         # Qdrant settings
         qdrant_url=os.getenv("QDRANT_URL"),
         qdrant_location=os.getenv("QDRANT_LOCATION"),
@@ -334,6 +572,12 @@ def get_settings() -> Settings:
         ollama_base_url=os.getenv("OLLAMA_BASE_URL"),
         ollama_embedding_model=os.getenv("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text"),
         ollama_verify_ssl=os.getenv("OLLAMA_VERIFY_SSL", "true").lower() == "true",
+        # OpenAI settings
+        openai_api_key=os.getenv("OPENAI_API_KEY"),
+        openai_base_url=os.getenv("OPENAI_BASE_URL"),
+        openai_embedding_model=os.getenv(
+            "OPENAI_EMBEDDING_MODEL", "text-embedding-3-small"
+        ),
         # Document chunking settings
         document_chunk_size=int(os.getenv("DOCUMENT_CHUNK_SIZE", "2048")),
         document_chunk_overlap=int(os.getenv("DOCUMENT_CHUNK_OVERLAP", "200")),
@@ -351,3 +595,20 @@ def get_settings() -> Settings:
         log_include_trace_context=os.getenv("LOG_INCLUDE_TRACE_CONTEXT", "true").lower()
         == "true",
     )
+
+
+def get_nextcloud_ssl_verify() -> bool | ssl.SSLContext:
+    """Return the SSL verification setting for Nextcloud connections.
+
+    Returns:
+        - False if NEXTCLOUD_VERIFY_SSL=false (disable verification)
+        - ssl.SSLContext if NEXTCLOUD_CA_BUNDLE is set (custom CA)
+        - True otherwise (default system CA verification)
+    """
+    settings = get_settings()
+    if not settings.nextcloud_verify_ssl:
+        return False
+    if settings.nextcloud_ca_bundle:
+        ctx = ssl.create_default_context(cafile=settings.nextcloud_ca_bundle)
+        return ctx
+    return True

nextcloud_mcp_server/config_validators.py

@@ -0,0 +1,459 @@
+"""Configuration validation and mode detection for the MCP server.
+
+This module provides:
+- Mode detection based on configuration
+- Configuration validation with clear error messages
+- Single source of truth for deployment mode requirements
+
+See ADR-020 for detailed architecture and deployment mode documentation.
+"""
+
+import logging
+import os
+from dataclasses import dataclass
+from enum import Enum
+
+from nextcloud_mcp_server.config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+class AuthMode(Enum):
+    """Authentication mode for the MCP server.
+
+    Determines how users authenticate and how the server accesses Nextcloud.
+    """
+
+    SINGLE_USER_BASIC = "single_user_basic"
+    MULTI_USER_BASIC = "multi_user_basic"
+    OAUTH_SINGLE_AUDIENCE = "oauth_single"
+    OAUTH_TOKEN_EXCHANGE = "oauth_exchange"
+    SMITHERY_STATELESS = "smithery"
+
+
+@dataclass
+class ModeRequirements:
+    """Requirements for a deployment mode.
+
+    Attributes:
+        required: Configuration variables that must be set
+        optional: Configuration variables that may be set
+        forbidden: Configuration variables that should not be set
+        conditional: Additional requirements based on feature flags
+                     Format: {feature_flag: [required_vars]}
+        description: Human-readable description of the mode
+    """
+
+    required: list[str]
+    optional: list[str]
+    forbidden: list[str]
+    conditional: dict[str, list[str]]
+    description: str
+
+
+# Mode requirements definition
+MODE_REQUIREMENTS: dict[AuthMode, ModeRequirements] = {
+    AuthMode.SINGLE_USER_BASIC: ModeRequirements(
+        required=["nextcloud_host", "nextcloud_username", "nextcloud_password"],
+        optional=[
+            "vector_sync_enabled",
+            "qdrant_url",
+            "qdrant_location",
+            "ollama_base_url",
+            "ollama_embedding_model",
+            "openai_api_key",
+            "openai_embedding_model",
+            "document_chunk_size",
+            "document_chunk_overlap",
+        ],
+        forbidden=[
+            "enable_multi_user_basic_auth",
+            "enable_token_exchange",
+            "oidc_client_id",
+            "oidc_client_secret",
+        ],
+        conditional={
+            "vector_sync_enabled": [
+                # Either qdrant_url OR qdrant_location (checked in Settings.__post_init__)
+                # At least one embedding provider (ollama_base_url OR openai_api_key)
+            ],
+        },
+        description="Single-user deployment with BasicAuth credentials. "
+        "Suitable for personal Nextcloud instances and local development.",
+    ),
+    AuthMode.MULTI_USER_BASIC: ModeRequirements(
+        required=["nextcloud_host", "enable_multi_user_basic_auth"],
+        optional=[
+            # Background sync with app passwords (via Astrolabe)
+            "enable_offline_access",
+            "token_encryption_key",
+            "token_storage_db",
+            "oidc_client_id",
+            "oidc_client_secret",
+            # Vector sync
+            "vector_sync_enabled",
+            "qdrant_url",
+            "qdrant_location",
+            "ollama_base_url",
+            "ollama_embedding_model",
+            "openai_api_key",
+            "openai_embedding_model",
+        ],
+        forbidden=[
+            "nextcloud_username",
+            "nextcloud_password",
+            "enable_token_exchange",
+        ],
+        conditional={
+            "enable_offline_access": [
+                # OAuth credentials validated separately (lines 397-406) with clearer error message
+                "token_encryption_key",
+                "token_storage_db",
+            ],
+            # Note: vector_sync_enabled (now ENABLE_SEMANTIC_SEARCH) automatically
+            # enables background operations in multi-user modes. No explicit
+            # enable_offline_access setting required.
+        },
+        description="Multi-user deployment with BasicAuth pass-through. "
+        "Users provide credentials in request headers. "
+        "Optional background sync using app passwords stored via Astrolabe.",
+    ),
+    AuthMode.OAUTH_SINGLE_AUDIENCE: ModeRequirements(
+        required=["nextcloud_host"],
+        optional=[
+            # OAuth credentials (uses DCR if not provided)
+            "oidc_client_id",
+            "oidc_client_secret",
+            "oidc_discovery_url",
+            # Offline access
+            "enable_offline_access",
+            "token_encryption_key",
+            "token_storage_db",
+            # Vector sync
+            "vector_sync_enabled",
+            "qdrant_url",
+            "qdrant_location",
+            "ollama_base_url",
+            "ollama_embedding_model",
+            "openai_api_key",
+            "openai_embedding_model",
+            # Scopes
+            "nextcloud_oidc_scopes",
+        ],
+        forbidden=[
+            "nextcloud_username",
+            "nextcloud_password",
+            "enable_token_exchange",
+            "enable_multi_user_basic_auth",
+        ],
+        conditional={
+            "enable_offline_access": [
+                "token_encryption_key",
+                "token_storage_db",
+            ],
+            # Note: vector_sync_enabled (now ENABLE_SEMANTIC_SEARCH) automatically
+            # enables background operations in multi-user modes. No explicit
+            # enable_offline_access setting required.
+        },
+        description="OAuth multi-user deployment with single-audience tokens. "
+        "Tokens work for both MCP server and Nextcloud APIs (pass-through). "
+        "Uses Dynamic Client Registration if credentials not provided.",
+    ),
+    AuthMode.OAUTH_TOKEN_EXCHANGE: ModeRequirements(
+        required=["nextcloud_host", "enable_token_exchange"],
+        optional=[
+            # OAuth credentials
+            "oidc_client_id",
+            "oidc_client_secret",
+            "oidc_discovery_url",
+            # Token exchange settings
+            "token_exchange_cache_ttl",
+            # Offline access
+            "enable_offline_access",
+            "token_encryption_key",
+            "token_storage_db",
+            # Vector sync
+            "vector_sync_enabled",
+            "qdrant_url",
+            "qdrant_location",
+            "ollama_base_url",
+            "ollama_embedding_model",
+            "openai_api_key",
+            "openai_embedding_model",
+        ],
+        forbidden=[
+            "nextcloud_username",
+            "nextcloud_password",
+            "enable_multi_user_basic_auth",
+        ],
+        conditional={
+            "enable_offline_access": [
+                "token_encryption_key",
+                "token_storage_db",
+            ],
+            # Note: vector_sync_enabled (now ENABLE_SEMANTIC_SEARCH) automatically
+            # enables background operations in multi-user modes. No explicit
+            # enable_offline_access setting required.
+        },
+        description="OAuth multi-user deployment with token exchange (RFC 8693). "
+        "MCP tokens are separate from Nextcloud tokens. "
+        "Server exchanges MCP token for Nextcloud token on each request.",
+    ),
+    AuthMode.SMITHERY_STATELESS: ModeRequirements(
+        required=[],  # All config from session URL params
+        optional=[],
+        forbidden=[
+            "nextcloud_host",
+            "nextcloud_username",
+            "nextcloud_password",
+            "enable_multi_user_basic_auth",
+            "enable_token_exchange",
+            "enable_offline_access",
+            "vector_sync_enabled",
+            "oidc_client_id",
+            "oidc_client_secret",
+        ],
+        conditional={},
+        description="Stateless multi-tenant deployment for Smithery platform. "
+        "Configuration comes from session URL parameters. "
+        "No persistent storage, no OAuth, no vector sync.",
+    ),
+}
+
+
+def detect_auth_mode(settings: Settings) -> AuthMode:
+    """Detect authentication mode from configuration.
+
+    Mode detection priority (ADR-021):
+    0. Explicit MCP_DEPLOYMENT_MODE (if set) - NEW in ADR-021
+    1. Smithery (explicit flag)
+    2. Token exchange (most specific OAuth mode)
+    3. Multi-user BasicAuth
+    4. Single-user BasicAuth
+    5. OAuth single-audience (default OAuth mode)
+
+    Args:
+        settings: Application settings
+
+    Returns:
+        Detected AuthMode
+
+    Raises:
+        ValueError: If explicit deployment_mode is invalid or conflicts with detected mode
+    """
+
+    logger = logging.getLogger(__name__)
+
+    # ADR-021: Check for explicit deployment mode first
+    if settings.deployment_mode:
+        mode_str = settings.deployment_mode.lower().strip()
+
+        # Map string to AuthMode enum
+        mode_map = {
+            "single_user_basic": AuthMode.SINGLE_USER_BASIC,
+            "multi_user_basic": AuthMode.MULTI_USER_BASIC,
+            "oauth_single_audience": AuthMode.OAUTH_SINGLE_AUDIENCE,
+            "oauth_token_exchange": AuthMode.OAUTH_TOKEN_EXCHANGE,
+            "smithery": AuthMode.SMITHERY_STATELESS,
+        }
+
+        if mode_str not in mode_map:
+            valid_modes = ", ".join(mode_map.keys())
+            raise ValueError(
+                f"Invalid MCP_DEPLOYMENT_MODE: '{settings.deployment_mode}'. "
+                f"Valid values: {valid_modes}"
+            )
+
+        explicit_mode = mode_map[mode_str]
+        logger.info(f"Using explicit deployment mode: {explicit_mode.value}")
+        return explicit_mode
+
+    # Auto-detection (existing behavior)
+    # Check for Smithery mode (explicit environment variable)
+    # Note: This checks the environment directly, not settings
+    # because Smithery mode has no settings-based config
+    if os.getenv("SMITHERY_DEPLOYMENT", "false").lower() == "true":
+        return AuthMode.SMITHERY_STATELESS
+
+    # Check for token exchange (most specific OAuth mode)
+    if settings.enable_token_exchange:
+        return AuthMode.OAUTH_TOKEN_EXCHANGE
+
+    # Check for multi-user BasicAuth
+    if settings.enable_multi_user_basic_auth:
+        return AuthMode.MULTI_USER_BASIC
+
+    # Check for single-user BasicAuth (explicit credentials)
+    if settings.nextcloud_username and settings.nextcloud_password:
+        return AuthMode.SINGLE_USER_BASIC
+
+    # Default: OAuth single-audience mode
+    # This is the safest multi-user mode (no credential storage)
+    return AuthMode.OAUTH_SINGLE_AUDIENCE
+
+
+def validate_configuration(settings: Settings) -> tuple[AuthMode, list[str]]:
+    """Validate configuration for detected mode.
+
+    Args:
+        settings: Application settings
+
+    Returns:
+        Tuple of (detected_mode, list_of_errors)
+        Empty list means valid configuration.
+    """
+    mode = detect_auth_mode(settings)
+    requirements = MODE_REQUIREMENTS[mode]
+    errors: list[str] = []
+
+    logger.debug(f"Validating configuration for mode: {mode.value}")
+
+    # Check required variables
+    for var in requirements.required:
+        value = getattr(settings, var, None)
+        if value is None or (isinstance(value, str) and not value.strip()):
+            errors.append(
+                f"[{mode.value}] Missing required configuration: {var.upper()}"
+            )
+
+    # Check forbidden variables
+    for var in requirements.forbidden:
+        value = getattr(settings, var, None)
+        # For bools, check if True (forbidden means must be False/unset)
+        # For strings, check if non-empty
+        is_set = False
+        if isinstance(value, bool):
+            is_set = value is True
+        elif isinstance(value, str):
+            is_set = bool(value.strip())
+        elif value is not None:
+            is_set = True
+
+        if is_set:
+            errors.append(
+                f"[{mode.value}] Forbidden configuration: {var.upper()} "
+                f"should not be set in this mode"
+            )
+
+    # Check conditional requirements
+    for condition, required_vars in requirements.conditional.items():
+        # Check if the condition is enabled
+        condition_value = getattr(settings, condition, None)
+        is_enabled = False
+
+        if isinstance(condition_value, bool):
+            is_enabled = condition_value is True
+        elif isinstance(condition_value, str):
+            is_enabled = bool(condition_value.strip())
+        elif condition_value is not None:
+            is_enabled = True
+
+        if is_enabled:
+            # Check that all required vars for this condition are set
+            for var in required_vars:
+                value = getattr(settings, var, None)
+
+                # For boolean requirements, check that they are True (not just set)
+                if hasattr(Settings, var):
+                    field_type = type(getattr(Settings(), var, None))
+                    if field_type is bool:
+                        if value is not True:
+                            errors.append(
+                                f"[{mode.value}] {var.upper()} must be enabled when "
+                                f"{condition.upper()} is enabled"
+                            )
+                        continue
+
+                # For non-boolean requirements, check that they are set
+                if value is None or (isinstance(value, str) and not value.strip()):
+                    errors.append(
+                        f"[{mode.value}] {var.upper()} is required when "
+                        f"{condition.upper()} is enabled"
+                    )
+
+    # Special validations for specific modes
+    if mode == AuthMode.SINGLE_USER_BASIC:
+        # Validate that NEXTCLOUD_HOST doesn't have trailing slash
+        if settings.nextcloud_host and settings.nextcloud_host.endswith("/"):
+            errors.append(
+                f"[{mode.value}] NEXTCLOUD_HOST should not have trailing slash: "
+                f"{settings.nextcloud_host}"
+            )
+
+    if mode in [
+        AuthMode.OAUTH_SINGLE_AUDIENCE,
+        AuthMode.OAUTH_TOKEN_EXCHANGE,
+    ]:
+        # If OAuth credentials not provided, DCR must be available
+        # (This is a runtime check, not a config check, so we just warn)
+        if not settings.oidc_client_id or not settings.oidc_client_secret:
+            logger.info(
+                f"[{mode.value}] OAuth credentials not configured. "
+                "Will attempt Dynamic Client Registration (DCR) at startup."
+            )
+
+    if mode == AuthMode.MULTI_USER_BASIC:
+        # If background operations enabled, check for OAuth credentials (for app password retrieval)
+        # Allow DCR as fallback, just like OAuth modes
+        if settings.enable_offline_access:
+            if not settings.oidc_client_id or not settings.oidc_client_secret:
+                logger.info(
+                    f"[{mode.value}] OAuth credentials not configured. "
+                    "Will attempt Dynamic Client Registration (DCR) at startup "
+                    "(required for app password retrieval via Astrolabe)."
+                )
+
+        # Note: Vector sync no longer requires explicit ENABLE_OFFLINE_ACCESS setting
+        # ENABLE_SEMANTIC_SEARCH (formerly VECTOR_SYNC_ENABLED) automatically enables
+        # background operations in multi-user modes via smart dependency resolution
+        # in config.py
+
+    # Note: Embedding provider validation removed - Simple provider is always
+    # available as fallback (ADR-015). Users can optionally configure Ollama or OpenAI
+    # for better quality embeddings.
+
+    return mode, errors
+
+
+def get_mode_summary(mode: AuthMode) -> str:
+    """Get human-readable summary of a deployment mode.
+
+    Args:
+        mode: Deployment mode
+
+    Returns:
+        Multi-line string describing the mode
+    """
+    requirements = MODE_REQUIREMENTS[mode]
+
+    summary_lines = [
+        f"Mode: {mode.value}",
+        f"Description: {requirements.description}",
+        "",
+        "Required configuration:",
+    ]
+
+    if requirements.required:
+        for var in requirements.required:
+            summary_lines.append(f"  - {var.upper()}")
+    else:
+        summary_lines.append("  (none - configured via session)")
+
+    summary_lines.append("")
+    summary_lines.append("Optional configuration:")
+
+    if requirements.optional:
+        for var in requirements.optional:
+            summary_lines.append(f"  - {var.upper()}")
+    else:
+        summary_lines.append("  (none)")
+
+    if requirements.conditional:
+        summary_lines.append("")
+        summary_lines.append("Conditional requirements:")
+        for condition, vars in requirements.conditional.items():
+            summary_lines.append(f"  When {condition.upper()} is enabled:")
+            for var in vars:
+                summary_lines.append(f"    - {var.upper()}")
+
+    return "\n".join(summary_lines)

nextcloud_mcp_server/context.py

@@ -1,21 +1,37 @@
 """Helper functions for accessing context in MCP tools."""
 
+import logging
+
+from httpx import BasicAuth
 from mcp.server.fastmcp import Context
 
 from nextcloud_mcp_server.client import NextcloudClient
-from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.config import (
+    DeploymentMode,
+    get_deployment_mode,
+    get_settings,
+)
+
+logger = logging.getLogger(__name__)
 
 
 async def get_client(ctx: Context) -> NextcloudClient:
     """
     Get the appropriate Nextcloud client based on authentication mode.
 
-    ADR-005 compliant implementation supporting two modes:
-    1. BasicAuth mode: Returns shared client from lifespan context
-    2. Multi-audience mode (ENABLE_TOKEN_EXCHANGE=false, default):
-       Token already contains both MCP and Nextcloud audiences - use directly
-    3. Token exchange mode (ENABLE_TOKEN_EXCHANGE=true):
-       Exchange MCP token for Nextcloud token via RFC 8693
+    ADR-016 compliant implementation supporting three deployment modes:
+
+    1. Smithery stateless mode (SMITHERY_DEPLOYMENT=true):
+       Create client from session configuration (nextcloud_url, username, app_password)
+       No persistent state - client created per-request from Smithery session config.
+
+    2. BasicAuth mode: Returns shared client from lifespan context
+
+    3. OAuth mode:
+       a. Multi-audience mode (ENABLE_TOKEN_EXCHANGE=false, default):
+          Token already contains both MCP and Nextcloud audiences - use directly
+       b. Token exchange mode (ENABLE_TOKEN_EXCHANGE=true):
+          Exchange MCP token for Nextcloud token via RFC 8693
 
     SECURITY: Token passthrough has been REMOVED. All OAuth modes validate
     proper token audiences per MCP Security Best Practices specification.
@@ -24,7 +40,7 @@ async def get_client(ctx: Context) -> NextcloudClient:
     by the MCP server via @require_scopes decorator, not by the IdP.
 
     This function automatically detects the authentication mode by checking
-    the type of the lifespan context.
+    the deployment mode and type of the lifespan context.
 
     Args:
         ctx: MCP request context
@@ -34,6 +50,7 @@ async def get_client(ctx: Context) -> NextcloudClient:
 
     Raises:
         AttributeError: If context doesn't contain expected data
+        ValueError: If Smithery mode but session config is missing required fields
 
     Example:
         ```python
@@ -43,7 +60,18 @@ async def get_client(ctx: Context) -> NextcloudClient:
             return await client.capabilities()
         ```
     """
+    deployment_mode = get_deployment_mode()
+
+    # ADR-016: Smithery stateless mode - create client from session config
+    if deployment_mode == DeploymentMode.SMITHERY_STATELESS:
+        return _get_client_from_session_config(ctx)
+
     settings = get_settings()
+
+    # Multi-user BasicAuth pass-through mode - extract credentials from request
+    if settings.enable_multi_user_basic_auth:
+        return _get_client_from_basic_auth(ctx)
+
     lifespan_ctx = ctx.request_context.lifespan_context
 
     # BasicAuth mode - use shared client (no token exchange)
@@ -75,3 +103,146 @@ async def get_client(ctx: Context) -> NextcloudClient:
         f"Lifespan context does not have 'client' or 'nextcloud_host' attribute. "
         f"Type: {type(lifespan_ctx)}"
     )
+
+
+def _get_client_from_session_config(ctx: Context) -> NextcloudClient:
+    """
+    Create NextcloudClient from Smithery session configuration.
+
+    ADR-016: In Smithery stateless mode, each request includes session config
+    with the user's Nextcloud credentials. This function creates a fresh client
+    for each request - no state is persisted between requests.
+
+    For container runtime, config is extracted from URL query parameters by
+    SmitheryConfigMiddleware and stored in a context variable.
+
+    Expected session config fields (from Smithery configSchema):
+    - nextcloud_url: str - Nextcloud instance URL (required)
+    - username: str - Nextcloud username (required)
+    - app_password: str - Nextcloud app password (required)
+
+    Args:
+        ctx: MCP request context (not used directly for Smithery config)
+
+    Returns:
+        NextcloudClient configured with session credentials
+
+    Raises:
+        ValueError: If required session config fields are missing
+    """
+    # ADR-016: Get session config from context variable (set by SmitheryConfigMiddleware)
+    from nextcloud_mcp_server.app import get_smithery_session_config
+
+    session_config = get_smithery_session_config()
+
+    if session_config is None:
+        raise ValueError(
+            "Session configuration required in Smithery mode. "
+            "Ensure nextcloud_url, username, and app_password are provided as URL query parameters."
+        )
+
+    # Extract required fields - config is always a dict from SmitheryConfigMiddleware
+    nextcloud_url = session_config.get("nextcloud_url")
+    username = session_config.get("username")
+    app_password = session_config.get("app_password")
+
+    # Validate required fields
+    missing_fields = []
+    if not nextcloud_url:
+        missing_fields.append("nextcloud_url")
+    if not username:
+        missing_fields.append("username")
+    if not app_password:
+        missing_fields.append("app_password")
+
+    if missing_fields:
+        raise ValueError(
+            f"Missing required session config fields: {', '.join(missing_fields)}. "
+            f"Configure these in the Smithery connection settings."
+        )
+
+    # Type assertions after validation (for type checker)
+    # These are guaranteed to be str after the missing_fields check above
+    assert nextcloud_url is not None
+    assert username is not None
+    assert app_password is not None
+
+    # Validate URL format
+    if not nextcloud_url.startswith(("http://", "https://")):
+        raise ValueError(
+            f"Invalid nextcloud_url: {nextcloud_url}. "
+            f"Must start with http:// or https://"
+        )
+
+    logger.debug(f"Creating Smithery client for {nextcloud_url} as {username}")
+
+    # Create client with session credentials using BasicAuth
+    return NextcloudClient(
+        base_url=nextcloud_url,
+        username=username,
+        auth=BasicAuth(username, app_password),
+    )
+
+
+def _get_client_from_basic_auth(ctx: Context) -> NextcloudClient:
+    """
+    Create NextcloudClient from BasicAuth credentials in request headers.
+
+    For multi-user BasicAuth pass-through mode, this function extracts
+    username/password from the Authorization: Basic header (stored by
+    BasicAuthMiddleware) and creates a client that passes these credentials
+    through to Nextcloud APIs.
+
+    The credentials are NOT stored persistently - they exist only for the
+    duration of this request (stateless).
+
+    Args:
+        ctx: MCP request context with basic_auth in request state
+
+    Returns:
+        NextcloudClient configured with BasicAuth credentials
+
+    Raises:
+        ValueError: If BasicAuth credentials not found in request or if
+                   NEXTCLOUD_HOST is not configured
+    """
+    settings = get_settings()
+
+    # Validate that NEXTCLOUD_HOST is configured
+    if not settings.nextcloud_host:
+        raise ValueError(
+            "NEXTCLOUD_HOST environment variable must be set for multi-user BasicAuth mode"
+        )
+
+    # Extract BasicAuth credentials from request state (set by BasicAuthMiddleware)
+    # Access scope through the request object
+    scope = getattr(ctx.request_context.request, "scope", None)
+    if scope is None:
+        raise ValueError("Request scope not available in context")
+
+    request_state = scope.get("state", {})
+    basic_auth = request_state.get("basic_auth")
+
+    if not basic_auth:
+        raise ValueError(
+            "BasicAuth credentials not found in request. "
+            "Ensure Authorization: Basic header is provided with valid credentials."
+        )
+
+    username = basic_auth.get("username")
+    password = basic_auth.get("password")
+
+    if not username or not password:
+        raise ValueError("Invalid BasicAuth credentials - missing username or password")
+
+    logger.debug(
+        f"Creating multi-user BasicAuth client for {settings.nextcloud_host} as {username}"
+    )
+
+    # Create client that passes BasicAuth credentials through to Nextcloud
+    # settings.nextcloud_host is guaranteed to be str after the check above
+    return NextcloudClient(
+        base_url=settings.nextcloud_host,
+        username=username,
+        auth=BasicAuth(username, password),
+    )

nextcloud_mcp_server/document_processors/__init__.py

@@ -1,12 +1,18 @@
 """Document processing plugins for extracting text from various file formats."""
 
 from .base import DocumentProcessor, ProcessingResult, ProcessorError
+from .pymupdf import PyMuPDFProcessor
 from .registry import ProcessorRegistry, get_registry
 
+# Register processors at module initialization
+_registry = get_registry()
+_registry.register(PyMuPDFProcessor(), priority=10)
+
 __all__ = [
     "DocumentProcessor",
     "ProcessingResult",
     "ProcessorError",
     "ProcessorRegistry",
     "get_registry",
+    "PyMuPDFProcessor",
 ]

nextcloud_mcp_server/document_processors/pymupdf.py

@@ -0,0 +1,254 @@
+"""Document processor using PyMuPDF (fitz) library."""
+
+import logging
+import pathlib
+import tempfile
+from collections.abc import Awaitable, Callable
+from typing import Any, Optional
+
+import anyio
+
+# NOTE: Do NOT call pymupdf.layout.activate() here!
+# It changes the behavior of pymupdf4llm.to_markdown() when page_chunks=True,
+# causing it to return a string instead of a list[dict].
+# See: https://github.com/pymupdf/pymupdf4llm/issues/323
+import pymupdf
+import pymupdf4llm
+
+from .base import DocumentProcessor, ProcessingResult, ProcessorError
+
+logger = logging.getLogger(__name__)
+
+
+class PyMuPDFProcessor(DocumentProcessor):
+    """Document processor using PyMuPDF library for PDF processing.
+
+    PyMuPDF (fitz) is a fast, local PDF processing library that extracts text,
+    metadata, and images without requiring external API calls.
+
+    Features:
+    - Fast text extraction with layout preservation
+    - PDF metadata extraction (title, author, creation date, page count)
+    - Image extraction for future multimodal support
+    - Page number tracking for precise citations
+    """
+
+    SUPPORTED_TYPES = {
+        "application/pdf",
+    }
+
+    def __init__(
+        self,
+        extract_images: bool = True,
+        image_dir: Optional[str | pathlib.Path] = None,
+    ):
+        """Initialize PyMuPDF processor.
+
+        Args:
+            extract_images: Whether to extract embedded images from PDFs
+            image_dir: Directory to store extracted images (defaults to temp directory)
+        """
+        self.extract_images = extract_images
+
+        if image_dir is None:
+            self.image_dir = pathlib.Path(tempfile.gettempdir()) / "pdf-images"
+        else:
+            self.image_dir = pathlib.Path(image_dir)
+
+        # Create image directory if it doesn't exist
+        if self.extract_images:
+            self.image_dir.mkdir(exist_ok=True, parents=True)
+            logger.info(
+                f"Initialized PyMuPDFProcessor with image extraction to {self.image_dir}"
+            )
+        else:
+            logger.info("Initialized PyMuPDFProcessor without image extraction")
+
+    @property
+    def name(self) -> str:
+        return "pymupdf"
+
+    @property
+    def supported_mime_types(self) -> set[str]:
+        return self.SUPPORTED_TYPES
+
+    async def process(
+        self,
+        content: bytes,
+        content_type: str,
+        filename: Optional[str] = None,
+        options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
+    ) -> ProcessingResult:
+        """Process a PDF document and extract text, metadata, and images.
+
+        Args:
+            content: PDF document bytes
+            content_type: MIME type (should be application/pdf)
+            filename: Optional filename for better error messages
+            options: Processing options (currently unused)
+            progress_callback: Optional callback for progress updates
+
+        Returns:
+            ProcessingResult with extracted text and metadata
+
+        Raises:
+            ProcessorError: If PDF processing fails
+        """
+
+        try:
+            if progress_callback:
+                await progress_callback(0, 100, "Opening PDF document")
+
+            # Open document and extract metadata in thread
+            doc = await anyio.to_thread.run_sync(  # type: ignore[attr-defined]
+                lambda: pymupdf.open("pdf", content)
+            )
+
+            metadata = self._extract_metadata(doc, filename)
+            metadata["file_size"] = len(content)
+            page_count = doc.page_count
+
+            if progress_callback:
+                await progress_callback(10, 100, f"Extracting {page_count} pages")
+
+            # Prepare image directory if needed
+            pdf_image_dir = None
+            if self.extract_images:
+                pdf_id = filename.replace("/", "_") if filename else "unknown"
+                pdf_image_dir = self.image_dir / pdf_id
+                pdf_image_dir.mkdir(exist_ok=True, parents=True)
+
+            # Extract all pages in a single call with page_chunks=True
+            def do_extract() -> list[dict[str, Any]]:
+                # When page_chunks=True, to_markdown returns list[dict] not str
+                return pymupdf4llm.to_markdown(  # type: ignore[return-value]
+                    doc,
+                    write_images=self.extract_images,
+                    image_path=pdf_image_dir if self.extract_images else None,
+                    page_chunks=True,
+                )
+
+            page_chunks: list[dict[str, Any]] = await anyio.to_thread.run_sync(  # type: ignore[attr-defined]
+                do_extract
+            )
+
+            if progress_callback:
+                await progress_callback(90, 100, "Building result")
+
+            # Extract page texts and build boundaries from chunks
+            page_texts: list[str] = []
+            page_boundaries: list[dict[str, Any]] = []
+            current_offset = 0
+            for chunk in page_chunks:
+                text = chunk.get("text", "")
+                page_num = chunk.get("metadata", {}).get("page", len(page_texts) + 1)
+                page_texts.append(text)
+                page_boundaries.append(
+                    {
+                        "page": page_num,
+                        "start_offset": current_offset,
+                        "end_offset": current_offset + len(text),
+                    }
+                )
+                current_offset += len(text)
+
+            # Collect image paths
+            image_paths = []
+            if pdf_image_dir and pdf_image_dir.exists():
+                image_paths = [str(p) for p in pdf_image_dir.glob("*")]
+
+            # Build final text and metadata
+            md_text = "".join(page_texts)
+            metadata["has_images"] = len(image_paths) > 0
+            if image_paths:
+                metadata["image_count"] = len(image_paths)
+                metadata["image_paths"] = image_paths
+            metadata["page_boundaries"] = page_boundaries
+
+            # Close document
+            doc.close()
+
+            if progress_callback:
+                await progress_callback(100, 100, "Processing complete")
+
+            logger.info(
+                f"Successfully processed PDF {filename or '<bytes>'}: "
+                f"{metadata['page_count']} pages, {len(md_text)} chars, "
+                f"{metadata.get('image_count', 0)} images"
+            )
+
+            return ProcessingResult(
+                text=md_text,
+                metadata=metadata,
+                processor=self.name,
+                success=True,
+            )
+
+        except Exception as e:
+            error_msg = f"Failed to process PDF {filename or '<bytes>'}: {e}"
+            logger.error(error_msg, exc_info=True)
+            raise ProcessorError(error_msg) from e
+
+    def _extract_metadata(
+        self, doc: pymupdf.Document, filename: Optional[str]
+    ) -> dict[str, Any]:
+        """Extract metadata from PDF document.
+
+        Args:
+            doc: Opened PyMuPDF document
+            filename: Optional filename
+
+        Returns:
+            Dictionary with PDF metadata
+        """
+        metadata: dict[str, Any] = {}
+
+        # Basic document info
+        metadata["page_count"] = doc.page_count
+        metadata["format"] = "PDF 1." + str(
+            doc.pdf_version() if hasattr(doc, "pdf_version") else "?"  # type: ignore[call-non-callable]
+        )
+
+        if filename:
+            metadata["filename"] = filename
+
+        # Extract PDF metadata dictionary
+        pdf_metadata = doc.metadata
+        if pdf_metadata:
+            # Standard PDF metadata fields
+            if pdf_metadata.get("title"):
+                metadata["title"] = pdf_metadata["title"]
+            if pdf_metadata.get("author"):
+                metadata["author"] = pdf_metadata["author"]
+            if pdf_metadata.get("subject"):
+                metadata["subject"] = pdf_metadata["subject"]
+            if pdf_metadata.get("keywords"):
+                metadata["keywords"] = pdf_metadata["keywords"]
+            if pdf_metadata.get("creator"):
+                metadata["creator"] = pdf_metadata["creator"]
+            if pdf_metadata.get("producer"):
+                metadata["producer"] = pdf_metadata["producer"]
+            if pdf_metadata.get("creationDate"):
+                metadata["creation_date"] = pdf_metadata["creationDate"]
+            if pdf_metadata.get("modDate"):
+                metadata["modification_date"] = pdf_metadata["modDate"]
+
+        return metadata
+
+    async def health_check(self) -> bool:
+        """Check if PyMuPDF is available and working.
+
+        Returns:
+            True if processor is ready to use
+        """
+        try:
+            # Try to create a simple PDF in memory
+            test_doc = pymupdf.open()
+            test_doc.close()
+            return True
+        except Exception as e:
+            logger.error(f"PyMuPDF health check failed: {e}")
+            return False

nextcloud_mcp_server/embedding/bm25_provider.py

@@ -3,6 +3,7 @@
 import logging
 from typing import Any
 
+import anyio
 from fastembed import SparseTextEmbedding
 
 logger = logging.getLogger(__name__)
@@ -37,7 +38,9 @@ class BM25SparseEmbeddingProvider:
 
     def encode(self, text: str) -> dict[str, Any]:
         """
-        Generate BM25 sparse embedding for a single text.
+        Generate BM25 sparse embedding for a single text (synchronous).
+
+        Note: For async contexts, prefer encode_async() to avoid blocking the event loop.
 
         Args:
             text: Input text to encode
@@ -53,7 +56,23 @@ class BM25SparseEmbeddingProvider:
             "values": sparse_embedding.values.tolist(),
         }
 
-    def encode_batch(self, texts: list[str]) -> list[dict[str, Any]]:
+    async def encode_async(self, text: str) -> dict[str, Any]:
+        """
+        Generate BM25 sparse embedding for a single text (async).
+
+        Runs CPU-bound BM25 encoding in thread pool to avoid blocking the event loop.
+
+        Args:
+            text: Input text to encode
+
+        Returns:
+            Dictionary with 'indices' and 'values' keys for Qdrant sparse vector
+        """
+
+        # Run CPU-bound BM25 encoding in thread pool
+        return await anyio.to_thread.run_sync(lambda: self.encode(text))  # type: ignore[attr-defined]
+
+    async def encode_batch(self, texts: list[str]) -> list[dict[str, Any]]:
         """
         Generate BM25 sparse embeddings for multiple texts (batched).
 
@@ -63,7 +82,11 @@ class BM25SparseEmbeddingProvider:
         Returns:
             List of dictionaries with 'indices' and 'values' for each text
         """
-        sparse_embeddings = list(self.model.embed(texts))
+
+        # Run CPU-bound BM25 encoding in thread pool to avoid blocking event loop
+        sparse_embeddings = await anyio.to_thread.run_sync(  # type: ignore[attr-defined]
+            lambda: list(self.model.embed(texts))
+        )
 
         return [
             {

nextcloud_mcp_server/http.py

@@ -0,0 +1,45 @@
+"""Centralized HTTP client factory for Nextcloud connections.
+
+All outbound connections to Nextcloud (API calls, OIDC endpoints) should use
+these factories to ensure consistent SSL/TLS configuration from environment
+variables (NEXTCLOUD_VERIFY_SSL, NEXTCLOUD_CA_BUNDLE).
+"""
+
+from typing import Any
+
+import httpx
+
+from .config import get_nextcloud_ssl_verify
+
+
+def nextcloud_httpx_client(**kwargs: Any) -> httpx.AsyncClient:
+    """Create an httpx.AsyncClient with Nextcloud SSL settings applied.
+
+    Reads NEXTCLOUD_VERIFY_SSL and NEXTCLOUD_CA_BUNDLE from the environment
+    via ``get_nextcloud_ssl_verify()``. Caller-supplied ``verify`` kwarg
+    takes precedence if explicitly provided.
+
+    Args:
+        **kwargs: Forwarded to ``httpx.AsyncClient()``.
+
+    Returns:
+        Configured ``httpx.AsyncClient``.
+    """
+    kwargs.setdefault("verify", get_nextcloud_ssl_verify())
+    return httpx.AsyncClient(**kwargs)
+
+
+def nextcloud_httpx_transport(**kwargs: Any) -> httpx.AsyncHTTPTransport:
+    """Create an httpx.AsyncHTTPTransport with Nextcloud SSL settings applied.
+
+    Used by ``NextcloudClient`` which wraps the transport in
+    ``AsyncDisableCookieTransport``.
+
+    Args:
+        **kwargs: Forwarded to ``httpx.AsyncHTTPTransport()``.
+
+    Returns:
+        Configured ``httpx.AsyncHTTPTransport``.
+    """
+    kwargs.setdefault("verify", get_nextcloud_ssl_verify())
+    return httpx.AsyncHTTPTransport(**kwargs)

nextcloud_mcp_server/migrations.py

@@ -0,0 +1,192 @@
+"""Database migration utilities for nextcloud-mcp-server.
+
+This module provides helper functions for managing Alembic database migrations
+programmatically. It enables automatic migration on application startup and
+provides CLI integration.
+"""
+
+import logging
+import sqlite3
+from pathlib import Path
+
+from alembic.config import Config
+
+from alembic import command
+
+logger = logging.getLogger(__name__)
+
+
+def get_alembic_config(database_path: str | Path | None = None) -> Config:
+    """
+    Get Alembic configuration for programmatic use.
+
+    Works in both development and installed (Docker) modes by using
+    package location instead of alembic.ini file.
+
+    Args:
+        database_path: Path to SQLite database file. If None, uses default
+                      (/app/data/tokens.db for Docker)
+
+    Returns:
+        Alembic Config object configured for the specified database
+    """
+    from nextcloud_mcp_server import alembic as alembic_package
+
+    # Use package location (works in both editable and installed modes)
+    if alembic_package.__file__ is None:
+        raise RuntimeError("alembic package __file__ is None")
+    script_location = Path(alembic_package.__file__).parent
+
+    # Create config programmatically (no alembic.ini needed at runtime)
+    config = Config()
+    config.set_main_option("script_location", str(script_location))
+    config.set_main_option("path_separator", "os")  # Suppress deprecation warning
+
+    # Set database URL
+    if database_path:
+        db_path = Path(database_path).resolve()
+    else:
+        db_path = Path("/app/data/tokens.db")  # Default for Docker
+
+    url = f"sqlite+aiosqlite:///{db_path}"
+    config.set_main_option("sqlalchemy.url", url)
+
+    logger.debug(f"Alembic script location: {script_location}")
+    logger.debug(f"Database: {db_path}")
+
+    return config
+
+
+def upgrade_database(
+    database_path: str | Path | None = None, revision: str = "head"
+) -> None:
+    """
+    Upgrade database to a specific revision.
+
+    Args:
+        database_path: Path to SQLite database file
+        revision: Target revision (default: "head" for latest)
+    """
+    config = get_alembic_config(database_path)
+    logger.info(f"Upgrading database to revision: {revision}")
+    command.upgrade(config, revision)
+    logger.info("Database upgrade completed successfully")
+
+
+def downgrade_database(
+    database_path: str | Path | None = None, revision: str = "-1"
+) -> None:
+    """
+    Downgrade database to a specific revision.
+
+    Args:
+        database_path: Path to SQLite database file
+        revision: Target revision (default: "-1" for previous version)
+    """
+    config = get_alembic_config(database_path)
+    logger.warning(f"Downgrading database to revision: {revision}")
+    command.downgrade(config, revision)
+    logger.info("Database downgrade completed successfully")
+
+
+def get_current_revision(database_path: str | Path | None = None) -> str | None:
+    """
+    Get the current database revision by directly querying the alembic_version table.
+
+    Args:
+        database_path: Path to SQLite database file
+
+    Returns:
+        Current revision ID or None if not versioned
+    """
+
+    if database_path is None:
+        database_path = "/app/data/tokens.db"
+
+    db_path = Path(database_path).resolve()
+
+    if not db_path.exists():
+        logger.debug(f"Database does not exist: {db_path}")
+        return None
+
+    try:
+        # Query alembic_version table directly
+        conn = sqlite3.connect(str(db_path))
+        cursor = conn.cursor()
+
+        # Check if alembic_version table exists
+        cursor.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='alembic_version'"
+        )
+        has_table = cursor.fetchone() is not None
+
+        if not has_table:
+            conn.close()
+            return None
+
+        # Get current version
+        cursor.execute("SELECT version_num FROM alembic_version")
+        row = cursor.fetchone()
+        conn.close()
+
+        return row[0] if row else None
+
+    except Exception as e:
+        logger.error(f"Failed to get current revision: {e}")
+        return None
+
+
+def stamp_database(
+    database_path: str | Path | None = None, revision: str = "head"
+) -> None:
+    """
+    Stamp database with a specific revision without running migrations.
+
+    This is useful for marking existing databases that were created before
+    Alembic was introduced. It tells Alembic "this database is at revision X"
+    without actually running the migration.
+
+    Args:
+        database_path: Path to SQLite database file
+        revision: Revision to stamp (default: "head" for latest)
+    """
+    config = get_alembic_config(database_path)
+    logger.info(f"Stamping database with revision: {revision}")
+    command.stamp(config, revision)
+    logger.info("Database stamped successfully")
+
+
+def show_migration_history(database_path: str | Path | None = None) -> None:
+    """
+    Display migration history.
+
+    Args:
+        database_path: Path to SQLite database file
+    """
+    config = get_alembic_config(database_path)
+    command.history(config, verbose=True)
+
+
+def create_migration(message: str, autogenerate: bool = False) -> None:
+    """
+    Create a new migration script.
+
+    Args:
+        message: Description of the migration
+        autogenerate: Whether to attempt auto-generation (requires SQLAlchemy models)
+
+    Note:
+        Since we don't use SQLAlchemy models, autogenerate will be disabled
+        and migrations must be written manually.
+    """
+    config = get_alembic_config()
+    logger.info(f"Creating new migration: {message}")
+
+    if autogenerate:
+        logger.warning(
+            "Auto-generation is not supported (no SQLAlchemy models). "
+            "Migration will be created with empty upgrade/downgrade functions."
+        )
+
+    command.revision(config, message=message, autogenerate=False)
+    logger.info("Migration created successfully. Edit the file to add SQL statements.")

nextcloud_mcp_server/models/news.py

@@ -0,0 +1,170 @@
+"""Pydantic models for Nextcloud News app responses."""
+
+from typing import List
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .base import BaseResponse
+
+
+class NewsFolder(BaseModel):
+    """Model for a News folder."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int = Field(description="Folder ID")
+    name: str = Field(description="Folder name")
+
+
+class NewsFeed(BaseModel):
+    """Model for a News feed (RSS/Atom subscription)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int = Field(description="Feed ID")
+    url: str = Field(description="Feed URL")
+    title: str = Field(description="Feed title")
+    favicon_link: str | None = Field(
+        None, alias="faviconLink", description="Favicon URL"
+    )
+    link: str | None = Field(None, description="Website link")
+    added: int = Field(description="Unix timestamp when feed was added")
+    folder_id: int | None = Field(
+        None, alias="folderId", description="Parent folder ID"
+    )
+    unread_count: int = Field(
+        0, alias="unreadCount", description="Number of unread items"
+    )
+    ordering: int = Field(
+        0, description="Feed ordering (0=default, 1=oldest, 2=newest)"
+    )
+    pinned: bool = Field(False, description="Whether feed is pinned to top")
+    update_error_count: int = Field(
+        0, alias="updateErrorCount", description="Consecutive update failures"
+    )
+    last_update_error: str | None = Field(
+        None, alias="lastUpdateError", description="Last update error message"
+    )
+
+    @property
+    def has_errors(self) -> bool:
+        """Check if feed has update errors."""
+        return self.update_error_count > 0
+
+
+class NewsItem(BaseModel):
+    """Model for a News item (article) with full content."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int = Field(description="Item ID")
+    guid: str = Field(description="Globally unique identifier")
+    guid_hash: str = Field(alias="guidHash", description="MD5 hash of GUID")
+    url: str | None = Field(None, description="Article URL")
+    title: str = Field(description="Article title")
+    author: str | None = Field(None, description="Article author")
+    pub_date: int | None = Field(
+        None, alias="pubDate", description="Publication timestamp"
+    )
+    body: str | None = Field(None, description="Article content (HTML)")
+    enclosure_mime: str | None = Field(
+        None, alias="enclosureMime", description="Enclosure MIME type"
+    )
+    enclosure_link: str | None = Field(
+        None, alias="enclosureLink", description="Enclosure URL"
+    )
+    media_thumbnail: str | None = Field(
+        None, alias="mediaThumbnail", description="Media thumbnail URL"
+    )
+    media_description: str | None = Field(
+        None, alias="mediaDescription", description="Media description"
+    )
+    feed_id: int = Field(alias="feedId", description="Parent feed ID")
+    unread: bool = Field(True, description="Whether item is unread")
+    starred: bool = Field(False, description="Whether item is starred")
+    rtl: bool = Field(False, description="Right-to-left text")
+    last_modified: int = Field(
+        alias="lastModified", description="Last modification timestamp"
+    )
+    fingerprint: str | None = Field(
+        None, description="Content fingerprint for deduplication"
+    )
+    content_hash: str | None = Field(
+        None, alias="contentHash", description="Content hash"
+    )
+
+
+class NewsItemSummary(BaseModel):
+    """Lightweight model for News item list responses."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int = Field(description="Item ID")
+    title: str = Field(description="Article title")
+    feed_id: int = Field(alias="feedId", description="Parent feed ID")
+    unread: bool = Field(True, description="Whether item is unread")
+    starred: bool = Field(False, description="Whether item is starred")
+    pub_date: int | None = Field(
+        None, alias="pubDate", description="Publication timestamp"
+    )
+    url: str | None = Field(None, description="Article URL")
+    author: str | None = Field(None, description="Article author")
+
+
+class NewsStatus(BaseModel):
+    """Model for News app status."""
+
+    version: str = Field(description="News app version")
+    warnings: dict = Field(default_factory=dict, description="Configuration warnings")
+
+
+# --- Response Models ---
+
+
+class ListFoldersResponse(BaseResponse):
+    """Response model for listing folders."""
+
+    results: List[NewsFolder] = Field(description="List of folders")
+    total_count: int = Field(description="Total number of folders")
+
+
+class ListFeedsResponse(BaseResponse):
+    """Response model for listing feeds."""
+
+    results: List[NewsFeed] = Field(description="List of feeds")
+    starred_count: int = Field(0, description="Number of starred items")
+    newest_item_id: int | None = Field(None, description="ID of newest item")
+    total_count: int = Field(description="Total number of feeds")
+
+
+class ListItemsResponse(BaseResponse):
+    """Response model for listing items."""
+
+    results: List[NewsItemSummary] = Field(description="List of items")
+    total_count: int = Field(description="Number of items returned")
+    has_more: bool = Field(False, description="Whether more items exist")
+    oldest_id: int | None = Field(None, description="Oldest item ID (for pagination)")
+
+
+class GetItemResponse(BaseResponse):
+    """Response model for getting a single item."""
+
+    item: NewsItem = Field(description="Full item details")
+
+
+class FeedHealthResponse(BaseResponse):
+    """Response model for feed health status."""
+
+    feed_id: int = Field(description="Feed ID")
+    title: str = Field(description="Feed title")
+    url: str = Field(description="Feed URL")
+    has_errors: bool = Field(description="Whether feed has update errors")
+    error_count: int = Field(description="Number of consecutive errors")
+    last_error: str | None = Field(None, description="Last error message")
+
+
+class GetStatusResponse(BaseResponse):
+    """Response model for app status."""
+
+    version: str = Field(description="News app version")
+    warnings: dict = Field(default_factory=dict, description="Configuration warnings")

nextcloud_mcp_server/models/semantic.py

@@ -10,7 +10,7 @@ from .base import BaseResponse
 class SemanticSearchResult(BaseModel):
     """Model for semantic search results with additional metadata."""
 
-    id: int = Field(description="Document ID")
+    id: int = Field(description="Document ID (int for all document types)")
     doc_type: str = Field(
         description="Document type (note, calendar_event, deck_card, etc.)"
     )
@@ -35,6 +35,32 @@ class SemanticSearchResult(BaseModel):
     chunk_end_offset: Optional[int] = Field(
         default=None, description="Character position where chunk ends in document"
     )
+    page_number: Optional[int] = Field(
+        default=None, description="Page number for PDF documents"
+    )
+    page_count: Optional[int] = Field(
+        default=None, description="Total number of pages in PDF document"
+    )
+    # Context expansion fields (optional, populated when include_context=True)
+    has_context_expansion: bool = Field(
+        default=False, description="Whether context expansion was performed"
+    )
+    marked_text: Optional[str] = Field(
+        default=None,
+        description="Full text with position markers around matched chunk",
+    )
+    before_context: Optional[str] = Field(
+        default=None, description="Text before the matched chunk"
+    )
+    after_context: Optional[str] = Field(
+        default=None, description="Text after the matched chunk"
+    )
+    has_before_truncation: Optional[bool] = Field(
+        default=None, description="Whether before_context was truncated"
+    )
+    has_after_truncation: Optional[bool] = Field(
+        default=None, description="Whether after_context was truncated"
+    )
 
 
 class SemanticSearchResponse(BaseResponse):

nextcloud_mcp_server/observability/logging_config.py

@@ -37,7 +37,7 @@ class HealthCheckFilter(logging.Filter):
         """
         # Check if the log message contains health check endpoints
         message = record.getMessage()
-        return not any(
+        health_check = any(
             endpoint in message
             for endpoint in [
                 "/health/live",
@@ -47,6 +47,8 @@ class HealthCheckFilter(logging.Filter):
             ]
         )
 
+        return not health_check
+
 
 class TraceContextFormatter(JsonFormatter):
     """
@@ -58,7 +60,7 @@ class TraceContextFormatter(JsonFormatter):
 
     def add_fields(
         self,
-        log_record: dict[str, Any],
+        log_data: dict[str, Any],
         record: logging.LogRecord,
         message_dict: dict[str, Any],
     ) -> None:
@@ -66,28 +68,28 @@ class TraceContextFormatter(JsonFormatter):
         Add custom fields to the log record, including trace context.
 
         Args:
-            log_record: Dictionary to be serialized as JSON
+            log_data: Dictionary to be serialized as JSON
             record: LogRecord instance
             message_dict: Dictionary of extra fields from log call
         """
         # Call parent to add standard fields
-        super().add_fields(log_record, record, message_dict)
+        super().add_fields(log_data, record, message_dict)
 
         # Add trace context if available
         trace_context = get_trace_context()
         if trace_context:
-            log_record["trace_id"] = trace_context.get("trace_id")
-            log_record["span_id"] = trace_context.get("span_id")
+            log_data["trace_id"] = trace_context.get("trace_id")
+            log_data["span_id"] = trace_context.get("span_id")
 
         # Add standard fields with consistent naming
-        log_record["timestamp"] = self.formatTime(record)
-        log_record["level"] = record.levelname
-        log_record["logger"] = record.name
-        log_record["message"] = record.getMessage()
+        log_data["timestamp"] = self.formatTime(record)
+        log_data["level"] = record.levelname
+        log_data["logger"] = record.name
+        log_data["message"] = record.getMessage()
 
         # Include exception info if present
         if record.exc_info:
-            log_record["exception"] = self.formatException(record.exc_info)
+            log_data["exception"] = self.formatException(record.exc_info)
 
 
 class TraceContextTextFormatter(logging.Formatter):