bump: version 0.36.0 → 0.37.0

.dockerignore

@@ -5,5 +5,3 @@
 !uv.lock
 
 !nextcloud_mcp_server/**/*.py
-!nextcloud_mcp_server/**/*.html
-!nextcloud_mcp_server/auth/static/*

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

@@ -1,89 +0,0 @@
-name: Build and Publish Astrolabe App Release
-
-on:
-  push:
-    tags:
-      - 'astrolabe-v*'
-
-env:
-  APP_NAME: astrolabe
-  APP_DIR: third_party/astrolabe
-
-jobs:
-  build-and-publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - name: Get version from tag
-        id: tag
-        run: |
-          echo "TAG=${GITHUB_REF#refs/tags/astrolabe-v}" >> $GITHUB_OUTPUT
-
-      - name: Validate version in info.xml matches tag
-        working-directory: ${{ env.APP_DIR }}
-        run: |
-          INFO_VERSION=$(sed -n 's/.*<version>\(.*\)<\/version>.*/\1/p' appinfo/info.xml | tr -d '\t')
-          if [ "$INFO_VERSION" != "${{ steps.tag.outputs.TAG }}" ]; then
-            echo "Version mismatch: info.xml has $INFO_VERSION but tag is ${{ steps.tag.outputs.TAG }}"
-            exit 1
-          fi
-          echo "Version validated: $INFO_VERSION"
-
-      - name: Setup Node
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: 22
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # v2
-        with:
-          php-version: 8.1
-          coverage: none
-
-      - name: Checkout Nextcloud server (for signing)
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-        with:
-          repository: nextcloud/server
-          ref: stable30
-          path: server
-
-      - name: Install dependencies and build
-        working-directory: ${{ env.APP_DIR }}
-        run: |
-          composer install --no-dev --optimize-autoloader
-          npm ci
-          npm run build
-
-      - name: Setup signing certificate
-        run: |
-          mkdir -p $HOME/.nextcloud/certificates
-          echo "${{ secrets.APP_PRIVATE_KEY }}" > $HOME/.nextcloud/certificates/${{ env.APP_NAME }}.key
-          echo "${{ secrets.APP_PUBLIC_CRT }}" > $HOME/.nextcloud/certificates/${{ env.APP_NAME }}.crt
-
-      - name: Build app store package
-        working-directory: ${{ env.APP_DIR }}
-        run: make appstore server_dir=${{ github.workspace }}/server
-
-      - name: Create GitHub release and attach tarball
-        uses: svenstaro/upload-release-action@6b7fa9f267e90b50a19fef07b3596790bb941741 # v2
-        with:
-          repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: ${{ env.APP_DIR }}/build/artifacts/${{ env.APP_NAME }}.tar.gz
-          asset_name: ${{ env.APP_NAME }}-${{ steps.tag.outputs.TAG }}.tar.gz
-          tag: ${{ github.ref }}
-          release_name: Astrolabe ${{ steps.tag.outputs.TAG }}
-          prerelease: ${{ contains(steps.tag.outputs.TAG, '-alpha') || contains(steps.tag.outputs.TAG, '-beta') || contains(steps.tag.outputs.TAG, '-rc') }}
-
-      - name: Upload to Nextcloud App Store
-        uses: R0Wi/nextcloud-appstore-push-action@9244bb5445776688cfe90fa1903ea8dff95b0c28 # v1.0.4
-        with:
-          app_name: ${{ env.APP_NAME }}
-          appstore_token: ${{ secrets.APPSTORE_TOKEN }}
-          download_url: ${{ github.server_url }}/${{ github.repository }}/releases/download/${{ github.ref_name }}/${{ env.APP_NAME }}-${{ steps.tag.outputs.TAG }}.tar.gz
-          app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
-          nightly: ${{ contains(steps.tag.outputs.TAG, '-alpha') || contains(steps.tag.outputs.TAG, '-beta') || contains(steps.tag.outputs.TAG, '-rc') }}

.github/workflows/astroglobe-ci.yml

@@ -1,275 +0,0 @@
-# Consolidated CI workflow for Astroglobe Nextcloud app
-#
-# Runs on PRs that modify the astroglobe directory
-# Based on Nextcloud app skeleton workflows
-#
-# SPDX-FileCopyrightText: 2025 Nextcloud MCP Server contributors
-# SPDX-License-Identifier: MIT
-
-name: Astroglobe CI
-
-on:
-  pull_request:
-    paths:
-      - 'third_party/astroglobe/**'
-      - '.github/workflows/astroglobe-ci.yml'
-
-permissions:
-  contents: read
-
-concurrency:
-  group: astroglobe-ci-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  changes:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-    outputs:
-      frontend: ${{ steps.changes.outputs.frontend }}
-      php: ${{ steps.changes.outputs.php }}
-    steps:
-      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
-        id: changes
-        continue-on-error: true
-        with:
-          filters: |
-            frontend:
-              - 'third_party/astroglobe/src/**'
-              - 'third_party/astroglobe/package.json'
-              - 'third_party/astroglobe/package-lock.json'
-              - 'third_party/astroglobe/vite.config.js'
-              - 'third_party/astroglobe/**/*.js'
-              - 'third_party/astroglobe/**/*.ts'
-              - 'third_party/astroglobe/**/*.vue'
-            php:
-              - 'third_party/astroglobe/lib/**'
-              - 'third_party/astroglobe/appinfo/**'
-              - 'third_party/astroglobe/composer.json'
-              - 'third_party/astroglobe/psalm.xml'
-
-  # Node.js build and lint
-  node-build:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.frontend != 'false'
-    name: Node.js build
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Read package.json node and npm engines version
-        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
-        id: versions
-        with:
-          path: third_party/astroglobe
-          fallbackNode: '^20'
-          fallbackNpm: '^10'
-
-      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: ${{ steps.versions.outputs.nodeVersion }}
-
-      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
-        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
-
-      - name: Install dependencies & build
-        env:
-          CYPRESS_INSTALL_BINARY: 0
-          PUPPETEER_SKIP_DOWNLOAD: true
-        run: |
-          npm ci
-          npm run build --if-present
-
-      - name: Check webpack build changes
-        run: |
-          bash -c "[[ ! \"`git status --porcelain `\" ]] || (echo 'Please recompile and commit the assets' && exit 1)"
-
-  # ESLint
-  eslint:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.frontend != 'false'
-    name: ESLint
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Read package.json node and npm engines version
-        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
-        id: versions
-        with:
-          path: third_party/astroglobe
-          fallbackNode: '^20'
-          fallbackNpm: '^10'
-
-      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: ${{ steps.versions.outputs.nodeVersion }}
-
-      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
-        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
-
-      - name: Install dependencies
-        env:
-          CYPRESS_INSTALL_BINARY: 0
-          PUPPETEER_SKIP_DOWNLOAD: true
-        run: npm ci
-
-      - name: Lint
-        run: npm run lint
-
-  # Stylelint
-  stylelint:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.frontend != 'false'
-    name: Stylelint
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Read package.json node and npm engines version
-        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
-        id: versions
-        with:
-          path: third_party/astroglobe
-          fallbackNode: '^20'
-          fallbackNpm: '^10'
-
-      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: ${{ steps.versions.outputs.nodeVersion }}
-
-      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
-        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
-
-      - name: Install dependencies
-        env:
-          CYPRESS_INSTALL_BINARY: 0
-          PUPPETEER_SKIP_DOWNLOAD: true
-        run: npm ci
-
-      - name: Lint
-        run: npm run stylelint
-
-  # PHP Code Style
-  php-cs:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.php != 'false'
-    name: PHP CS Fixer
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Get php version
-        id: versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astroglobe/appinfo/info.xml
-
-      - name: Set up php${{ steps.versions.outputs.php-min }}
-        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
-        with:
-          php-version: ${{ steps.versions.outputs.php-min }}
-          extensions: bz2, ctype, curl, dom, fileinfo, gd, iconv, intl, json, libxml, mbstring, openssl, pcntl, posix, session, simplexml, xmlreader, xmlwriter, zip, zlib, sqlite, pdo_sqlite
-          coverage: none
-          ini-file: development
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install dependencies
-        run: |
-          composer remove nextcloud/ocp --dev || true
-          composer i
-
-      - name: Lint
-        run: composer run cs:check || ( echo 'Please run `composer run cs:fix` to format your code' && exit 1 )
-
-  # Psalm Static Analysis
-  psalm:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.php != 'false'
-    name: Psalm
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Get php version
-        id: versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astroglobe/appinfo/info.xml
-
-      - name: Set up php${{ steps.versions.outputs.php-min }}
-        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
-        with:
-          php-version: ${{ steps.versions.outputs.php-min }}
-          extensions: bz2, ctype, curl, dom, fileinfo, gd, iconv, intl, json, libxml, mbstring, openssl, pcntl, posix, session, simplexml, xmlreader, xmlwriter, zip, zlib, sqlite, pdo_sqlite
-          coverage: none
-          ini-file: development
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install dependencies
-        run: |
-          composer remove nextcloud/ocp --dev || true
-          composer i
-
-      - name: Get OCP version matrix
-        id: ocp-versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astroglobe/appinfo/info.xml
-
-      - name: Install OCP for static analysis
-        run: |
-          # Get first OCP version from matrix
-          OCP_VERSION=$(echo '${{ steps.ocp-versions.outputs.ocp-matrix }}' | jq -r '.include[0]."ocp-version"')
-          composer require --dev "nextcloud/ocp:$OCP_VERSION" --ignore-platform-reqs --with-dependencies
-
-      - name: Run Psalm
-        run: composer run psalm -- --threads=1 --monochrome --no-progress --output-format=github
-
-  # Summary job
-  summary:
-    permissions:
-      contents: none
-    runs-on: ubuntu-latest
-    needs: [changes, node-build, eslint, stylelint, php-cs, psalm]
-    if: always()
-    name: astroglobe-ci-summary
-    steps:
-      - name: Summary status
-        run: |
-          if ${{ needs.changes.outputs.frontend != 'false' && (needs.node-build.result != 'success' || needs.eslint.result != 'success' || needs.stylelint.result != 'success') }}; then
-            echo "Frontend checks failed"
-            exit 1
-          fi
-          if ${{ needs.changes.outputs.php != 'false' && (needs.php-cs.result != 'success' || needs.psalm.result != 'success') }}; then
-            echo "PHP checks failed"
-            exit 1
-          fi
-          echo "All checks passed"

.github/workflows/bump-version.yml

@@ -7,159 +7,26 @@ on:
 
 jobs:
   bump-version:
-    if: "!startsWith(github.event.head_commit.message, 'bump:') && !startsWith(github.event.head_commit.message, 'chore(release):')"
+    if: "!startsWith(github.event.head_commit.message, 'bump:')"
     runs-on: ubuntu-latest
-    name: "Bump version and create changelog for monorepo components"
+    name: "Bump version and create changelog with commitizen"
     permissions:
       contents: write
       packages: write
     steps:
       - name: Check out
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
         with:
           fetch-depth: 0
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+      - name: Create bump and changelog
+        uses: commitizen-tools/commitizen-action@9615e7be1cf341393c52e865ebbdaa0712176d81 # 0.25.0
         with:
-          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/astrolabe scopes)
-          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 or astrolabe
-          mcp_commit_count=$(git log "$commit_range" --oneline --grep="^(feat|fix|docs|refactor|perf|test|build|ci|chore)" -E | \
-            { grep -v "(helm)" || true; } | { grep -v "(astrolabe)" || true; } | wc -l)
-
-          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"
-          else
-            echo "No commits found for MCP server since $last_mcp_tag"
-          fi
-
-          # Bump Helm chart (scope: helm)
-          echo "Checking Helm chart for version bump..."
-          if has_commits_since_tag "nextcloud-mcp-server-" "(feat|fix|docs|refactor|perf|test|build|ci|chore)\(helm\)(!)?:"; then
-            echo "Bumping Helm chart version..."
-            ./scripts/bump-helm.sh
-            BUMPED_COMPONENTS="$BUMPED_COMPONENTS helm"
-          fi
-
-          # Bump Astrolabe (scope: astrolabe)
-          echo "Checking Astrolabe for version bump..."
-          if has_commits_since_tag "astrolabe-v" "(feat|fix|docs|refactor|perf|test|build|ci|chore)\(astrolabe\)(!)?:"; then
-            echo "Bumping Astrolabe version..."
-            ./scripts/bump-astrolabe.sh
-            BUMPED_COMPONENTS="$BUMPED_COMPONENTS astrolabe"
-          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
-                  ;;
-                astrolabe)
-                  tag=$(git tag --sort=-creatordate | grep -E '^astrolabe-v' | head -n 1)
-                  echo "- **Astrolabe**: \`$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_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 }}

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

@@ -1,57 +0,0 @@
-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@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code Review
-        id: claude-review
-        uses: anthropics/claude-code-action@7145c3e0510bcdbdd29f67cc4a8c1958f1acfa2f # v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          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

@@ -1,50 +0,0 @@
-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@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code
-        id: claude
-        uses: anthropics/claude-code-action@7145c3e0510bcdbdd29f67cc4a8c1958f1acfa2f # v1
-        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,8 +2,7 @@ name: Build and Publish Docker Image
 
 on:
   push:
-    tags:
-      - "v*"
+    tags: ["*"]
 
 jobs:
   build-and-push:
@@ -13,11 +12,11 @@ jobs:
       packages: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
+        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5
         with:
           # list of Docker images to use as base name for tags
           images: |
@@ -34,7 +33,7 @@ jobs:
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3
 
       - name: Log in to GitHub Container Registry
         if: github.event_name != 'pull_request'

.github/workflows/helm-release.yml

@@ -4,7 +4,6 @@ on:
   push:
     tags:
       - v*
-      - nextcloud-mcp-server-*
 
 jobs:
   release:
@@ -15,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
         with:
           fetch-depth: 0
 
@@ -39,8 +38,6 @@ 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

@@ -1,105 +0,0 @@
-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@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-
-      - name: Run docker compose with vector sync
-        uses: hoverkraft-tech/compose-action@248470ecc5ed40d8ed3d4480d8260d77179ef579 # v2.4.2
-        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@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
-
-      - 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
-        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@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
       - name: Install uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
       - 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@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
       - name: Check format
         run: |
           uv run --frozen ruff format --diff
@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           submodules: 'true'
 
@@ -35,7 +35,7 @@ jobs:
       ###### Required to build OIDC App ######
 
       - name: Set up php 8.4
-        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # v2
+        uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # v2
         with:
           php-version: 8.4
           coverage: none
@@ -48,32 +48,15 @@ jobs:
       ###### Required to build OIDC App ######
 
 
-      ###### Required to build Astrolabe App ######
-
-      - name: Set up Node.js for Astrolabe
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
-        with:
-          node-version: '20'
-
-      - name: Build Astrolabe app
-        run: |
-          cd third_party/astrolabe
-          composer install --no-dev --optimize-autoloader
-          npm ci
-          npm run build
-
-      ###### Required to build Astrolabe App ######
-
-
       - name: Run docker compose
-        uses: hoverkraft-tech/compose-action@248470ecc5ed40d8ed3d4480d8260d77179ef579 # v2.4.2
+        uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
         with:
           compose-file: "./docker-compose.yml"
           #compose-flags: "--profile qdrant"
           up-flags: "--build"
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
 
       - name: Install Playwright dependencies
         run: |
@@ -102,4 +85,4 @@ jobs:
           NEXTCLOUD_USERNAME: "admin"
           NEXTCLOUD_PASSWORD: "admin"
         run: |
-          uv run pytest -v --log-cli-level=WARN -m unit -m smoke
+          uv run pytest -v --log-cli-level=WARN -m smoke

.gitignore

@@ -13,6 +13,3 @@ docker-compose.override.yml
 # Generated by pytest used to login users
 .nextcloud_oauth_*.json
 .playwright-mcp/
-
-# RAG Evaluation
-tests/rag_evaluation/fixtures/

.gitmodules

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

CHANGELOG.md

@@ -1,459 +1,3 @@
-# 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.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
-
-- Improve vector visualization with static assets and fixes
-- Redesign UI to match Nextcloud ecosystem aesthetic
-
-### Fix
-
-- Improve 3D plot rendering with explicit dimensions and window resize support
-- Preserve 3D plot camera and improve documentation
-- Preserve 3D plot camera position and fix CSS loading
-
-## v0.43.0 (2025-11-18)
-
-### Feat
-
-- Replace custom document chunker with LangChain MarkdownTextSplitter
-
-## v0.42.0 (2025-11-17)
-
-### Feat
-
-- **viz**: Add dual-score display and improve UI controls
-
-## v0.41.0 (2025-11-17)
-
-### Feat
-
-- add configurable fusion algorithms for BM25 hybrid search
-- add chunk position tracking to vector indexing and search
-- add vector viz template and chunk context endpoint
-
-### Fix
-
-- prevent infinite loop in DocumentChunker with position tracking
-- Relax SearchResult validation to support DBSF fusion scores > 1.0
-
-## v0.40.0 (2025-11-16)
-
-### Feat
-
-- add unified provider architecture with Amazon Bedrock support
-
-### Fix
-
-- suppress Starlette middleware type warnings in ty checker
-
-## v0.39.0 (2025-11-16)
-
-### Feat
-
-- Implement BM25 hybrid search with native Qdrant RRF fusion
-
-### Fix
-
-- Handle named vectors in visualization and semantic search
-- Update vizApp to use bm25_hybrid algorithm and remove deprecated weights
-- Update viz routes to use BM25 hybrid search after refactor
-
-## v0.38.0 (2025-11-16)
-
-### Feat
-
-- add concurrent uploads and --force flag to upload command
-- implement RAG evaluation framework with CLI tooling
-
-### Fix
-
-- download qrels from BEIR ZIP instead of HuggingFace
-
-### Refactor
-
-- migrate asyncio to anyio for consistent structured concurrency
-- replace httpx client with NextcloudClient in upload command
-
-### Perf
-
-- Eliminate double-fetching in semantic search sampling
-- fix vector viz search performance and visual encoding
-- make note deletion concurrent in upload --force
-
 ## v0.37.0 (2025-11-16)
 
 ### Feat

CLAUDE.md

@@ -5,29 +5,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Coding Conventions
 
 ### async/await Patterns
-- **Use anyio for all async operations** - Provides structured concurrency
+- **Use anyio + asyncio hybrid** - Both libraries are available
   - pytest runs in `anyio` mode (`anyio_mode = "auto"` in pyproject.toml)
-  - Use `anyio.create_task_group()` for concurrent execution (NOT `asyncio.gather()`)
-  - Use `anyio.Lock()` for synchronization primitives (NOT `asyncio.Lock()`)
-  - Use `anyio.run()` for entry points (NOT `asyncio.run()`)
+  - asyncio used in auth modules (refresh_token_storage.py, token_exchange.py, token_broker.py)
+  - anyio used in calendar.py, client_registration.py, app.py
   - Prefer standard async/await syntax without explicit library imports when possible
-  - Examples: app.py, search/hybrid.py, search/verification.py, auth/token_broker.py
 
 ### Type Hints
 - **Use Python 3.10+ union syntax**: `str | None` instead of `Optional[str]`
 - **Use lowercase generics**: `dict[str, Any]` instead of `Dict[str, Any]`
 - **Type all function signatures** - Parameters and return types
-- **Type checker**: `ty` is configured for static type checking
-  ```bash
-  uv run ty check -- nextcloud_mcp_server
-  ```
+- **No explicit type checker configured** - Ruff handles linting only
 
 ### Code Quality
-- **Run ruff and ty before committing**:
+- **Run ruff before committing**:
   ```bash
   uv run ruff check
   uv run ruff format
-  uv run ty check -- nextcloud_mcp_server
   ```
 - **Ruff configuration** in pyproject.toml (extends select: ["I"] for import sorting)
 
@@ -56,127 +50,13 @@ 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
 - `nextcloud_mcp_server/auth/` - OAuth/OIDC authentication
 - `nextcloud_mcp_server/models/` - Pydantic response models
-- `nextcloud_mcp_server/providers/` - Unified LLM provider infrastructure (embeddings + generation)
 - `tests/` - Layered test suite (unit, smoke, integration, load)
 
-### Provider Architecture (ADR-015)
-
-**Unified Provider System** for embeddings and text generation:
-
-**Location:** `nextcloud_mcp_server/providers/`
-- `base.py` - `Provider` ABC with optional capabilities
-- `registry.py` - Auto-detection and factory pattern
-- `ollama.py` - Ollama provider (embeddings + generation)
-- `anthropic.py` - Anthropic provider (generation only)
-- `bedrock.py` - Amazon Bedrock provider (embeddings + generation)
-- `simple.py` - Simple in-memory provider (embeddings only, fallback)
-
-**Usage:**
-```python
-from nextcloud_mcp_server.providers import get_provider
-
-provider = get_provider()  # Auto-detects from environment
-
-# Check capabilities
-if provider.supports_embeddings:
-    embeddings = await provider.embed_batch(texts)
-
-if provider.supports_generation:
-    text = await provider.generate("prompt", max_tokens=500)
-```
-
-**Environment Variables:**
-
-Bedrock:
-- `AWS_REGION` - AWS region (e.g., "us-east-1")
-- `BEDROCK_EMBEDDING_MODEL` - Embedding model ID (e.g., "amazon.titan-embed-text-v2:0")
-- `BEDROCK_GENERATION_MODEL` - Generation model ID (e.g., "anthropic.claude-3-sonnet-20240229-v1:0")
-- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` - Optional, uses AWS credential chain
-
-Ollama:
-- `OLLAMA_BASE_URL` - API URL (e.g., "http://localhost:11434")
-- `OLLAMA_EMBEDDING_MODEL` - Embedding model (default: "nomic-embed-text")
-- `OLLAMA_GENERATION_MODEL` - Generation model (e.g., "llama3.2:1b")
-- `OLLAMA_VERIFY_SSL` - SSL verification (default: "true")
-
-Simple (fallback, no config needed):
-- `SIMPLE_EMBEDDING_DIMENSION` - Dimension (default: 384)
-
-**Auto-Detection Priority:** Bedrock → Ollama → Simple
-
-**Backward Compatibility:**
-- Old code using `nextcloud_mcp_server.embedding.get_embedding_service()` still works
-- `EmbeddingService` now wraps `get_provider()` internally
-
-**For Details:** See `docs/ADR-015-unified-provider-architecture.md`
-
 ## Development Commands (Quick Reference)
 
 ### Testing
@@ -506,29 +386,6 @@ 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

@@ -1,116 +0,0 @@
-# Contributing to Nextcloud MCP Server
-
-## Version Management
-
-This monorepo uses commitizen for version management with **independent versioning** for three 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` |
-| Astrolabe App | `astrolabe` | `./scripts/bump-astrolabe.sh` | `astrolabe-v0.2.0` |
-
-### 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
-
-# Astrolabe app changes
-feat(astrolabe): add dark mode toggle
-fix(astrolabe): resolve search UI bug
-```
-
-**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(astrolabe): add dark mode toggle"
-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
-
-# Bump Astrolabe (reads commits with scope=astrolabe)
-./scripts/bump-astrolabe.sh
-# → Creates tag: astrolabe-v0.2.0
-# → Updates: info.xml, package.json
-```
-
-#### 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
-- **Astrolabe**: `third_party/astrolabe/CHANGELOG.md` - includes `feat(astrolabe):` 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)
-- **Astrolabe**: Follows PEP 440, `major_version_zero = true` (0.x.x for alpha/beta)
-
-### 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,28 +1,17 @@
-FROM docker.io/library/python:3.12-slim-trixie@sha256:fa48eefe2146644c2308b909d6bb7651a768178f84fc9550dcd495e4d6d84d01
-
-COPY --from=ghcr.io/astral-sh/uv:0.9.18@sha256:5713fa8217f92b80223bc83aac7db36ec80a84437dbc0d04bbc659cae030d8c9 /uv /uvx /bin/
+FROM ghcr.io/astral-sh/uv:0.9.9-python3.11-alpine@sha256:0faa7934fac1db7f5056f159c1224d144bab864fd2677a4066d25a686ae32edd
 
 # 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
+RUN apk add --no-cache git sqlite
 
 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
+RUN uv sync --locked --no-dev --no-editable
 
 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", "run", "--host", "0.0.0.0"]
+ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "--host", "0.0.0.0"]

Dockerfile.smithery

@@ -1,44 +0,0 @@
-# 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:fa48eefe2146644c2308b909d6bb7651a768178f84fc9550dcd495e4d6d84d01
-
-WORKDIR /app
-
-# Install uv for fast dependency management
-COPY --from=ghcr.io/astral-sh/uv:0.9.18@sha256:5713fa8217f92b80223bc83aac7db36ec80a84437dbc0d04bbc659cae030d8c9 /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

@@ -1,11 +1,6 @@
-<p align="center">
-  <img src="astrolabe.svg" alt="Nextcloud MCP Server" width="128" height="128">
-</p>
-
 # 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.**
 
@@ -18,20 +13,7 @@ This is a **dedicated standalone MCP server** designed for external MCP clients
 
 ## Quick Start
 
-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:
+Get up and running in 60 seconds using Docker:
 
 ```bash
 # 1. Create a minimal configuration
@@ -47,15 +29,10 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
 
 # 3. Test the connection
 curl http://127.0.0.1:8000/health/ready
-
-# 4. Connect to the endpoint
-http://127.0.0.1:8000/sse
-
-# 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)
 
@@ -63,7 +40,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, Files, News items, and Deck cards (requires Qdrant + Ollama)
+- **Semantic Search (Experimental)** - Optional vector-powered search for Notes (requires Qdrant + Ollama)
 - **Document Processing** - OCR and text extraction from PDFs, DOCX, images with progress notifications
 - **Flexible Deployment** - Docker, Kubernetes (Helm), VM, or local installation
 - **Production-Ready Auth** - Basic Auth with app passwords (recommended) or OAuth2/OIDC (experimental)
@@ -81,7 +58,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, Files, News items, and Deck cards (experimental, opt-in, requires infrastructure) |
+| **Semantic Search** | 2+ | Vector search for Notes (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!
 
@@ -99,7 +76,7 @@ Want to see another Nextcloud app supported? [Open an issue](https://github.com/
 
 ### Authentication Modes
 
-The server supports three authentication modes:
+The server supports two authentication modes:
 
 **Single-User Mode (BasicAuth):**
 - One set of credentials shared by all MCP clients
@@ -113,12 +90,6 @@ The server supports three 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
@@ -133,7 +104,7 @@ This enables natural language queries and helps discover related content across
 
 > [!NOTE]
 > **Semantic Search is experimental and opt-in:**
-> - Disabled by default (`ENABLE_SEMANTIC_SEARCH=false`)
+> - Disabled by default (`VECTOR_SYNC_ENABLED=false`)
 > - Currently supports Notes app only (multi-app support planned)
 > - Requires additional infrastructure: vector database + embedding service
 > - Answer generation (`nc_semantic_search_answer`) requires MCP client sampling support
@@ -151,8 +122,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, 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
+- **[Semantic Search Architecture](docs/semantic-search-architecture.md)** - Experimental vector search (Notes only, opt-in)
 
 ### Advanced Topics
 - **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works (experimental)

alembic.ini

@@ -1,90 +0,0 @@
-# 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

@@ -1,71 +0,0 @@
-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

@@ -1,26 +0,0 @@
-"""${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,9 +3,3 @@
 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

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

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

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

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

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

astrolabe.svg

@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
-  <rect width="512" height="512" rx="80" ry="80" fill="#0082C9"/>
-  <path d="M255.9 21.04c-11.8 0-22.2 4.08-28.6 10.01-5.6 4.98-8.6 11.41-8.6 18.11 0 5.55 2.2 11.01 5.9 15.48-16.4 4.97-30.1 13.64-39 24.53 22.1-7.67 45.7-11.86 70.3-11.86 24.6 0 48.3 4.19 70.3 11.86-8.9-10.89-22.6-19.56-39-24.53 3.9-4.47 5.9-9.93 5.9-15.48 0-6.7-3-13.13-8.5-18.11-6.4-5.93-16.9-10.01-28.7-10.01zm0 20.34c5.3 0 10.1 1.27 13.6 3.52 1.7 1.16 3.4 2.43 3.4 4.27 0 1.76-1.7 3.03-3.4 4.19-3.5 2.33-8.3 3.61-13.6 3.61-5.3 0-10.1-1.28-13.6-3.61-1.6-1.16-3.3-2.43-3.3-4.19 0-1.84 1.7-3.11 3.3-4.27 3.5-2.25 8.3-3.52 13.6-3.52zm.1 48.1c-110.8 0-200.72 90.02-200.72 200.82S145.2 491 256 491s200.7-89.9 200.7-200.7c0-110.8-89.9-200.82-200.7-200.82zm0 32.62c92.9 0 168.2 75.3 168.2 168.2 0 92.8-75.3 168.2-168.2 168.2-92.9 0-168.26-75.4-168.26-168.2 0-92.9 75.36-168.2 168.26-168.2zm-8.2 6.3c-9.6.5-19 1.9-28.3 4.1l2.3 7.8c8.4-2 17.1-3.3 26-3.8v-8.1zm16.2 0v8.1c9 .5 17.7 1.8 26 3.8l2.2-7.8c-9.1-2.2-18.6-3.6-28.2-4.1zm-60 8.5c-9 3.2-17.6 7-25.8 11.6l4.1 7.1c7.7-4.3 15.6-7.9 23.9-10.8l-2.2-7.9zm103.7 0-2 7.9c8.4 2.9 16.2 6.5 23.8 10.8l4.2-7.1c-8.2-4.6-16.9-8.4-26-11.6zm-143.3 20.3c-7.5 5.4-14.6 11.4-21.1 17.9l5.8 5.8c5.9-6.1 12.5-11.7 19.5-16.6l-4.2-7.1zm182.9 0-4 7.1c6.9 4.9 13.5 10.5 19.5 16.6l5.7-5.8c-6.5-6.5-13.7-12.5-21.2-17.9zm-91.4 11.5c-37 0-67.4 28.6-70.3 64.9l15.9 4.7c.7-29.6 24.7-53.4 54.4-53.4 30.1 0 54.4 24.4 54.4 54.3 0 15-6.2 28.7-16 38.5l.1.1c1.7 2.7 3 5.6 4.1 8.6.9 3 1.7 5.7 2.3 8.6v.4c33.8-16.7 57.2-51.5 57.2-91.7 0-3.8-.2-7.3-.6-10.9-3.2-3.3-6.3-6.4-9.8-9.5 1.5 6.5 2.3 13.4 2.3 20.4 0 28.7-13 54.7-33.5 71.8 6.3-10.6 10.1-23 10.1-36.3 0-38.9-31.7-70.5-70.6-70.5zm-91.8 14.6c-3.3 3.1-6.5 6.2-9.7 9.5-.3 3.6-.5 7.1-.5 10.9 0 7.3.7 14.2 2.1 20.9l9.1 2.7c-2.1-7.5-3.1-15.4-3.1-23.6 0-7 .7-13.9 2.1-20.4zm-31.6 4c-5.8 7.1-10.9 14.6-15.4 22.6l7.1 4c4.1-7.4 8.8-14.3 14-20.8l-5.7-5.8zm246.8 0-5.7 5.8c5.3 6.5 10 13.4 13.9 20.8l7.1-4c-4.4-8-9.5-15.5-15.3-22.6zm-269.2 37.1c-2.5 5.7-4.6 11.4-6.4 17.6l.1-.3c3.4-5 7.9-9.3 12.9-12.5l.3-.6-6.9-4.2zm291.8 0-7.2 4.2c3.2 7.3 5.7 15.1 7.6 23.1l7.9-2.1c-2.1-8.8-4.9-17.3-8.3-25.2zm-261.2 11.5c-13.4.1-25.7 9-29.7 22.5l114.8 34.2c-4.9 16.7 4.6 34.2 21.2 39.2L361.7 366c16.6 5 34.1-4.4 39.1-21l-114.6-34.4c4.9-16.5-4.7-34.1-21.3-39.1 0 0-72.4-21.5-114.8-34.3-3.1-.9-6.3-1.4-9.4-1.3zm-42.09 29.7c-.9 6.9-1.4 14-1.4 21.3 0 1.3.1 2.9.1 4.2h8.09v-4.2c0-6.5.4-12.9 1.2-19.2l-7.99-2.1zm314.59 0-7.9 2.1c.7 6.3 1.3 12.7 1.3 19.2 0 1.3 0 2.9-.2 4.2h8.2v-4.2c0-7.3-.5-14.4-1.4-21.3zm-157.3 24.7c6.3 0 11.5 5 11.5 11.3 0 6.4-5.2 11.6-11.5 11.6s-11.5-5.2-11.5-11.6c0-6.3 5.2-11.3 11.5-11.3zM98.51 307.4c1 8.2 2.89 16.4 5.09 24.3l7.9-2.1c-2.1-7.2-3.8-14.6-4.8-22.2h-8.19zm306.69 0c-1.1 7.6-2.7 15-4.8 22.2l7.8 2.1c2.2-7.9 4.1-16.1 5.2-24.3h-8.2zm-191.3 10.9c-19 13.3-31.4 35.3-31.4 60.1 0 10.4 2.3 20.4 6.2 29.7 8.8 4.9 17.9 8.8 27.6 11.7-10.8-10.7-17.5-25.2-17.5-41.4 0-19 9.3-36 23.7-46.3-3.8-4.1-6.7-8.7-8.6-13.8zM116.8 345l-7.9 2c3.1 7.6 6.8 14.7 11 21.6l6.9-4.2c-3.8-6.2-7-12.8-10-19.4zm194.8 20.5c.9 4.1 1.4 8.5 1.4 12.9 0 16.2-6.7 30.7-17.4 41.4 9.6-2.9 18.8-6.8 27.5-11.7 4-9.3 6.2-19.3 6.2-29.7 0-2.7-.2-5.2-.4-7.7l-17.3-5.2zM136 377.9l-7.1 4.1c4.7 6.2 9.7 12.1 15.3 17.3l5.7-5.5c-5.1-5-9.7-10.3-13.9-15.9zm243.9 2.3-.2.1c-2.1.3-4 .6-6.2.7h-.1c-3.6 4.5-7.3 8.8-11.5 12.8l5.8 5.5c5.5-5.2 10.5-11.1 15.2-17.3l-3-1.8zm-217.8 24-5.9 5.9c6 4.8 12.2 9.7 18.8 13.6l3.8-7.8c-5.7-2.9-11.4-6.8-16.7-11.7zm187.7 0c-5.4 4.9-11.1 8.8-16.8 11.7l3.9 7.8c6.5-3.9 12.8-8.8 18.7-13.6l-5.8-5.9zm-156.4 19.5-4.1 6.8c6.6 4 13.7 5.8 20.7 8.8l2.2-7.9c-6.5-1.9-12.7-4.8-18.8-7.7zm125.2 0c-6.2 2.9-12.5 5.8-19.1 7.7l2.3 7.9c7.2-3 14-4.8 20.7-8.8l-3.9-6.8zm-90.7 11.7-2 7.8c7.1 1 14.5 1.9 21.9 1.9v-7.7c-6.8 0-13.5-1.1-19.9-2zm55.9 0c-6.3.9-13 2-19.8 2v7.7c7.5 0 14.8-.9 22.1-1.9l-2.3-7.8z" fill="#fff"/>
-</svg>

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

@@ -1,25 +0,0 @@
-[tool.commitizen]
-name = "cz_conventional_commits"
-version = "0.56.2"
-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/CHANGELOG.md

@@ -1,833 +0,0 @@
-# Changelog - Helm Chart
-
-All notable changes to the Helm chart 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 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-
-### Added
-- Initial independent versioning release
-- Support for Nextcloud MCP server deployment
-- Qdrant subchart integration
-- Ollama subchart integration
-- Configurable resource limits
-- Grafana dashboard annotations
-
-## nextcloud-mcp-server-0.56.2 (2025-12-29)
-
-### Fix
-
-- **oauth**: Enable browser OAuth routes for Management API in hybrid mode
-
-## nextcloud-mcp-server-0.56.1 (2025-12-26)
-
-### Fix
-
-- **mcp**: Move all imports to the top of modules
-
-## nextcloud-mcp-server-0.56.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
-
-## nextcloud-mcp-server-0.55.2 (2025-12-22)
-
-### Fix
-
-- **helm**: set OIDC client env vars when using existingSecret
-
-## nextcloud-mcp-server-0.55.1 (2025-12-22)
-
-### Fix
-
-- **helm**: trigger chart release workflow on helm chart tags
-
-## nextcloud-mcp-server-0.55.0 (2025-12-22)
-
-### BREAKING CHANGE
-
-- MCP server now bumps for ANY conventional commit except
-those explicitly scoped to helm or astrolabe.
-
-### Feat
-
-- **helm**: add support for multi-user BasicAuth mode
-- **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)
-- **auth**: add multi-user BasicAuth pass-through mode
-- **astrolabe**: add dynamic MCP server configuration for testing
-- **ci**: add --increment flag to bump scripts for manual version control
-
-### Fix
-
-- **helm**: address PR #447 reviewer feedback
-- **helm**: include MCP server version bumps in changelog pattern
-- **config**: address reviewer feedback
-- **astrolabe**: screenshots in info.xml
-- **astrolabe**: screenshots in info.xml
-- **astrolabe**: Update screenshots
-- **ci**: skip existing Helm chart releases to prevent duplicate release errors
-- **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
-- **ci**: push all tags explicitly in bump workflow
-- **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
-
-### Refactor
-
-- **config**: centralize configuration validation and simplify startup
-
-## nextcloud-mcp-server-0.54.0 (2025-12-19)
-
-### Feat
-
-- **ci**: implement monorepo-aware version bumping workflow
-- **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
-
-## nextcloud-mcp-server-0.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
-
-## nextcloud-mcp-server-0.52.1 (2025-12-13)
-
-## nextcloud-mcp-server-0.52.0 (2025-12-13)
-
-## nextcloud-mcp-server-0.51.0 (2025-12-13)
-
-### Feat
-
-- **vector**: add Deck card vector search with visualization support
-- **vector-viz**: add news_item support for links and chunk expansion
-
-### Perf
-
-- **deck**: optimize card lookup by storing board_id/stack_id in metadata
-
-## nextcloud-mcp-server-0.50.2 (2025-12-13)
-
-### Fix
-
-- **news**: revert get_item() to use get_items() + filter
-
-## nextcloud-mcp-server-0.50.1 (2025-12-12)
-
-### Fix
-
-- Disable DNS rebinding protection for containerized deployments
-- **deps**: update dependency mcp to >=1.23,<1.24
-
-## nextcloud-mcp-server-0.50.0 (2025-12-11)
-
-### Feat
-
-- add MCP tool annotations for enhanced UX
-
-### Fix
-
-- address PR review feedback
-
-## nextcloud-mcp-server-0.49.2 (2025-12-09)
-
-### Fix
-
-- Update lockfile
-
-## nextcloud-mcp-server-0.49.1 (2025-12-09)
-
-### Fix
-
-- Revert mcp version <1.23
-
-## nextcloud-mcp-server-0.49.0 (2025-12-08)
-
-### Fix
-
-- resolve all type checking errors (8 errors fixed)
-- **deps**: update dependency mcp to >=1.23,<1.24
-
-### Perf
-
-- **news**: use direct API endpoint for get_item()
-
-## nextcloud-mcp-server-0.48.5 (2025-11-28)
-
-### Feat
-
-- **news**: add Nextcloud News app integration
-
-### Fix
-
-- **deps**: update dependency pillow to v12
-
-### Refactor
-
-- **news**: simplify vector sync to fetch all items
-
-## nextcloud-mcp-server-0.48.4 (2025-11-23)
-
-### Fix
-
-- Add rate limit retry logic to OpenAI provider
-
-## nextcloud-mcp-server-0.48.3 (2025-11-23)
-
-### Fix
-
-- Increase MCP sampling timeout to 5 minutes for slower LLMs
-
-## nextcloud-mcp-server-0.48.2 (2025-11-23)
-
-### Fix
-
-- Share vector sync state with FastMCP session lifespan via module singleton
-
-## nextcloud-mcp-server-0.48.1 (2025-11-23)
-
-## nextcloud-mcp-server-0.48.0 (2025-11-23)
-
-## nextcloud-mcp-server-0.47.0 (2025-11-23)
-
-### Feat
-
-- Add tag management methods to WebDAV client
-- Add OpenAI provider support for embeddings and generation
-
-### Fix
-
-- Share vector sync state with FastMCP session lifespan via module singleton
-- 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
-
-## nextcloud-mcp-server-0.46.2 (2025-11-22)
-
-### Fix
-
-- **smithery**: Enable JSON response format for scanner compatibility
-
-## nextcloud-mcp-server-0.46.1 (2025-11-22)
-
-### Perf
-
-- Optimize vector viz search performance
-
-## nextcloud-mcp-server-0.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
-
-## nextcloud-mcp-server-0.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
-
-## nextcloud-mcp-server-0.44.1 (2025-11-21)
-
-### Fix
-
-- **deps**: update dependency mcp to >=1.22,<1.23
-
-## nextcloud-mcp-server-0.44.0 (2025-11-19)
-
-### Feat
-
-- Improve vector visualization with static assets and fixes
-- Redesign UI to match Nextcloud ecosystem aesthetic
-
-### Fix
-
-- Improve 3D plot rendering with explicit dimensions and window resize support
-- Preserve 3D plot camera and improve documentation
-- Preserve 3D plot camera position and fix CSS loading
-
-## nextcloud-mcp-server-0.43.0 (2025-11-18)
-
-### Feat
-
-- Replace custom document chunker with LangChain MarkdownTextSplitter
-
-## nextcloud-mcp-server-0.42.0 (2025-11-17)
-
-### Feat
-
-- **viz**: Add dual-score display and improve UI controls
-
-## nextcloud-mcp-server-0.41.0 (2025-11-17)
-
-### Feat
-
-- add configurable fusion algorithms for BM25 hybrid search
-- add chunk position tracking to vector indexing and search
-- add vector viz template and chunk context endpoint
-
-### Fix
-
-- prevent infinite loop in DocumentChunker with position tracking
-- Relax SearchResult validation to support DBSF fusion scores > 1.0
-
-## nextcloud-mcp-server-0.40.0 (2025-11-16)
-
-### Feat
-
-- add unified provider architecture with Amazon Bedrock support
-
-### Fix
-
-- suppress Starlette middleware type warnings in ty checker
-
-## nextcloud-mcp-server-0.39.0 (2025-11-16)
-
-## nextcloud-mcp-server-0.38.0 (2025-11-16)
-
-### Feat
-
-- add concurrent uploads and --force flag to upload command
-- implement RAG evaluation framework with CLI tooling
-- Add OpenTelemetry tracing to @instrument_tool decorator
-- Implement BM25 hybrid search with native Qdrant RRF fusion
-
-### Fix
-
-- download qrels from BEIR ZIP instead of HuggingFace
-- Handle named vectors in visualization and semantic search
-- Update vizApp to use bm25_hybrid algorithm and remove deprecated weights
-- Update viz routes to use BM25 hybrid search after refactor
-
-### Refactor
-
-- migrate asyncio to anyio for consistent structured concurrency
-- replace httpx client with NextcloudClient in upload command
-
-### Perf
-
-- Eliminate double-fetching in semantic search sampling
-- fix vector viz search performance and visual encoding
-- make note deletion concurrent in upload --force
-
-## nextcloud-mcp-server-0.36.0 (2025-11-15)
-
-### BREAKING CHANGE
-
-- Search algorithms now require Qdrant to be populated.
-Vector sync must be enabled and documents indexed for search to work.
-
-### Feat
-
-- Normalize hybrid search RRF scores to 0-1 range
-- Enhance vector visualization UI and parallelize search verification
-- Add Vector Viz tab to app home page
-- Add vector visualization pane with multi-select document types
-- Implement custom PCA to remove sklearn dependency
-- Add multi-document Protocol with cross-app search support
-- Update nc_semantic_search tool with algorithm selection
-- Implement unified search algorithm module
-
-### Fix
-
-- Reorder tabs and fix viz pane session access
-
-### Refactor
-
-- Optimize Nextcloud access verification with centralized filtering
-- Make all search algorithms query Qdrant payload, not Nextcloud
-
-### Perf
-
-- Exclude vector-sync status polling from distributed tracing
-
-## nextcloud-mcp-server-0.35.0 (2025-11-15)
-
-### Feat
-
-- Enable SSE transport for mcp service and update test fixtures
-
-## nextcloud-mcp-server-0.34.2 (2025-11-13)
-
-### Fix
-
-- Use NEXTCLOUD_OIDC_CLIENT_ID/SECRET env vars consistently
-- return all notes when search query is empty
-
-## nextcloud-mcp-server-0.34.0 (2025-11-13)
-
-### Feat
-
-- Complete Phase 5 - Instrument all 93 MCP tools
-- Add instrumentation decorator and apply to notes tools (Phase 5)
-- Add OAuth token and database metrics (Phases 3-4)
-- Add metrics instrumentation for queue, health, and database operations
-
-## nextcloud-mcp-server-0.33.1 (2025-11-13)
-
-### Fix
-
-- Move grafana_folder from labels to annotations
-
-## nextcloud-mcp-server-0.33.0 (2025-11-13)
-
-### Feat
-
-- Add Grafana dashboard and vector sync metric instrumentation
-
-## nextcloud-mcp-server-0.32.1 (2025-11-12)
-
-### Fix
-
-- add dynamic dimension detection for Ollama embedding models
-
-## nextcloud-mcp-server-0.32.0 (2025-11-11)
-
-### Feat
-
-- **ollama**: Pull model on startup if not available in ollama
-- add dynamic vector sync status updates with htmx polling
-- add webhook management UI and BeforeNodeDeletedEvent support
-- validate Nextcloud webhook schemas and document findings
-
-### Fix
-
-- improve webapp tab UI with CSS Grid and viewport-filling container
-
-### Refactor
-
-- move webapp from /user/page to /app
-- consolidate database storage for webhooks and OAuth tokens
-
-## nextcloud-mcp-server-0.31.1 (2025-11-10)
-
-### Refactor
-
-- simplify OpenTelemetry tracing configuration
-
-## nextcloud-mcp-server-0.31.0 (2025-11-10)
-
-### Feat
-
-- skip tracing for health and metrics endpoints
-
-### Fix
-
-- add retry logic for ETag conflicts in category change test
-- optimize Notes API pagination with pruneBefore parameter
-
-## nextcloud-mcp-server-0.30.0 (2025-11-10)
-
-### Feat
-
-- **helm**: Add document chunking configuration
-- **vector**: Add configurable chunk size and overlap for document embedding
-- **vector**: Support multiple embedding models with auto-generated collection names
-
-### Fix
-
-- Support in-memory Qdrant for CI testing
-
-## nextcloud-mcp-server-0.29.2 (2025-11-09)
-
-### Fix
-
-- **helm**: Set default strategy to Recreate
-
-## nextcloud-mcp-server-0.29.1 (2025-11-09)
-
-### Fix
-
-- **observability**: isolate metrics endpoint to dedicated port
-
-## nextcloud-mcp-server-0.29.0 (2025-11-09)
-
-### Feat
-
-- **helm**: Add observability support with ServiceMonitor and Grafana dashboard
-
-### Fix
-
-- **readiness**: Only check external Qdrant in network mode
-
-## nextcloud-mcp-server-0.28.0 (2025-11-09)
-
-### Feat
-
-- **observability**: Add comprehensive monitoring with Prometheus and OpenTelemetry
-
-### Fix
-
-- **vector**: Handle missing 'modified' field in notes gracefully
-
-## nextcloud-mcp-server-0.27.3 (2025-11-09)
-
-### Fix
-
-- **ci**: Use helm dependency build instead of update to use Chart.lock
-
-## nextcloud-mcp-server-0.27.2 (2025-11-09)
-
-### Fix
-
-- **helm**: update Qdrant dependency condition to match new mode structure
-
-## nextcloud-mcp-server-0.27.1 (2025-11-09)
-
-### Feat
-
-- **helm**: add Qdrant local mode support with three deployment options [skip ci]
-- add Qdrant local mode support with in-memory and persistent storage
-- implement ADR-009 - refactor semantic search to use generic semantic:read scope
-- implement MCP sampling for semantic search RAG (ADR-008)
-- add optional vector database and semantic search to helm chart
-- add vector sync processing status to /user/page endpoint
-- implement semantic search tool and fix vector sync issues (ADR-007 Phase 3)
-- implement vector sync scanner and processor (ADR-007 Phase 2)
-
-### Fix
-
-- **ci**: add Helm repository setup to chart release workflow
-- implement deletion grace period and vector sync status tool
-- remove unnecessary urllib3<2.0 constraint
-- integrate vector sync tasks with Starlette lifespan for streamable-http
-
-### Refactor
-
-- migrate vector sync from asyncio.Queue to anyio memory object streams
-- update to Qdrant query_points API and fix Playwright Keycloak login
-
-## nextcloud-mcp-server-0.26.1 (2025-11-08)
-
-### Fix
-
-- **deps**: update dependency mcp to >=1.21,<1.22
-
-## nextcloud-mcp-server-0.26.0 (2025-11-08)
-
-### Feat
-
-- add real elicitation integration test with python-sdk MCP client
-- unify session architecture and enhance login status visibility
-
-### Fix
-
-- Consolidate OAuth callbacks and implement PKCE for all flows
-
-## nextcloud-mcp-server-0.25.0 (2025-11-05)
-
-### BREAKING CHANGE
-
-- All OAuth deployments must be reconfigured to specify
-resource URIs (NEXTCLOUD_MCP_SERVER_URL and NEXTCLOUD_RESOURCE_URI) and
-choose between multi-audience or token exchange mode.
-
-### Feat
-
-- Implement ADR-005 unified token verifier to eliminate token passthrough vulnerability
-
-### Fix
-
-- Implement proper OAuth resource parameters and PRM-based discovery
-- Simplify token verifier to be RFC 7519 compliant
-- Use Keycloak client ID for NEXTCLOUD_RESOURCE_URI in token exchange
-- Correct OAuth token audience validation for multi-audience mode
-
-### Refactor
-
-- Eliminate duplicate validation logic in UnifiedTokenVerifier
-
-## nextcloud-mcp-server-0.24.1 (2025-11-04)
-
-### Fix
-
-- **deps**: update dependency mcp to >=1.20,<1.21
-
-## nextcloud-mcp-server-0.24.0 (2025-11-04)
-
-### Feat
-
-- add scope protection to OAuth provisioning tools
-- enable authorization services for token exchange in Keycloak
-- implement scope-based audience mapping and RFC 9728 support
-- integrate token exchange into MCP server application
-- implement RFC 8693 Standard Token Exchange for Keycloak
-- Add userinfo route/page
-- add browser-based user info page with separate OAuth flow
-- Implement ADR-004 Progressive Consent foundation (partial)
-- Complete ADR-004 Progressive Consent OAuth flows implementation
-- Implement ADR-004 Progressive Consent foundation components
-- Implement ADR-004 Hybrid Flow with comprehensive integration tests
-
-### Fix
-
-- add missing await for get_nextcloud_client in capabilities resource
-- use valid Fernet encryption keys in token exchange tests
-- accept resource URL in token audience for Nextcloud JWT tokens
-- remove token-exchange-nextcloud scope and accept tokens without audience
-- move audience mapper from scope to nextcloud-mcp-server client
-- move token-exchange-nextcloud from default to optional scopes
-- restructure routes to prevent SessionAuthBackend from interfering with FastMCP OAuth
-- allow OAuth Bearer tokens on /mcp endpoint by excluding from session auth
-- correct OAuth token audience validation using RFC 8707 resource parameter
-- remove remaining references to deleted oauth_callback and oauth_token
-- remove Hybrid Flow, make Progressive Consent default (ADR-004)
-- browser OAuth userinfo endpoint and refresh token rotation
-- make ENABLE_PROGRESSIVE_CONSENT consistently opt-in (default false)
-- make provisioning checks opt-in (default false)
-- Disable Progressive Consent for mcp-oauth to enable Hybrid Flow tests
-
-### Refactor
-
-- integrate token exchange into unified get_client() pattern
-
-## nextcloud-mcp-server-0.23.0 (2025-11-03)
-
-### Feat
-
-- Auto-configure impersonation role in Keycloak realm import
-- Implement dual-tier token exchange (Standard V2 + Legacy V1 impersonation)
-- Add Keycloak external IdP integration with custom scopes
-- Implement RFC 8693 token exchange for Keycloak (ADR-002 Tier 2)
-- Add Keycloak OAuth provider support with refresh token storage
-
-### Fix
-
-- Complete Keycloak external IdP integration with all tests passing
-- Complete Keycloak external IdP integration with all tests passing
-- Update DCR token_type tests for OIDC app changes
-
-### Refactor
-
-- Remove NEXTCLOUD_OIDC_CLIENT_STORAGE environment variable
-- Remove unnecessary user_oidc patch - CORSMiddleware patch is sufficient
-- Unify OAuth configuration to be provider-agnostic
-
-## nextcloud-mcp-server-0.22.7 (2025-10-29)
-
-### Fix
-
-- **helm**: Remove image tag overide
-
-## nextcloud-mcp-server-0.22.6 (2025-10-29)
-
-### Fix
-
-- **helm**: Update helm chart with extraArgs
-
-## nextcloud-mcp-server-0.22.5 (2025-10-29)
-
-### Fix
-
-- Update helm chart variables
-
-## nextcloud-mcp-server-0.22.4 (2025-10-29)
-
-### Fix
-
-- **helm**: Update helm version with release
-- **helm**: Update helm version with release
-- **helm**: Update helm version with release
-
-## nextcloud-mcp-server-0.1.1 (2025-10-29)
-
-### Fix
-
-- **helm**: Update helm version with release
-- Trigger release
-
-## nextcloud-mcp-server-0.1.0 (2025-10-29)
-
-### BREAKING CHANGE
-
-- FASTMCP_-prefixed env vars have been replaced by CLI
-arguments. Refer to the README for updated usage.
-
-### Feat
-
-- **server**: Add /live & /health endpoints
-- Initialize helm chart
-- Add text processing background worker for telling client about progress
-- **auth**: Add support for client registration deletion
-- Split read/write scopes into app:read/write scopes
-- Enable token introspection for opaque tokens
-- **server**: Add support for custom OIDC scopes and permissions via JWTs
-- Initialize JWT-scoped tools
-- **caldav**: Add support for tasks
-- **webdav**: Add search and list favorite response tools
-- **cookbook**: Add full Cookbook app support with 13 tools and 2 resources
-- Add Groups API client
-- add sharing API client and server tools
-- **server**: Experimental support for OAuth2/OIDC authentication
-- **users**: Initialize user API client
-- **server**: Add support for `streamable-http` transport type
-- Add WebDAV resource copy functionality
-- Add WebDAV resource move/rename functionality
-- **deck**: Add support for stack, cards, labels
-- **deck**: Initialize Deck app client/server
-- **cli**: Replace `mcp run` with click CLI and runtime options
-- **client**: Preserve fields when modifying contacts/calendar resources
-- **server**: Add structured output to all tool/resource output
-- **contacts**: Initialize Contacts App
-- **calendar**: add comprehensive Calendar app support via CalDAV protocol
-- Update webdav client create_directory method to handle recursive directories
-- **webdav**: add complete file system support
-- Add TablesClient and associated tools
-- Switch to using async client
-- **notes**: Add append to note functionality
-
-### Fix
-
-- Add support for RFC 7592 client registration and deletion
-- Update webdav models for proper serialization
-- **deps**: update dependency mcp to >=1.19,<1.20
-- Add CORS middleware to allow browser-based clients like MCP Inspector
-- Use occ-created OAuth clients with allowed_scopes for all tests
-- Separate OAuth fixtures for opaque vs JWT tokens
-- **caldav**: Fix caldav search() due to missing todos
-- **caldav**: Check that calendar exists after creation to avoid race condition
-- **caldav**: Properly parse datetimes as vDDDTypes
-- Increase HTTP client timeout to 30s
-- Handle RequestError in mcp tools
-- **deps**: update dependency mcp to >=1.18,<1.19
-- **deps**: update dependency pillow to v12
-- **oauth**: Remove the option to force_register new clients
-- Update user/groups API to OCS v2
-- **deps**: update dependency mcp to >=1.17,<1.18
-- **deps**: update dependency mcp to >=1.16,<1.17
-- **deps**: update dependency mcp to >=1.15,<1.16
-- **docker**: Provide --host 0.0.0.0 in default docker image
-- **deps**: update dependency mcp to >=1.13,<1.14
-- **server**: Replace ErrorResponses with standard McpErrors
-- **notes**: Include ETags in responses to avoid accidently updates
-- **notes**: Remove note contents from responses to reduce token usage
-- **model**: Serialize timestamps in RFC3339 format
-- **client**: Use paging to fetch all notes
-- **client**: Strip cookies from responses to avoid falsely raising CSRF errors
-- **calendar**: Fix iCalendar date vs datetime format
-- **calendar**: Remove try/except in calendar API
-- apply ruff formatting to pass CI checks
-- **calendar**: address PR feedback from maintainer
-- apply ruff formatting to test_webdav_operations.py
-- **deps**: update dependency mcp to >=1.10,<1.11
-- update tests
-- Commitizen release process
-- Do not update dependencies when running in Dockerfile
-- Configure logging
-- Limit search results to notes with score > 0.5
-- Install deps before checking service
-- **deps**: update dependency mcp to >=1.9,<1.10
-
-### Refactor
-
-- Transform document parsing into pluggable processor architecture
-- Update JWT client to use DCR, re-enable tool filtering
-- Migrate from internal CalendarClient to caldav library
-- Unify logging & remove factory deployment
-- Add tools for all resources to enable tool-only workflows
-- Add `http` to --transport option
-- Use _make_request where available
-- **calendar**: optimize logging for production readiness
-- Modularize NC and Notes app client
-
-### Perf
-
-- **notes**: Improve notes search performance using async iterators

charts/nextcloud-mcp-server/Chart.lock

@@ -1,9 +1,9 @@
 dependencies:
 - name: qdrant
   repository: https://qdrant.github.io/qdrant-helm
-  version: 1.16.3
+  version: 1.15.5
 - name: ollama
   repository: https://otwld.github.io/ollama-helm
-  version: 1.36.0
-digest: sha256:7f0979ec4110ff41ebeb55bf586b41366a350cc39fe65a2da7d2da03f723fe9b
-generated: "2025-12-22T11:09:39.166328543Z"
+  version: 1.34.0
+digest: sha256:d51c97d05be2614b751c0dd7267ef7dc959eff5ebef859c5f895c5c554b7a874
+generated: "2025-11-09T17:08:02.86648061Z"

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.56.2
-appVersion: "0.60.2"
+version: 0.37.0
+appVersion: "0.37.0"
 keywords:
   - nextcloud
   - mcp
@@ -27,10 +27,10 @@ annotations:
   grafana_dashboard_folder: "Nextcloud MCP"
 dependencies:
   - name: qdrant
-    version: "1.16.3"
+    version: "1.15.5"
     repository: https://qdrant.github.io/qdrant-helm
     condition: qdrant.networkMode.deploySubchart
   - name: ollama
-    version: "1.36.0"
+    version: "1.34.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 URL for browser-accessible OAuth authorization endpoint (OAuth only, optional) | Smart default** |
+| `nextcloud.publicIssuerUrl` | Public issuer URL for OAuth (OAuth only, optional) | Smart default** |
 
 **Smart Defaults:**
 - `*mcpServerUrl`: If not set, automatically uses ingress host (if enabled) or `http://localhost:8000` (for port-forward setups)
-- `**publicIssuerUrl`: If not set, 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
+- `**publicIssuerUrl`: If not set, automatically defaults to `nextcloud.host` (which works when both clients and MCP server access Nextcloud at the same URL)
 
 #### Authentication
 
@@ -208,16 +208,16 @@ The application exposes HTTP health check endpoints:
 
 #### Vector Search & Semantic Capabilities (Optional)
 
-Enable semantic search capabilities with BM25 hybrid search by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
+Enable semantic search capabilities by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
 
-**Semantic Search Configuration:**
+**Vector Sync Configuration:**
 
 | Parameter | Description | Default |
 |-----------|-------------|---------|
-| `semanticSearch.enabled` | Enable semantic search and background vector synchronization | `false` |
-| `semanticSearch.scanInterval` | Scan interval in seconds | `3600` |
-| `semanticSearch.processorWorkers` | Number of concurrent processor workers | `3` |
-| `semanticSearch.queueMaxSize` | Maximum queue size for pending documents | `10000` |
+| `vectorSync.enabled` | Enable background vector synchronization | `false` |
+| `vectorSync.scanInterval` | Scan interval in seconds | `3600` |
+| `vectorSync.processorWorkers` | Number of concurrent processor workers | `3` |
+| `vectorSync.queueMaxSize` | Maximum queue size for pending documents | `10000` |
 
 **Document Chunking Configuration:**
 
@@ -427,7 +427,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 (only used for browser-accessible auth endpoint)
+  # publicIssuerUrl defaults to nextcloud.host
 
 auth:
   mode: oauth
@@ -459,7 +459,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 (only used for browser-accessible auth endpoint)
+  # publicIssuerUrl will automatically default to nextcloud.host
 
 auth:
   mode: oauth
@@ -537,8 +537,8 @@ auth:
     username: admin
     password: secure-password
 
-# Enable semantic search
-semanticSearch:
+# Enable vector sync
+vectorSync:
   enabled: true
   scanInterval: 1800  # Scan every 30 minutes
   processorWorkers: 5
@@ -576,7 +576,7 @@ ollama:
 Or use an external Ollama instance:
 
 ```yaml
-semanticSearch:
+vectorSync:
   enabled: true
 
 qdrant:
@@ -592,7 +592,7 @@ ollama:
 Or use OpenAI for embeddings:
 
 ```yaml
-semanticSearch:
+vectorSync:
   enabled: true
 
 qdrant:
@@ -689,9 +689,7 @@ 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.semanticSearch.enabled }}
+{{- if .Values.vectorSync.enabled }}
 
-5. Semantic Search & Vector Capabilities:
-   - Semantic Search: Enabled
-   - Scan Interval: {{ .Values.semanticSearch.scanInterval }}s
-   - Processor Workers: {{ .Values.semanticSearch.processorWorkers }}
+5. Vector Search & Semantic Capabilities:
+   - Vector Sync: Enabled
+   - Scan Interval: {{ .Values.vectorSync.scanInterval }}s
+   - Processor Workers: {{ .Values.vectorSync.processorWorkers }}
    {{- if .Values.qdrant.enabled }}
    - Qdrant: Deployed as subchart ({{ .Release.Name }}-qdrant:6333)
    {{- else }}

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

@@ -72,28 +72,6 @@ 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
 */}}

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 (single-user)
+            # Basic auth mode
             - name: NEXTCLOUD_USERNAME
               valueFrom:
                 secretKeyRef:
@@ -79,41 +79,6 @@ 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
@@ -122,7 +87,7 @@ spec:
               value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
             - name: NEXTCLOUD_OIDC_SCOPES
               value: {{ .Values.auth.oauth.scopes | quote }}
-            {{- if or .Values.auth.oauth.clientId .Values.auth.oauth.existingSecret }}
+            {{- if .Values.auth.oauth.clientId }}
             - name: NEXTCLOUD_OIDC_CLIENT_ID
               valueFrom:
                 secretKeyRef:
@@ -182,16 +147,16 @@ spec:
               value: {{ .Values.documentProcessing.custom.types | quote }}
             {{- end }}
             {{- end }}
-            # Semantic Search (replaces deprecated VECTOR_SYNC_ENABLED)
-            - name: ENABLE_SEMANTIC_SEARCH
-              value: {{ .Values.semanticSearch.enabled | quote }}
-            {{- if .Values.semanticSearch.enabled }}
+            # Vector Sync
+            - name: VECTOR_SYNC_ENABLED
+              value: {{ .Values.vectorSync.enabled | quote }}
+            {{- if .Values.vectorSync.enabled }}
             - name: VECTOR_SYNC_SCAN_INTERVAL
-              value: {{ .Values.semanticSearch.scanInterval | quote }}
+              value: {{ .Values.vectorSync.scanInterval | quote }}
             - name: VECTOR_SYNC_PROCESSOR_WORKERS
-              value: {{ .Values.semanticSearch.processorWorkers | quote }}
+              value: {{ .Values.vectorSync.processorWorkers | quote }}
             - name: VECTOR_SYNC_QUEUE_MAX_SIZE
-              value: {{ .Values.semanticSearch.queueMaxSize | quote }}
+              value: {{ .Values.vectorSync.queueMaxSize | quote }}
             {{- end }}
             # Document Chunking (always set, used by vector sync processor)
             - name: DOCUMENT_CHUNK_SIZE
@@ -286,10 +251,6 @@ spec:
             - name: oauth-storage
               mountPath: /app/.oauth
             {{- end }}
-            {{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled }}
-            - name: token-storage
-              mountPath: /app/data
-            {{- end }}
             {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
             - name: qdrant-data
               mountPath: /app/data
@@ -305,11 +266,6 @@ spec:
           persistentVolumeClaim:
             claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
         {{- end }}
-        {{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled }}
-        - name: token-storage
-          persistentVolumeClaim:
-            claimName: {{ include "nextcloud-mcp-server.multiUserBasicPvcName" . }}
-        {{- end }}
         {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
         - name: qdrant-data
           persistentVolumeClaim:

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

@@ -16,24 +16,6 @@ spec:
       storage: {{ .Values.auth.oauth.persistence.size }}
 {{- end }}
 ---
-{{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled (not .Values.auth.multiUserBasic.persistence.existingClaim) }}
-apiVersion: v1
-kind: PersistentVolumeClaim
-metadata:
-  name: {{ include "nextcloud-mcp-server.fullname" . }}-token-storage
-  labels:
-    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
-spec:
-  accessModes:
-    - {{ .Values.auth.multiUserBasic.persistence.accessMode }}
-  {{- if .Values.auth.multiUserBasic.persistence.storageClass }}
-  storageClassName: {{ .Values.auth.multiUserBasic.persistence.storageClass }}
-  {{- end }}
-  resources:
-    requests:
-      storage: {{ .Values.auth.multiUserBasic.persistence.size }}
-{{- end }}
----
 {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled (not .Values.qdrant.localPersistence.existingClaim) }}
 apiVersion: v1
 kind: PersistentVolumeClaim

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

@@ -13,24 +13,6 @@ 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,29 +26,21 @@ nextcloud:
   # Example: https://mcp.example.com
   mcpServerUrl: ""
 
-  # 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)
+  # Public issuer URL for OAuth (OAuth mode only)
+  # If not specified, defaults to nextcloud.host
+  # Only set this if your Nextcloud is accessible at a different URL for OAuth
   # Example: https://cloud.example.com
   publicIssuerUrl: ""
 
 # Authentication configuration
-# Choose one mode: "basic", "multi-user-basic", or "oauth"
+# Choose either basic auth OR oauth (not both)
 auth:
-  # 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)
+  # Authentication mode: "basic" or "oauth"
+  # basic: Uses username/password (recommended for most users)
   # oauth: Uses OAuth2/OIDC (experimental, requires patches)
   mode: basic
 
-  # Basic authentication settings (single-user mode)
+  # Basic authentication settings
   basic:
     # Nextcloud username (ignored if existingSecret is set)
     username: ""
@@ -66,47 +58,6 @@ 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"
@@ -365,11 +316,10 @@ extraEnvFrom: []
 # - secretRef:
 #     name: my-secret
 
-# 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
+# Vector Sync Configuration
+# Background synchronization of Nextcloud content into vector database for semantic search
+vectorSync:
+  # Enable background vector synchronization
   enabled: false
   # Scan interval in seconds (how often to check for changes)
   scanInterval: 3600
@@ -380,7 +330,7 @@ semanticSearch:
 
 # Document Chunking Configuration
 # Controls how documents are split into chunks before embedding
-# Only relevant when semanticSearch.enabled is true
+# Only relevant when vectorSync.enabled is true
 documentChunking:
   # Number of words per chunk (default: 512)
   # Smaller chunks (256-384): Better for precise searches, more chunks to store

docker-compose.ci.yml

@@ -1,25 +0,0 @@
-# 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,13 +3,11 @@ 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:6b848cb24fbbd87429917f6c4422ac53c343e85692eb0fef86553e99e4f422f3
     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
@@ -19,14 +17,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:6cbef353e480a8a6e7f10ec545f13d7d3fa85a212cdcc5ffaf5a1c818b9d3798
+    image: docker.io/library/redis:alpine@sha256:28c9c4d7596949a24b183eaaab6455f8e5d55ecbf72d02ff5e2c17fe72671d31
     restart: always
 
   app:
-    image: docker.io/library/nextcloud:32.0.3@sha256:53231a9fb9233af2c15bfe70fc03ebe639fd53243fa42a9369884b1e0008deae
+    image: docker.io/library/nextcloud:32.0.1@sha256:5b043f7ea2f609d5ff5635f475c30d303bec17775a5c3f7fa435e3818e669120
     restart: always
     ports:
-      - 127.0.0.1:8080:80
+      - 0.0.0.0:8080:80
     depends_on:
       - redis
       - db
@@ -37,7 +35,6 @@ services:
       # 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/astrolabe:/opt/apps/astrolabe:ro
     environment:
       - NEXTCLOUD_TRUSTED_DOMAINS=app
       - NEXTCLOUD_ADMIN_USER=admin
@@ -54,7 +51,7 @@ services:
       retries: 30
 
   recipes:
-    image: docker.io/library/nginx:alpine@sha256:052b75ab72f690f33debaa51c7e08d9b969a0447a133eb2b99cc905d9188cb2b
+    image: docker.io/library/nginx:alpine@sha256:b3c656d55d7ad751196f21b7fd2e8d4da9cb430e32f646adcf92441b72f82b14
     restart: always
     volumes:
       - ./tests/fixtures/test_recipe.html:/usr/share/nginx/html/test_recipe.html:ro
@@ -73,13 +70,11 @@ services:
   mcp:
     build: .
     restart: always
-    command: ["--transport", "streamable-http"]
     depends_on:
       app:
         condition: service_healthy
     ports:
       - 127.0.0.1:8000:8000
-      - 127.0.0.1:9090:9090
     volumes:
       - mcp-data:/app/data
     environment:
@@ -89,8 +84,8 @@ services:
       - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
 
       # Vector sync configuration (ADR-007)
-      #- VECTOR_SYNC_ENABLED=true
-      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_ENABLED=true
+      - VECTOR_SYNC_SCAN_INTERVAL=10
       - VECTOR_SYNC_PROCESSOR_WORKERS=1
 
       #- LOG_FORMAT=json
@@ -125,41 +120,6 @@ 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_OFFLINE_ACCESS=true
-      - ENABLE_BACKGROUND_OPERATIONS=true
-
-      # Token storage (required for middleware initialization)
-      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
-      - TOKEN_STORAGE_DB=/app/data/tokens.db
-
-      - VECTOR_SYNC_ENABLED=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"]
@@ -180,8 +140,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
+      - ENABLE_OFFLINE_ACCESS=true
       - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
       - TOKEN_STORAGE_DB=/app/data/tokens.db
 
@@ -189,20 +148,6 @@ services:
       # Tokens must contain BOTH MCP and Nextcloud audiences
       # No token exchange needed - tokens work for both MCP auth and Nextcloud APIs
 
-      # Vector sync configuration (ADR-007)
-      - ENABLE_SEMANTIC_SEARCH=true
-      #- VECTOR_SYNC_ENABLED=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)
@@ -211,7 +156,7 @@ services:
       - oauth-tokens:/app/data
 
   keycloak:
-    image: quay.io/keycloak/keycloak:26.4.7@sha256:9409c59bdfb65dbffa20b11e6f18b8abb9281d480c7ca402f51ed3d5977e6007
+    image: quay.io/keycloak/keycloak:26.4.5@sha256:653852bfdea2be6e958b9e90a976eff1c6de34edd55f2f679bdc48ef16bc528e
     command:
       - "start-dev"
       - "--import-realm"
@@ -248,8 +193,8 @@ services:
       # Provider auto-detected from OIDC_DISCOVERY_URL issuer
       # Using internal Docker hostname for discovery to get consistent issuer
       - OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
-      - NEXTCLOUD_OIDC_CLIENT_ID=nextcloud-mcp-server
-      - NEXTCLOUD_OIDC_CLIENT_SECRET=mcp-secret-change-in-production
+      - OIDC_CLIENT_ID=nextcloud-mcp-server
+      - OIDC_CLIENT_SECRET=mcp-secret-change-in-production
       - OIDC_JWKS_URI=http://keycloak:8080/realms/nextcloud-mcp/protocol/openid-connect/certs
 
       # Nextcloud API endpoint (for accessing APIs with validated token)
@@ -259,8 +204,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
+      - ENABLE_OFFLINE_ACCESS=true
       - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
       - TOKEN_STORAGE_DB=/app/data/tokens.db
 
@@ -278,28 +222,8 @@ 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
-      - VECTOR_SYNC_ENABLED=false
-      - PORT=8081
-    profiles:
-      - smithery
-
   qdrant:
-    image: qdrant/qdrant:v1.16.2@sha256:dab6de32f7b2cc599985a7c764db3e8b062f70508fb85ca074aa856f829bf335
+    image: qdrant/qdrant:v1.15.5@sha256:0fb8897412abc81d1c0430a899b9a81eb8328aa634e7242d1bc804c1fe8fe863
     restart: always
     ports:
       - 127.0.0.1:6333:6333  # REST API
@@ -325,4 +249,3 @@ volumes:
   keycloak-oauth-storage:
   qdrant-data:
   mcp-data:
-  multi-user-basic-data:

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

@@ -1,8 +1,7 @@
 # ADR-011: Improving Semantic Search Quality Through Better Chunking and Embeddings
 
-**Status**: Partially Implemented (Chunking Complete, Embeddings Pending)
+**Status**: Proposed
 **Date**: 2025-11-12
-**Implementation Date**: 2025-11-18 (Chunking)
 **Authors**: Development Team
 **Related**: ADR-003 (Vector Database Architecture), ADR-008 (MCP Sampling for RAG)
 
@@ -894,50 +893,3 @@ This ADR addresses the root causes of poor semantic search recall:
 - No new infrastructure or ongoing costs
 
 **Next Steps**: Approve ADR → Implement changes → Reindex → Validate → Production rollout
-
-## Implementation Status
-
-### Completed (2025-11-18)
-
-**✅ Semantic Markdown-Aware Chunking (Option C1 + C3 Hybrid)**
-
-Implementation details:
-- Replaced custom word-based chunking with `MarkdownTextSplitter` from LangChain
-- Optimized for Nextcloud Notes markdown content with special handling for:
-  - Headers (`#`, `##`, `###`, etc.)
-  - Code blocks (` ``` `)
-  - Lists (`-`, `*`, `1.`)
-  - Horizontal rules (`---`)
-  - Paragraphs and sentences
-- Maintained `ChunkWithPosition` interface for backward compatibility
-- Updated configuration defaults:
-  - `DOCUMENT_CHUNK_SIZE`: 512 words → 2048 characters
-  - `DOCUMENT_CHUNK_OVERLAP`: 50 words → 200 characters
-- Updated unit tests to verify position tracking and boundary preservation
-- All tests passing with markdown-aware character-based chunking
-
-**Files Modified**:
-- `nextcloud_mcp_server/vector/document_chunker.py` - LangChain integration
-- `nextcloud_mcp_server/config.py` - Character-based defaults
-- `tests/unit/test_document_chunker.py` - Updated test suite
-
-**Dependencies Added**:
-- `langchain-text-splitters>=1.0.0` (already present in `pyproject.toml`)
-
-**Migration Required**:
-- ⚠️ Full reindex required to apply new chunking strategy
-- Existing documents in vector database use old word-based chunks
-- See "Migration Strategy" section above for reindexing process
-
-### Pending
-
-**⏳ Embedding Model Upgrade (Option E1)**
-
-Still to be implemented:
-- Switch from `nomic-embed-text` (768-dim) to `mxbai-embed-large-v1` (1024-dim)
-- Implement dynamic dimension detection in `ollama_provider.py`
-- Create migration script for collection reindexing
-- Run benchmarking to validate improvement
-- Deploy to production with atomic collection swap
-
-**Estimated Timeline**: 1-2 weeks for implementation and validation

docs/ADR-013-rag-evaluation.md

@@ -1,254 +0,0 @@
-## ADR-013: RAG Evaluation Testing Framework
-
-**Status:** Proposed
-
-**Date:** 2025-11-15
-
-### Context
-
-The `nc_semantic_search_answer` tool implements a Retrieval-Augmented Generation (RAG) system where:
-1. **Retrieval**: Vector sync pipeline indexes Nextcloud documents (notes, calendar, contacts, etc.) into a vector database
-2. **Generation**: MCP client's LLM synthesizes answers from retrieved documents via MCP sampling (ADR-008)
-
-We need a testing framework to evaluate RAG system performance and identify whether failures occur in retrieval (wrong documents found) or generation (poor answer quality). This framework must use industry-standard evaluation methodologies while remaining practical to implement and maintain.
-
-To establish a baseline, we will use the **BeIR/nfcorpus** dataset (medical/biomedical corpus) with ~5,000 documents and established query/answer pairs.
-
-Homepage: https://www.cl.uni-heidelberg.de/statnlpgroup/nfcorpus/
-Download: https://public.ukp.informatik.tu-darmstadt.de/thakur/BEIR/datasets/nfcorpus.zip
-
-### Decision
-
-We will implement a **two-part evaluation framework** that independently tests retrieval and generation quality using pytest fixtures.
-
-#### In Scope
-
-**1. Retrieval Evaluation**
-Tests the vector sync/embedding pipeline's ability to find relevant documents.
-
-- **Metric: Context Recall** (Did we retrieve documents containing the answer?)
-  - **Evaluation method**: Heuristic - Check if ground-truth document IDs appear in top-k retrieval results
-  - **Test**: Query → Semantic search → Assert expected doc IDs present
-
-**2. Generation Evaluation**
-Tests the MCP client LLM's ability to synthesize correct answers from retrieved context.
-
-- **Metric: Answer Correctness** (Is the generated answer factually correct?)
-  - **Evaluation method**: LLM-as-judge - Compare RAG answer against ground-truth answer
-  - **Test**: Query → `nc_semantic_search_answer` → LLM evaluates answer vs. ground truth (binary true/false)
-
-#### Out of Scope (Initial Implementation)
-
-- **Context Relevance/Precision**: Measuring irrelevant documents in retrieval results
-- **Faithfulness/Groundedness**: Detecting hallucinations not supported by retrieved context
-- **Answer Relevance**: Whether answer addresses the specific question asked
-- **Out-of-Scope Handling**: Testing "I don't know" responses when answer isn't in context
-- **Continuous benchmarking**: Automated tracking of metric trends over time
-- **Custom domain datasets**: Production-specific test data (medical corpus used initially)
-
-These remain valuable for future iterations but add complexity beyond our initial goals.
-
-#### Implementation
-
-**Test Structure**
-
-Location: `tests/rag_evaluation/`
-- `test_retrieval_quality.py` - Retrieval evaluation tests
-- `test_generation_quality.py` - Generation evaluation tests
-- `conftest.py` - Fixtures for test data, MCP clients, and evaluation LLMs
-
-**Required Pytest Fixtures**
-
-1. **`nfcorpus_test_data`** (session-scoped)
-   - Downloads/caches BeIR nfcorpus dataset at runtime
-   - Loads 5 pre-selected test queries with:
-     - Query text
-     - Pre-generated ground-truth answer (from `tests/rag_evaluation/fixtures/ground_truth.json`)
-     - Expected document IDs (from qrels with score=2)
-   - Uploads all corpus documents as notes in test Nextcloud instance
-   - Triggers vector sync to index documents
-   - Waits for indexing completion
-   - Returns test case data structure
-
-2. **`mcp_sampling_client`** (session-scoped)
-   - Creates MCP client that supports sampling
-   - Configurable LLM provider (ollama or anthropic) via environment:
-     - `RAG_EVAL_PROVIDER=ollama` (default) or `anthropic`
-     - `RAG_EVAL_OLLAMA_BASE_URL=http://localhost:11434`
-     - `RAG_EVAL_OLLAMA_MODEL=llama3.1:8b`
-     - `RAG_EVAL_ANTHROPIC_API_KEY=sk-...`
-     - `RAG_EVAL_ANTHROPIC_MODEL=claude-3-5-sonnet-20241022`
-   - Returns configured MCP client fixture
-
-3. **`evaluation_llm`** (session-scoped)
-   - Separate LLM instance for evaluation (independent from MCP client)
-   - Same provider configuration as `mcp_sampling_client`
-   - Returns callable: `async def evaluate(prompt: str) -> str`
-
-**Test Implementation Examples**
-
-```python
-# tests/rag_evaluation/test_retrieval_quality.py
-async def test_retrieval_recall(nc_client, nfcorpus_test_data):
-    """Test that semantic search retrieves documents containing the answer."""
-    for test_case in nfcorpus_test_data:
-        # Perform semantic search (retrieval only, no generation)
-        results = await nc_client.notes.semantic_search(
-            query=test_case.query,
-            limit=10
-        )
-
-        retrieved_doc_ids = {r.document_id for r in results}
-        expected_doc_ids = set(test_case.expected_document_ids)
-
-        # Context Recall: Are expected documents in top-k results?
-        recall = len(expected_doc_ids & retrieved_doc_ids) / len(expected_doc_ids)
-        assert recall >= 0.8, f"Recall {recall} below threshold for query: {test_case.query}"
-
-
-# tests/rag_evaluation/test_generation_quality.py
-async def test_answer_correctness(mcp_sampling_client, evaluation_llm, nfcorpus_test_data):
-    """Test that RAG system generates factually correct answers."""
-    for test_case in nfcorpus_test_data:
-        # Execute full RAG pipeline (retrieval + generation)
-        result = await mcp_sampling_client.call_tool(
-            "nc_semantic_search_answer",
-            arguments={"query": test_case.query, "limit": 5}
-        )
-
-        rag_answer = result["generated_answer"]
-
-        # LLM-as-judge evaluation
-        evaluation_prompt = f"""Compare these two answers and respond with only TRUE or FALSE.
-
-Question: {test_case.query}
-
-Generated Answer: {rag_answer}
-
-Ground Truth Answer: {test_case.ground_truth}
-
-Are these answers semantically equivalent (do they convey the same factual information)?
-Respond with only: TRUE or FALSE"""
-
-        evaluation_result = await evaluation_llm(evaluation_prompt)
-
-        assert evaluation_result.strip().upper() == "TRUE", \
-            f"Answer mismatch for query: {test_case.query}\nGot: {rag_answer}\nExpected: {test_case.ground_truth}"
-```
-
-**Dataset Integration**
-
-The BeIR nfcorpus dataset structure:
-- **corpus.jsonl**: 3,633 medical/biomedical documents (articles from PubMed)
-- **queries.jsonl**: 3,237 queries (questions)
-- **qrels/*.tsv**: Relevance judgments mapping query IDs to document IDs with scores (2=highly relevant, 1=somewhat relevant)
-
-**Important**: The dataset provides relevance judgments (which documents answer which queries) but does NOT include ground truth answers. We must generate synthetic ground truth offline.
-
-**Selected Test Queries** (5 diverse candidates):
-
-1. **PLAIN-2630**: "Alkylphenol Endocrine Disruptors and Allergies" (5 words, 21 highly relevant docs)
-2. **PLAIN-2660**: "How Long to Detox From Fish Before Pregnancy?" (8 words, 20 highly relevant docs)
-3. **PLAIN-2510**: "Coffee and Artery Function" (4 words, 16 highly relevant docs)
-4. **PLAIN-2430**: "Preventing Brain Loss with B Vitamins?" (6 words, 15 highly relevant docs)
-5. **PLAIN-2690**: "Chronic Headaches and Pork Tapeworms" (5 words, 14 highly relevant docs)
-
-**Ground Truth Generation** (offline, pre-test):
-
-Ground truth answers will be generated offline using a script that:
-1. Loads nfcorpus dataset
-2. For each selected query, extracts top 3-5 highly relevant documents
-3. Uses an LLM (ollama/anthropic) to synthesize a reference answer
-4. Stores ground truth in `tests/rag_evaluation/fixtures/ground_truth.json`
-
-```python
-# tools/generate_rag_ground_truth.py
-async def generate_ground_truth(query: str, relevant_docs: List[dict], llm: LLMProvider) -> str:
-    """Generate synthetic ground truth answer from highly relevant documents."""
-    context = "\n\n".join([
-        f"Document {i+1}:\nTitle: {doc['title']}\n{doc['text']}"
-        for i, doc in enumerate(relevant_docs[:5])
-    ])
-
-    prompt = f"""Based on the following documents, provide a comprehensive answer to this question:
-
-Question: {query}
-
-{context}
-
-Provide a factual, well-structured answer that synthesizes information from the documents.
-Focus on accuracy and completeness."""
-
-    return await llm.generate(prompt, max_tokens=500)
-```
-
-**Dataset Loading at Test Runtime** (in `nfcorpus_test_data` fixture):
-
-1. Download nfcorpus dataset (cached in pytest temp directory)
-2. Load corpus, queries, and qrels (relevance judgments)
-3. Load pre-generated ground truth from `tests/rag_evaluation/fixtures/ground_truth.json`
-4. Upload all corpus documents as Nextcloud notes
-5. Trigger vector sync to index documents
-6. Wait for indexing completion
-7. Return test cases with query, ground truth, and expected doc IDs
-
-**LLM Provider Abstraction**
-
-```python
-# tests/rag_evaluation/llm_providers.py
-class LLMProvider(Protocol):
-    async def generate(self, prompt: str, max_tokens: int = 100) -> str: ...
-
-class OllamaProvider:
-    def __init__(self, base_url: str, model: str):
-        self.base_url = base_url
-        self.model = model
-
-    async def generate(self, prompt: str, max_tokens: int = 100) -> str:
-        # Use httpx to call Ollama API
-        ...
-
-class AnthropicProvider:
-    def __init__(self, api_key: str, model: str):
-        self.client = anthropic.AsyncAnthropic(api_key=api_key)
-        self.model = model
-
-    async def generate(self, prompt: str, max_tokens: int = 100) -> str:
-        message = await self.client.messages.create(
-            model=self.model,
-            max_tokens=max_tokens,
-            messages=[{"role": "user", "content": prompt}]
-        )
-        return message.content[0].text
-```
-
-### Consequences
-
-**Positive:**
-
-* **Actionable debugging**: Separate retrieval/generation tests pinpoint failure location
-* **Industry-standard metrics**: Context Recall and Answer Correctness are recognized RAG evaluation metrics
-* **Simple initial implementation**: Binary LLM evaluation (true/false) is straightforward to implement and interpret
-* **Extensible framework**: Easy to add more metrics (faithfulness, relevance) later
-* **Standardized benchmark**: nfcorpus provides objective comparison against published RAG systems
-* **Hybrid evaluation**: Combines efficiency (heuristics for retrieval) with quality (LLM-as-judge for generation)
-* **Provider flexibility**: Supports both local (Ollama) and cloud (Anthropic) LLM evaluation
-
-**Negative:**
-
-* **Medical domain bias**: nfcorpus is medical/biomedical content, may not represent production use cases (personal notes, calendar events, etc.)
-* **Manual test execution**: Tests require external LLM access and are not integrated into CI pipeline
-* **Limited initial coverage**: Starting with only 5 queries provides limited statistical confidence
-* **Evaluation cost**: LLM-as-judge for generation evaluation incurs API costs (Anthropic) or requires local inference (Ollama)
-* **Single metric per component**: Initial scope tests only one metric per component, missing other important quality dimensions
-* **Synthetic ground truth**: Ground truth answers are LLM-generated, not human-validated, which may introduce evaluation bias
-* **Large corpus upload**: Uploading 3,633 documents at test runtime may be slow; caching strategy needed
-
-**Future Work:**
-
-* Expand to 50-100 queries for statistical significance
-* Add custom test dataset with production-representative documents (meeting notes, task lists, etc.)
-* Implement additional metrics (faithfulness, context relevance, answer relevance)
-* Create automated benchmarking dashboard to track metric trends
-* Test multi-hop reasoning (synthesis questions requiring multiple documents)
-* Evaluate out-of-scope handling ("I don't know" responses)

docs/ADR-014-bm25-search.md

@@ -1,241 +0,0 @@
-# ADR-014: Replace Custom Keyword Search with BM25 Hybrid Search via Qdrant
-
-**Date:** 2025-11-16
-
-**Status:** Implemented
-
----
-
-### 1. Context
-
-Our RAG application currently employs two separate retrieval mechanisms:
-1.  **Dense (Semantic) Search:** Using vector embeddings stored in our Qdrant database to find semantically similar context.
-2.  **Keyword Search:** A custom-built fuzzy/character-based search to match-specific keywords, acronyms, and product codes that semantic search often misses.
-
-This dual-system approach has several drawbacks:
-* **Poor Relevance:** Our current keyword search is basic (e.g., `LIKE` queries or simple fuzzy matching). It is not as effective as modern full-text search algorithms like BM25.
-* **Clunky Fusion:** We lack a robust, principled method to combine the results from the two systems. This leads to disjointed logic in the application layer and suboptimal context being passed to the LLM.
-* **Architectural Complexity:** We must maintain two separate search pathways (one to Qdrant, one to the keyword search mechanism), increasing code complexity and maintenance overhead.
-
-Our vector database, **Qdrant**, natively supports **hybrid search** by combining dense vectors with BM25-based **sparse vectors** in a single collection.
-
-### 2. Decision
-
-We will **deprecate and remove** the existing custom keyword/fuzzy search functionality.
-
-We will **replace it by implementing native hybrid search within Qdrant**. This involves:
-1.  **Modifying the Qdrant Collection:** Updating our collection to support a named sparse vector index configured for BM25.
-2.  **Updating the Ingestion Pipeline:** For every document chunk, we will generate and upsert *both*:
-    * Its **dense vector** (from our existing embedding model).
-    * Its **sparse vector** (generated using a BM25-compatible model, e.g., `Qdrant/bm25` from `fastembed`).
-3.  **Refactoring Retrieval Logic:** All retrieval calls will be consolidated into a single Qdrant query using the `query_points` endpoint. This query will use the `prefetch` parameter to execute both dense and sparse searches, and Qdrant's built-in **Reciprocal Rank Fusion (RRF)** to automatically merge the results into a single, relevance-ranked list.
-4.  **Backfilling:** A one-time migration script will be created to generate and add sparse vectors for all existing documents in the Qdrant collection.
-
----
-
-### 3. Considered Options
-
-#### Option 1: Native Qdrant Hybrid Search (Chosen)
-* Use Qdrant's built-in sparse vector and RRF capabilities.
-* **Pros:**
-    * **Consolidated Architecture:** Manages both dense and sparse indexes in one database.
-    * **No Data Sync Issues:** Updates are atomic. A single `upsert` updates both representations.
-    * **Built-in Fusion:** RRF is handled natively and efficiently by the database.
-    * **Superior Relevance:** Replaces our brittle custom search with the industry-standard BM25.
-* **Cons:**
-    * Requires a one-time data backfill which may be time-consuming.
-    * Adds a new step (sparse vector generation) to the ingestion pipeline.
-
-#### Option 2: External Full-Text Search (e.g., Elasticsearch)
-* Keep Qdrant for dense search and add a separate Elasticsearch/OpenSearch cluster for BM25.
-* **Pros:**
-    * Provides a very powerful, dedicated full-text search engine.
-* **Cons:**
-    * **High Complexity:** Introduces a new, stateful service to deploy, manage, and scale.
-    * **Data Sync Nightmare:** We would be responsible for ensuring that the document IDs and content in Qdrant and Elasticsearch are always perfectly synchronized. This is a major source of bugs.
-    * **Manual Fusion:** The application would have to query both systems and perform RRF manually.
-
-#### Option 3: Keep Current System
-* Make no changes.
-* **Pros:**
-    * No engineering effort required.
-* **Cons:**
-    * Fails to address the known relevance and architectural problems.
-    * Our RAG application's performance will remain suboptimal, especially for keyword-sensitive queries.
-
----
-
-### 4. Rationale
-
-**Option 1 is the clear winner.** It directly solves our primary problem (poor keyword matching) by adopting the industry-standard BM25.
-
-Critically, it achieves this while **simplifying** our overall architecture, not complicating it. By leveraging features already present in our existing database (Qdrant), we avoid the massive operational and synchronization overhead of adding a second search system (Option 2).
-
-This decision consolidates our retrieval logic, eliminates the data consistency problem, and moves the complex fusion logic (RRF) from the application layer into the database, where it can be performed more efficiently.
-
-### 5. Consequences
-
-**New Work:**
-* **Ingestion:** The data ingestion pipeline must be updated to add the `fastembed` library (or similar), generate sparse vectors, and upsert them to the new named vector field in Qdrant.
-* **Retrieval:** The application's retrieval service must be refactored to use the `query_points` endpoint with `prefetch` and `fusion=models.Fusion.RRF`.
-* **Migration:** A one-time backfill script must be written and executed to add sparse vectors for all existing documents.
-* **Infrastructure:** The Qdrant collection schema must be updated (or re-created) to add the `sparse_vectors_config`.
-
-**Positive:**
-* **Improved Accuracy:** Retrieval will be significantly more accurate, handling both semantic and keyword queries robustly.
-* **Simplified Code:** The application's retrieval logic will be cleaner and simpler, with one endpoint instead of two.
-* **Reduced Maintenance:** We will remove the custom fuzzy-search code, which is brittle and difficult to maintain.
-
-**Negative:**
-* The data backfill process will require careful management to avoid downtime.
-* Ingestion time will slightly increase due to the extra step of sparse vector generation. This is considered a negligible trade-off for the gains in relevance.
-
----
-
-### 6. Implementation Notes
-
-**Implementation completed on 2025-11-16**
-
-**Key Changes:**
-
-1. **Dependencies** (pyproject.toml:25):
-   - Added `fastembed>=0.4.2` for BM25 sparse vector embeddings
-   - Adjusted `pillow` version constraint to be compatible with fastembed
-
-2. **Qdrant Collection Schema** (nextcloud_mcp_server/vector/qdrant_client.py:113-128):
-   - Updated to named vectors: `{"dense": VectorParams(...), "sparse": SparseVectorParams(...)}`
-   - Added sparse vector configuration with BM25 index
-   - Maintains backward compatibility with existing collections (detects legacy schema)
-
-3. **BM25 Embedding Provider** (nextcloud_mcp_server/embedding/bm25_provider.py):
-   - Created `BM25SparseEmbeddingProvider` using FastEmbed's `Qdrant/bm25` model
-   - Implements `encode()` and `encode_batch()` methods
-   - Returns sparse vectors as `{indices: list[int], values: list[float]}` format
-
-4. **Document Indexing Pipeline** (nextcloud_mcp_server/vector/processor.py:229-255):
-   - Generates both dense (semantic) and sparse (BM25) embeddings for each document chunk
-   - Updates `PointStruct` to use named vectors: `vector={"dense": ..., "sparse": ...}`
-   - Maintains same chunking strategy (512 words, 50-word overlap)
-
-5. **BM25 Hybrid Search Algorithm** (nextcloud_mcp_server/search/bm25_hybrid.py):
-   - Implements `BM25HybridSearchAlgorithm` using Qdrant's native RRF fusion
-   - Uses `prefetch` parameter for parallel dense + sparse search
-   - Applies `fusion=models.Fusion.RRF` for automatic result merging
-   - Maintains same deduplication and filtering logic as semantic search
-
-6. **MCP Tool Updates** (nextcloud_mcp_server/server/semantic.py:39-68):
-   - Simplified `nc_semantic_search()` to use BM25 hybrid only
-   - Removed `algorithm`, `semantic_weight`, `keyword_weight`, `fuzzy_weight` parameters
-   - Updated default `score_threshold=0.0` for RRF scoring
-   - Returns `search_method="bm25_hybrid"` in responses
-
-7. **Legacy Algorithm Removal**:
-   - Deleted `nextcloud_mcp_server/search/keyword.py` (278 lines)
-   - Deleted `nextcloud_mcp_server/search/fuzzy.py` (220 lines)
-   - Deleted `nextcloud_mcp_server/search/hybrid.py` (238 lines - custom RRF)
-   - Updated `nextcloud_mcp_server/search/__init__.py` to export only BM25 hybrid
-
-**Migration Strategy:**
-- No migration required (vector sync feature is experimental)
-- New documents automatically indexed with both dense + sparse vectors
-- Collection re-creation on first startup with updated schema
-
-**Test Results:**
-- All unit tests passing (118 passed)
-- All integration tests passing (7 semantic search tests)
-- Code formatting verified with ruff
-
-**Benefits Realized:**
-- ✅ Consolidated architecture (single Qdrant database for both dense + sparse)
-- ✅ Native fusion algorithms (database-level, more efficient)
-- ✅ Industry-standard BM25 (replaces custom keyword search)
-- ✅ Simplified codebase (removed 736 lines of legacy code)
-- ✅ Better relevance (handles both semantic and keyword queries)
-- ✅ Configurable fusion methods (RRF and DBSF)
-
----
-
-### 7. Fusion Algorithm Options
-
-**Update: 2025-11-16**
-
-The BM25 hybrid search now supports two fusion algorithms for combining dense (semantic) and sparse (BM25) search results:
-
-#### Reciprocal Rank Fusion (RRF)
-
-**Default fusion method.** RRF is a widely-used, well-established algorithm that combines rankings from multiple retrieval systems using the reciprocal rank formula:
-
-```
-RRF(doc) = Σ 1/(k + rank_i(doc))
-```
-
-where `k` is a constant (typically 60) and `rank_i(doc)` is the rank of the document in retrieval system `i`.
-
-**Characteristics:**
-- ✅ **General-purpose**: Works well across diverse query types and document collections
-- ✅ **Rank-based**: Focuses on relative rankings rather than absolute scores
-- ✅ **Established**: Well-tested, documented, and understood in IR literature
-- ✅ **Robust**: Less sensitive to score distribution differences between systems
-
-**When to use RRF:**
-- Default choice for most use cases
-- When you have mixed query types (semantic + keyword)
-- When retrieval systems have very different score ranges
-- When you want predictable, well-understood behavior
-
-#### Distribution-Based Score Fusion (DBSF)
-
-**Alternative fusion method.** DBSF normalizes scores from each retrieval system using distribution statistics before combining them:
-
-1. **Normalization**: For each query, calculates mean (μ) and standard deviation (σ) of scores
-2. **Outlier handling**: Uses μ ± 3σ as normalization bounds
-3. **Fusion**: Sums normalized scores across systems
-
-**Characteristics:**
-- ✅ **Score-aware**: Uses actual relevance scores, not just rankings
-- ✅ **Statistical**: Normalizes based on score distribution properties
-- ⚠️ **Experimental**: Newer algorithm, less battle-tested than RRF
-- ⚠️ **Sensitive**: May behave differently depending on score distributions
-
-**When to use DBSF:**
-- When retrieval systems have vastly different score ranges that RRF doesn't balance well
-- When you want to experiment with score-based (vs rank-based) fusion
-- When statistical normalization better matches your use case
-- For A/B testing against RRF to measure retrieval quality improvements
-
-#### Configuration
-
-Both fusion algorithms are exposed via the `fusion` parameter in MCP tools:
-
-```python
-# Use RRF (default)
-response = await nc_semantic_search(
-    query="async programming",
-    fusion="rrf"  # Can be omitted, RRF is default
-)
-
-# Use DBSF
-response = await nc_semantic_search(
-    query="async programming",
-    fusion="dbsf"
-)
-```
-
-The `nc_semantic_search_answer` tool also supports the `fusion` parameter and passes it through to the underlying search.
-
-#### Future: Configurable Weights
-
-**Current limitation**: Neither RRF nor DBSF currently support per-system weights (e.g., 0.8 for semantic, 0.2 for BM25). This is a Qdrant platform limitation tracked in [qdrant/qdrant#6067](https://github.com/qdrant/qdrant/issues/6067).
-
-When Qdrant adds weight support, the `fusion` parameter can be extended to accept weight configurations:
-
-```python
-# Hypothetical future API
-response = await nc_semantic_search(
-    query="async programming",
-    fusion="rrf",
-    fusion_weights={"dense": 0.7, "sparse": 0.3}  # Not yet implemented
-)
-```
-
-**Recommendation**: Start with RRF (default). If you encounter cases where keyword matches are under- or over-weighted, experiment with DBSF. Monitor [qdrant/qdrant#6067](https://github.com/qdrant/qdrant/issues/6067) for configurable weight support.

docs/ADR-015-unified-provider-architecture.md

@@ -1,380 +0,0 @@
-# ADR-015: Unified Provider Architecture for Embeddings and Text Generation
-
-**Status:** Accepted
-**Date:** 2025-01-16
-**Deciders:** Development Team
-**Related:** ADR-003 (Vector Database), ADR-008 (MCP Sampling), ADR-013 (RAG Evaluation)
-
-## Context
-
-Prior to this refactoring, the codebase had two separate provider systems:
-
-1. **Embedding Providers** (`nextcloud_mcp_server/embedding/`)
-   - Used `EmbeddingProvider` ABC with methods: `embed()`, `embed_batch()`, `get_dimension()`
-   - Had auto-detection via `EmbeddingService._detect_provider()`
-   - Used for semantic search and vector indexing (production)
-
-2. **LLM Providers** (`tests/rag_evaluation/llm_providers.py`)
-   - Used `LLMProvider` Protocol with method: `generate()`
-   - Had separate factory function `create_llm_provider()`
-   - Used only for RAG evaluation tests (not production)
-
-This fragmentation created several problems:
-
-### Problems with Dual Provider Systems
-
-1. **Code Duplication**
-   - Ollama configuration appeared in both `embedding/service.py` and `tests/rag_evaluation/llm_providers.py`
-   - Similar provider detection logic in multiple places
-   - Separate singleton patterns for each system
-
-2. **Limited Extensibility**
-   - Hard-coded provider detection in `EmbeddingService._detect_provider()`
-   - No support for providers that offer both capabilities (like Bedrock)
-   - Adding new providers required modifying multiple files
-
-3. **Inconsistent Patterns**
-   - BM25 provider didn't follow `EmbeddingProvider` ABC
-   - Different method names across providers (`embed` vs `encode`)
-   - ABC vs Protocol for type checking
-
-4. **Difficult Scaling**
-   - Adding Amazon Bedrock (our third provider) would exacerbate all issues
-   - No clear path for future providers (OpenAI, Cohere, etc.)
-
-### Amazon Bedrock Requirements
-
-Bedrock naturally supports **both** embeddings and text generation:
-- **Embeddings**: `amazon.titan-embed-text-v1/v2`, `cohere.embed-*`
-- **Text Generation**: `anthropic.claude-*`, `meta.llama3-*`, `amazon.titan-text-*`
-- **Unified API**: Single `invoke_model()` method via bedrock-runtime
-
-This made it the perfect opportunity to establish a unified provider architecture.
-
-## Decision
-
-We refactored the provider infrastructure to use a **unified Provider ABC** with optional capabilities:
-
-### 1. Unified Provider Interface
-
-**New Structure:**
-```
-nextcloud_mcp_server/providers/
-├── __init__.py
-├── base.py              # Provider ABC with optional capabilities
-├── registry.py          # Auto-detection and factory
-├── ollama.py            # Supports both embedding + generation
-├── anthropic.py         # Generation only
-├── bedrock.py           # Supports both embedding + generation
-└── simple.py            # Embedding only (testing fallback)
-```
-
-**Base Class (`providers/base.py`):**
-```python
-class Provider(ABC):
-    @property
-    @abstractmethod
-    def supports_embeddings(self) -> bool:
-        """Whether this provider supports embedding generation."""
-        pass
-
-    @property
-    @abstractmethod
-    def supports_generation(self) -> bool:
-        """Whether this provider supports text generation."""
-        pass
-
-    @abstractmethod
-    async def embed(self, text: str) -> list[float]:
-        """Generate embedding (raises NotImplementedError if not supported)."""
-        pass
-
-    @abstractmethod
-    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
-        """Generate batch embeddings (raises NotImplementedError if not supported)."""
-        pass
-
-    @abstractmethod
-    def get_dimension(self) -> int:
-        """Get embedding dimension (raises NotImplementedError if not supported)."""
-        pass
-
-    @abstractmethod
-    async def generate(self, prompt: str, max_tokens: int = 500) -> str:
-        """Generate text (raises NotImplementedError if not supported)."""
-        pass
-
-    @abstractmethod
-    async def close(self) -> None:
-        """Close provider and release resources."""
-        pass
-```
-
-### 2. Provider Registry
-
-**Auto-Detection Priority** (`providers/registry.py`):
-```python
-class ProviderRegistry:
-    @staticmethod
-    def create_provider() -> Provider:
-        # 1. Bedrock (AWS_REGION or BEDROCK_*_MODEL)
-        # 2. Ollama (OLLAMA_BASE_URL)
-        # 3. Simple (fallback)
-```
-
-**Environment Variables:**
-
-**Bedrock:**
-- `AWS_REGION`: AWS region (e.g., "us-east-1")
-- `AWS_ACCESS_KEY_ID`: AWS access key (optional, uses credential chain)
-- `AWS_SECRET_ACCESS_KEY`: AWS secret key (optional)
-- `BEDROCK_EMBEDDING_MODEL`: Model ID for embeddings (e.g., "amazon.titan-embed-text-v2:0")
-- `BEDROCK_GENERATION_MODEL`: Model ID for text generation (e.g., "anthropic.claude-3-sonnet-20240229-v1:0")
-
-**Ollama:**
-- `OLLAMA_BASE_URL`: Ollama API base URL (e.g., "http://localhost:11434")
-- `OLLAMA_EMBEDDING_MODEL`: Model for embeddings (default: "nomic-embed-text")
-- `OLLAMA_GENERATION_MODEL`: Model for text generation (e.g., "llama3.2:1b")
-- `OLLAMA_VERIFY_SSL`: Verify SSL certificates (default: "true")
-
-**Simple (no configuration, fallback):**
-- `SIMPLE_EMBEDDING_DIMENSION`: Embedding dimension (default: 384)
-
-### 3. Backward Compatibility
-
-**Old Code Continues to Work:**
-```python
-# Old way (still works)
-from nextcloud_mcp_server.embedding import get_embedding_service
-
-service = get_embedding_service()  # Returns singleton Provider
-embeddings = await service.embed_batch(texts)
-```
-
-**New Way (recommended):**
-```python
-# New way (cleaner)
-from nextcloud_mcp_server.providers import get_provider
-
-provider = get_provider()  # Returns singleton Provider
-embeddings = await provider.embed_batch(texts)
-
-# Can also use generation if provider supports it
-if provider.supports_generation:
-    text = await provider.generate("prompt")
-```
-
-**Migration Path:**
-- `embedding/service.py` now wraps `providers.get_provider()` for compatibility
-- `tests/rag_evaluation/llm_providers.py` now uses unified providers
-- Old imports still work, marked as deprecated in docstrings
-
-### 4. Amazon Bedrock Implementation
-
-**Features:**
-- Supports both embeddings and text generation
-- Model-specific request/response handling for:
-  - Titan Embed (amazon.titan-embed-text-*)
-  - Cohere Embed (cohere.embed-*)
-  - Claude (anthropic.claude-*)
-  - Llama (meta.llama3-*)
-  - Titan Text (amazon.titan-text-*)
-  - Mistral (mistral.*)
-- Uses boto3 bedrock-runtime client
-- Graceful degradation if boto3 not installed
-- Async implementation matching existing patterns
-
-**Model-Specific Handling:**
-```python
-# Bedrock embedding request (Titan)
-{"inputText": text}
-
-# Bedrock generation request (Claude)
-{
-    "anthropic_version": "bedrock-2023-05-31",
-    "max_tokens": max_tokens,
-    "temperature": 0.7,
-    "messages": [{"role": "user", "content": prompt}]
-}
-```
-
-## Consequences
-
-### Positive
-
-1. **Sustainable Provider Additions**
-   - New providers only need to implement `Provider` ABC
-   - Auto-detection via environment variables
-   - No modifications to existing code required
-
-2. **Code Consolidation**
-   - Single provider interface instead of two
-   - Unified configuration pattern
-   - Eliminated duplication
-
-3. **Better Extensibility**
-   - Providers can support one or both capabilities
-   - Clear capability detection via properties
-   - Registry pattern simplifies auto-detection
-
-4. **Improved Testing**
-   - RAG evaluation can use any provider (Ollama, Anthropic, Bedrock)
-   - Comprehensive unit tests for all providers
-   - Mocked boto3 tests for Bedrock
-
-5. **Production-Ready Bedrock Support**
-   - Full embedding and generation support
-   - Multiple model families supported
-   - AWS credential chain integration
-
-### Neutral
-
-1. **Optional Boto3 Dependency**
-   - boto3 is dev dependency only (not required for core functionality)
-   - Bedrock provider gracefully fails if boto3 not installed
-   - Users who want Bedrock must `pip install boto3`
-
-2. **Capability Properties**
-   - All providers must implement capability properties
-   - Methods raise `NotImplementedError` if capability not supported
-   - Clear error messages guide users to alternatives
-
-### Negative
-
-1. **Migration Effort**
-   - Existing code must be migrated to new imports (optional, backward compatible)
-   - Documentation needs updating
-   - Users must learn new environment variables
-
-2. **Increased Complexity**
-   - Provider base class has more methods (embedding + generation)
-   - More environment variables to configure
-   - Capability detection adds runtime checks
-
-## Implementation
-
-### Files Created
-
-**New Provider Infrastructure:**
-- `nextcloud_mcp_server/providers/__init__.py`
-- `nextcloud_mcp_server/providers/base.py`
-- `nextcloud_mcp_server/providers/registry.py`
-- `nextcloud_mcp_server/providers/ollama.py`
-- `nextcloud_mcp_server/providers/anthropic.py`
-- `nextcloud_mcp_server/providers/bedrock.py`
-- `nextcloud_mcp_server/providers/simple.py`
-
-**Tests:**
-- `tests/unit/providers/__init__.py`
-- `tests/unit/providers/test_bedrock.py` (9 unit tests)
-
-**Documentation:**
-- `docs/ADR-015-unified-provider-architecture.md` (this file)
-
-### Files Modified
-
-**Backward Compatibility:**
-- `nextcloud_mcp_server/embedding/service.py` - Now wraps `get_provider()`
-- `tests/rag_evaluation/llm_providers.py` - Uses unified providers
-
-**Dependencies:**
-- `pyproject.toml` - Added `boto3>=1.35.0` to dev dependencies
-
-### Testing Results
-
-**Unit Tests:** 127 passed (including 9 new Bedrock tests)
-**Type Checking:** All checks passed (ty)
-**Linting:** All checks passed (ruff)
-**Backward Compatibility:** Verified - existing embedding tests work
-
-## Alternatives Considered
-
-### Alternative 1: Keep Separate Provider Systems
-
-**Pros:**
-- No refactoring needed
-- Simpler short-term
-
-**Cons:**
-- Bedrock would need to be implemented twice
-- Continued code duplication
-- No long-term scalability
-
-**Decision:** Rejected - technical debt would continue to grow
-
-### Alternative 2: Separate Embedding and Generation Providers
-
-Use composition instead of unified interface:
-```python
-class CombinedProvider:
-    def __init__(self, embedding: EmbeddingProvider, generation: LLMProvider):
-        self.embedding = embedding
-        self.generation = generation
-```
-
-**Pros:**
-- Clearer separation of concerns
-- Simpler individual providers
-
-**Cons:**
-- Bedrock and Ollama naturally do both - artificial separation
-- More complex configuration (two providers to configure)
-- More boilerplate code
-
-**Decision:** Rejected - unified interface better matches provider capabilities
-
-### Alternative 3: Plugin System
-
-Dynamic provider registration via entry points:
-```python
-# setup.py
-entry_points={
-    'nextcloud_mcp.providers': [
-        'ollama = nextcloud_mcp_server.providers.ollama:OllamaProvider',
-        'bedrock = nextcloud_mcp_server.providers.bedrock:BedrockProvider',
-    ]
-}
-```
-
-**Pros:**
-- Most extensible
-- Third-party providers possible
-
-**Cons:**
-- Over-engineered for current needs
-- Added complexity
-- No immediate benefit
-
-**Decision:** Deferred - can add later if needed
-
-## Future Work
-
-1. **Additional Providers**
-   - OpenAI (embeddings + generation)
-   - Cohere (embeddings + generation)
-   - Google Vertex AI
-   - Azure OpenAI
-
-2. **Provider Features**
-   - Streaming generation support
-   - Batch API optimization (when available)
-   - Model-specific optimizations
-   - Cost tracking and metrics
-
-3. **Configuration Improvements**
-   - Provider profiles (development, production)
-   - Model aliasing (e.g., "small", "large")
-   - Fallback provider chains
-
-4. **Testing**
-   - Integration tests with real Bedrock endpoints
-   - Performance benchmarking across providers
-   - Cost comparison analysis
-
-## References
-
-- [boto3 Bedrock Runtime Documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-runtime.html)
-- [Amazon Bedrock User Guide](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html)
-- ADR-003: Vector Database and Semantic Search
-- ADR-008: MCP Sampling for Semantic Search
-- ADR-013: RAG Evaluation Framework

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

@@ -1,492 +0,0 @@
-# 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

@@ -1,506 +0,0 @@
-# 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

@@ -1,342 +0,0 @@
-# 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

@@ -1,391 +0,0 @@
-# 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

@@ -1,104 +0,0 @@
-# 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/authentication.md

@@ -140,93 +140,6 @@ 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 |
-
-### 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/bedrock-setup.md

@@ -1,338 +0,0 @@
-# Amazon Bedrock Setup Guide
-
-This guide covers how to configure the Nextcloud MCP Server to use Amazon Bedrock for embeddings and text generation.
-
-## Prerequisites
-
-1. **AWS Account** with access to Amazon Bedrock
-2. **boto3 library** installed: `pip install boto3` or `uv sync --group dev`
-3. **Model Access** - Request access to models in AWS Bedrock console
-
-## Required AWS Permissions
-
-### IAM Policy for Bedrock Access
-
-The AWS IAM user or role needs the following permissions:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "BedrockInvokeModels",
-      "Effect": "Allow",
-      "Action": [
-        "bedrock:InvokeModel",
-        "bedrock:InvokeModelWithResponseStream"
-      ],
-      "Resource": [
-        "arn:aws:bedrock:*::foundation-model/*"
-      ]
-    }
-  ]
-}
-```
-
-### Minimal Permissions (Production)
-
-For production deployments, restrict to specific models:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "BedrockEmbeddings",
-      "Effect": "Allow",
-      "Action": [
-        "bedrock:InvokeModel"
-      ],
-      "Resource": [
-        "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v2:0"
-      ]
-    },
-    {
-      "Sid": "BedrockGeneration",
-      "Effect": "Allow",
-      "Action": [
-        "bedrock:InvokeModel"
-      ],
-      "Resource": [
-        "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-sonnet-20240229-v1:0"
-      ]
-    }
-  ]
-}
-```
-
-### Additional Permissions (Optional)
-
-For advanced use cases:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "BedrockListModels",
-      "Effect": "Allow",
-      "Action": [
-        "bedrock:ListFoundationModels",
-        "bedrock:GetFoundationModel"
-      ],
-      "Resource": "*"
-    },
-    {
-      "Sid": "BedrockAsyncInvoke",
-      "Effect": "Allow",
-      "Action": [
-        "bedrock:InvokeModelAsync",
-        "bedrock:GetAsyncInvoke",
-        "bedrock:ListAsyncInvokes"
-      ],
-      "Resource": [
-        "arn:aws:bedrock:*::foundation-model/*"
-      ]
-    }
-  ]
-}
-```
-
-## Model Access
-
-Before using Bedrock models, you must request access in the AWS Console:
-
-1. Navigate to **Amazon Bedrock** → **Model access**
-2. Click **Manage model access**
-3. Select models you want to use:
-   - **Embeddings:** Amazon Titan Embed Text, Cohere Embed
-   - **Text Generation:** Anthropic Claude, Meta Llama, Amazon Titan Text
-4. Click **Request model access**
-5. Wait for approval (usually instant for most models)
-
-## Supported Models
-
-### Embedding Models
-
-| Provider | Model ID | Dimensions | Best For |
-|----------|----------|------------|----------|
-| Amazon Titan | `amazon.titan-embed-text-v1` | 1,536 | General purpose |
-| Amazon Titan | `amazon.titan-embed-text-v2:0` | 1,024 | Latest, improved quality |
-| Cohere | `cohere.embed-english-v3` | 1,024 | English text |
-| Cohere | `cohere.embed-multilingual-v3` | 1,024 | Multilingual |
-
-### Text Generation Models
-
-| Provider | Model ID | Context | Best For |
-|----------|----------|---------|----------|
-| Anthropic | `anthropic.claude-3-sonnet-20240229-v1:0` | 200K | Balanced performance |
-| Anthropic | `anthropic.claude-3-haiku-20240307-v1:0` | 200K | Fast, cost-effective |
-| Anthropic | `anthropic.claude-3-opus-20240229-v1:0` | 200K | Highest quality |
-| Meta | `meta.llama3-8b-instruct-v1:0` | 8K | Fast, open-source |
-| Meta | `meta.llama3-70b-instruct-v1:0` | 8K | High quality |
-| Amazon | `amazon.titan-text-express-v1` | 8K | Fast, low cost |
-| Mistral | `mistral.mistral-7b-instruct-v0:2` | 32K | Efficient |
-
-## Configuration
-
-### Environment Variables
-
-**Required:**
-```bash
-AWS_REGION=us-east-1
-```
-
-**Optional (at least one model required):**
-```bash
-# For embeddings
-BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
-
-# For text generation (RAG evaluation)
-BEDROCK_GENERATION_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
-```
-
-**AWS Credentials (choose one method):**
-
-**Method 1: Environment Variables**
-```bash
-AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
-AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
-```
-
-**Method 2: AWS Credentials File** (`~/.aws/credentials`)
-```ini
-[default]
-aws_access_key_id = AKIAIOSFODNN7EXAMPLE
-aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
-```
-
-**Method 3: IAM Role** (when running on AWS EC2/ECS/Lambda)
-- No credentials needed, uses instance/task role automatically
-
-### Docker Configuration
-
-Add to your `docker-compose.yml`:
-
-```yaml
-services:
-  mcp:
-    environment:
-      - AWS_REGION=us-east-1
-      - BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
-      - BEDROCK_GENERATION_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
-      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
-      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
-```
-
-Or use AWS credentials file volume mount:
-
-```yaml
-services:
-  mcp:
-    volumes:
-      - ~/.aws:/root/.aws:ro
-    environment:
-      - AWS_REGION=us-east-1
-      - BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
-```
-
-## Usage Examples
-
-### Embeddings Only
-
-```bash
-export AWS_REGION=us-east-1
-export BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
-export AWS_ACCESS_KEY_ID=your-key
-export AWS_SECRET_ACCESS_KEY=your-secret
-
-uv run nextcloud-mcp-server
-```
-
-### Both Embeddings and Generation
-
-```bash
-export AWS_REGION=us-east-1
-export BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
-export BEDROCK_GENERATION_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
-
-# For RAG evaluation with Bedrock
-export RAG_EVAL_PROVIDER=bedrock
-export RAG_EVAL_BEDROCK_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
-
-uv run python -m tests.rag_evaluation.evaluate
-```
-
-### Programmatic Usage
-
-```python
-from nextcloud_mcp_server.providers import BedrockProvider
-
-# Embeddings only
-provider = BedrockProvider(
-    region_name="us-east-1",
-    embedding_model="amazon.titan-embed-text-v2:0",
-)
-
-embeddings = await provider.embed_batch(["text1", "text2"])
-
-# Both capabilities
-provider = BedrockProvider(
-    region_name="us-east-1",
-    embedding_model="amazon.titan-embed-text-v2:0",
-    generation_model="anthropic.claude-3-sonnet-20240229-v1:0",
-)
-
-# Generate embeddings
-embedding = await provider.embed("query text")
-
-# Generate text
-response = await provider.generate("Write a summary", max_tokens=500)
-```
-
-## Cost Considerations
-
-### Embedding Costs (as of Jan 2025)
-
-| Model | Price per 1K tokens |
-|-------|---------------------|
-| Titan Embed Text v2 | $0.0001 |
-| Cohere Embed English v3 | $0.0001 |
-
-### Generation Costs (as of Jan 2025)
-
-| Model | Input (per 1K tokens) | Output (per 1K tokens) |
-|-------|----------------------|------------------------|
-| Claude 3 Haiku | $0.00025 | $0.00125 |
-| Claude 3 Sonnet | $0.003 | $0.015 |
-| Claude 3 Opus | $0.015 | $0.075 |
-| Llama 3 8B | $0.0003 | $0.0006 |
-| Titan Text Express | $0.0002 | $0.0006 |
-
-**Note:** Prices vary by region. Check [AWS Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/) for current rates.
-
-## Troubleshooting
-
-### Error: "Executable doesn't exist" or boto3 not found
-
-**Solution:**
-```bash
-uv sync --group dev  # Installs boto3
-```
-
-### Error: "AccessDeniedException"
-
-**Causes:**
-1. IAM permissions missing
-2. Model access not requested
-3. Wrong AWS region
-
-**Solution:**
-1. Verify IAM policy includes `bedrock:InvokeModel`
-2. Request model access in Bedrock console
-3. Check model is available in your region
-
-### Error: "ResourceNotFoundException"
-
-**Cause:** Invalid model ID or model not available in region
-
-**Solution:**
-- Verify model ID matches exactly (case-sensitive)
-- Check model availability in your AWS region
-- Use `aws bedrock list-foundation-models` to see available models
-
-### Error: "ThrottlingException"
-
-**Cause:** Rate limit exceeded
-
-**Solution:**
-- Reduce request rate
-- Request quota increase via AWS Support
-- Use batch operations where possible
-
-## Security Best Practices
-
-1. **Use IAM Roles** when running on AWS infrastructure
-2. **Rotate Access Keys** regularly if using IAM users
-3. **Restrict Permissions** to only required models
-4. **Enable CloudTrail** for audit logging
-5. **Use AWS Secrets Manager** for credential management
-6. **Monitor Costs** with AWS Cost Explorer and Budgets
-
-## Regional Availability
-
-Amazon Bedrock is available in:
-- **US East (N. Virginia)**: `us-east-1` ✅ Most models
-- **US West (Oregon)**: `us-west-2` ✅ Most models
-- **Asia Pacific (Singapore)**: `ap-southeast-1`
-- **Asia Pacific (Tokyo)**: `ap-northeast-1`
-- **Europe (Frankfurt)**: `eu-central-1`
-
-**Note:** Model availability varies by region. Check the [AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) for current availability.
-
-## References
-
-- [AWS Bedrock Documentation](https://docs.aws.amazon.com/bedrock/)
-- [AWS Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/)
-- [boto3 Bedrock Runtime API](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-runtime.html)
-- [Provider Architecture ADR](./ADR-015-unified-provider-architecture.md)

docs/configuration-migration-v2.md

@@ -1,564 +0,0 @@
-# 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,82 +2,25 @@
 
 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
 
-We provide mode-specific configuration templates for quick setup:
+Create a `.env` file based on `env.sample`:
 
 ```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 deployment mode:
+Then choose your authentication mode:
 
-- [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](#oauth2oidc-configuration) (Recommended)
+- [Basic Authentication Configuration](#basic-authentication-legacy)
 
 ---
 
-## Deployment Mode Selection
+## OAuth2/OIDC Configuration
 
-**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.
+OAuth2/OIDC is the recommended authentication mode for production deployments.
 
 ### Minimal Configuration (Auto-registration)
 
@@ -85,9 +28,6 @@ OAuth2/OIDC is the recommended authentication mode for production multi-user dep
 # .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=
@@ -101,9 +41,6 @@ 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
@@ -173,50 +110,8 @@ NEXTCLOUD_PASSWORD=your_app_password_or_password
 
 ## 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:
@@ -231,7 +126,7 @@ No configuration needed! If neither `QDRANT_URL` nor `QDRANT_LOCATION` is set, t
 
 ```dotenv
 # No Qdrant configuration needed - defaults to :memory:
-ENABLE_SEMANTIC_SEARCH=true
+VECTOR_SYNC_ENABLED=true
 ```
 
 **Pros:**
@@ -250,7 +145,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
-ENABLE_SEMANTIC_SEARCH=true
+VECTOR_SYNC_ENABLED=true
 ```
 
 **Pros:**
@@ -271,7 +166,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
-ENABLE_SEMANTIC_SEARCH=true
+VECTOR_SYNC_ENABLED=true
 ```
 
 **Pros:**
@@ -388,15 +283,13 @@ Solutions:
 - Data corruption in Qdrant
 - Confusing error messages during indexing
 
-### Background Indexing Configuration
+### Vector Sync Configuration
 
 Control background indexing behavior:
 
 ```dotenv
-# Semantic search (ADR-007, ADR-021)
-ENABLE_SEMANTIC_SEARCH=true           # Enable background indexing
-
-# Tuning parameters (advanced - only modify if needed)
+# Vector sync settings (ADR-007)
+VECTOR_SYNC_ENABLED=true              # Enable background indexing
 VECTOR_SYNC_SCAN_INTERVAL=300         # Scan interval in seconds (default: 5 minutes)
 VECTOR_SYNC_PROCESSOR_WORKERS=3       # Concurrent indexing workers (default: 3)
 VECTOR_SYNC_QUEUE_MAX_SIZE=10000      # Max queued documents (default: 10000)
@@ -406,8 +299,6 @@ 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:
@@ -478,11 +369,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 | Auto-generated | Qdrant collection name |
+| `QDRANT_COLLECTION` | ⚠️ Optional | `nextcloud_content` | Qdrant collection name |
+| `VECTOR_SYNC_ENABLED` | ⚠️ Optional | `false` | Enable background vector indexing |
 | `VECTOR_SYNC_SCAN_INTERVAL` | ⚠️ Optional | `300` | Document scan interval (seconds) |
 | `VECTOR_SYNC_PROCESSOR_WORKERS` | ⚠️ Optional | `3` | Concurrent indexing workers |
 | `VECTOR_SYNC_QUEUE_MAX_SIZE` | ⚠️ Optional | `10000` | Max queued documents |
@@ -492,9 +383,6 @@ 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:
@@ -504,7 +392,7 @@ services:
   mcp:
     environment:
       - QDRANT_URL=http://qdrant:6333
-      - ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_ENABLED=true
 
   qdrant:
     image: qdrant/qdrant:latest
@@ -657,7 +545,6 @@ 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
@@ -666,4 +553,3 @@ 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

@@ -1,301 +0,0 @@
-# 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,10 +14,100 @@ Before running the server:
 
 ## Quick Start
 
-Start the server using Docker:
+Load your environment variables and start the server:
 
 ```bash
-# OAuth mode (recommended)
+# 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
 docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
   ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 
@@ -26,56 +116,11 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
   ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
 ```
 
-The server will start on `http://127.0.0.1:8000` by default.
-
----
-
-## Running with Docker
-
-### Basic Docker Run
-
-#### OAuth Mode (Recommended)
+### Docker with Persistent OAuth Storage
 
 ```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)/data:/app/data \
+  -v $(pwd)/.oauth:/app/.oauth \
   --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 ```
 
@@ -95,7 +140,7 @@ services:
     env_file:
       - .env
     volumes:
-      - ./data:/app/data  # Persistent token storage
+      - ./oauth-storage:/app/.oauth
     restart: unless-stopped
 ```
 
@@ -123,39 +168,30 @@ docker-compose down
 
 ```bash
 # Bind to all interfaces (accessible from network)
-docker run -p 0.0.0.0:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+uv run nextcloud-mcp-server --host 0.0.0.0 --port 8000
 
 # Bind to localhost only (default, more secure)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+uv run nextcloud-mcp-server --host 127.0.0.1 --port 8000
 
-# 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
+# Use a different port
+uv run nextcloud-mcp-server --port 8080
 ```
 
-**Security Note:** Binding to `0.0.0.0` exposes the server to your network. Only use this if you understand the security implications.
+**Security Note:** Using `--host 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 (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
+# Streamable HTTP (recommended)
+uv run nextcloud-mcp-server --transport streamable-http
 
-# 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
+# SSE - Server-Sent Events (default, deprecated)
+uv run nextcloud-mcp-server --transport sse
 
 # HTTP
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --transport http
+uv run nextcloud-mcp-server --transport http
 ```
 
 > [!WARNING]
@@ -165,14 +201,10 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
 
 ```bash
 # Set log level (critical, error, warning, info, debug, trace)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --log-level debug
+uv run nextcloud-mcp-server --log-level debug
 
 # Production: use warning or error
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --log-level warning
+uv run nextcloud-mcp-server --log-level warning
 ```
 
 ### Selective App Enablement
@@ -180,26 +212,22 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
 By default, all supported Nextcloud apps are enabled. You can enable specific apps only:
 
 ```bash
-# Available apps: notes, tables, webdav, calendar, contacts, cookbook, deck
+# Available apps: notes, tables, webdav, calendar, contacts, deck
 
 # Enable all apps (default)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+uv run nextcloud-mcp-server
 
 # Enable only 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
+uv run nextcloud-mcp-server --enable-app notes
 
 # Enable multiple apps
-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
+uv run nextcloud-mcp-server \
+  --enable-app notes \
+  --enable-app calendar \
+  --enable-app contacts
 
 # Enable only WebDAV for file operations
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --enable-app webdav
+uv run nextcloud-mcp-server --enable-app webdav
 ```
 
 **Use cases:**
@@ -212,68 +240,24 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
 
 ## Development Mode
 
-### Running for Development
-
-For active development with auto-reload, mount your source code as a volume:
+For active development with auto-reload:
 
 ```bash
-# 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 \
+# Using uvicorn with reload
+uv run uvicorn nextcloud_mcp_server.app:get_app \
+  --factory \
+  --reload \
+  --host 127.0.0.1 \
+  --port 8000 \
   --log-level debug
 ```
 
-For local development without Docker:
+Or use the CLI with reload flag:
 
 ```bash
-# Load environment variables
-export $(grep -v '^#' .env | xargs)
-
-# Run the server with auto-reload
-uv run nextcloud-mcp-server run --oauth --log-level debug
+uv run nextcloud-mcp-server --reload --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
@@ -282,15 +266,15 @@ See [Database Migrations Guide](database-migrations.md) for detailed information
 
 MCP Inspector is a browser-based tool for testing MCP servers:
 
-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
+```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
+```
 
 ### Using MCP Clients
 
@@ -338,13 +322,48 @@ INFO     Initializing Nextcloud client with BasicAuth
 
 ### Running as a Background Service
 
-Use Docker Compose with `restart: unless-stopped` (see [Docker Compose section](#docker-compose) above).
+#### 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`.
 
 ### Monitoring Logs
 
 ```bash
-# Docker (find container name first)
-docker ps
+# Local installation with systemd
+sudo journalctl -u nextcloud-mcp -f
+
+# Docker
 docker logs -f <container-name>
 
 # Docker Compose
@@ -355,37 +374,34 @@ docker-compose logs -f mcp
 
 ## Performance Tuning
 
-### Production Settings
+### Multiple Workers
 
-For production deployments, use Docker Compose with the recommended settings:
+For production deployments with higher load:
 
-```yaml
-version: '3.8'
+```bash
+# Using CLI (if supported)
+uv run nextcloud-mcp-server --workers 4
 
-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
+# Using uvicorn
+uv run uvicorn nextcloud_mcp_server.app:get_app \
+  --factory \
+  --workers 4 \
+  --host 0.0.0.0 \
+  --port 8000
 ```
 
-### Scaling with Multiple Replicas
+### Production Settings
 
-For higher load, use Docker Swarm or Kubernetes. See the [Helm Chart](../helm/) for Kubernetes deployments.
+```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
+```
 
 ---
 
@@ -395,18 +411,12 @@ For higher load, use Docker Swarm or Kubernetes. See the [Helm Chart](../helm/)
 
 Check logs for errors:
 ```bash
-# 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
+uv run nextcloud-mcp-server --log-level debug
 ```
 
 Common issues:
-- 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`)
+- Environment variables not loaded - See [Configuration](configuration.md#loading-environment-variables)
+- Port already in use - Try a different port with `--port`
 - 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, Files (PDFs), News items, and Deck cards**
+> - Currently supports **Notes app only** (multi-app architecture ready, additional apps planned)
 > - Requires additional infrastructure (Qdrant vector database + Ollama embedding service)
 > - RAG answer generation requires MCP client sampling support
 
@@ -39,9 +39,9 @@ Semantic search enables:
 
 ### Current Support
 
-- **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
+- **Supported Apps**: Notes (fully implemented)
+- **Planned Apps**: Calendar events, Calendar tasks, Deck cards, Files (with text extraction), Contacts
+- **Architecture**: Multi-app plugin system ready, awaiting implementation
 
 ## System Components
 

docs/troubleshooting.md

@@ -4,146 +4,6 @@ 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/user-guide/vector-sync-ui.md

@@ -1,93 +0,0 @@
-# Vector Sync UI Guide
-
-This guide covers the browser-based interface for the Nextcloud MCP Server's semantic search and vector synchronization features.
-
-## Overview
-
-The Vector Sync UI (`/app`) provides an interactive interface to test semantic search queries and visualize results from your Nextcloud documents. It exposes the same retrieval capabilities that LLMs use in Retrieval-Augmented Generation (RAG) workflows, powered by Alpine.js for reactive state, htmx for dynamic updates, and Plotly.js for 3D visualization.
-
-**Supported Apps**: Notes, Files (text/PDF), Calendar (events/tasks), Contacts (CardDAV), and Deck are indexed and searchable.
-
-## Accessing the UI
-
-Navigate to `/app` after authentication:
-- **BasicAuth mode**: `http://localhost:8000/app` (uses credentials from environment)
-- **OAuth mode**: `http://localhost:8000/app` (redirects to login if not authenticated)
-
-## Tabs
-
-### Welcome Page
-
-Landing page that introduces semantic search and RAG workflows. Shows authentication status, explains how vector embeddings work, and provides feature navigation. Adapts content based on whether `VECTOR_SYNC_ENABLED=true`.
-
-### User Info
-
-Displays authentication details and session information:
-- **BasicAuth**: Username, mode badge, Nextcloud host
-- **OAuth**: Username, session ID (truncated), background access status, IdP profile, revocation option
-
-### Vector Sync Status
-
-Real-time monitoring of document indexing:
-- **Indexed Documents**: Total chunks stored in Qdrant vector database (immediately searchable)
-- **Pending Documents**: Queue awaiting embedding processing
-- **Status**: "✓ Idle" (green) when up-to-date, "⟳ Syncing" (orange) during processing
-
-Auto-refreshes every 10 seconds via htmx. Check this tab after adding content to verify indexing completion.
-
-### Vector Visualization
-
-Interactive search interface with 3D PCA plot of semantic space.
-
-**Search Controls**:
-- **Query**: Natural language search (e.g., "health benefits of coffee")
-- **Algorithm**: Semantic (Dense) for pure vector search, or BM25 Hybrid (default) combining vectors + keywords
-- **Fusion** (Hybrid only): RRF (Reciprocal Rank Fusion) or DBSF (Distribution-Based Score Fusion)
-- **Advanced**: Filter by document type, adjust score threshold (0.0-1.0), set result limit (max 100)
-
-**3D Visualization**:
-
-The plot uses Principal Component Analysis (PCA) to reduce 768-dimensional embeddings to 3D. Documents are positioned by semantic similarity with the query point shown in red. Point size and opacity indicate relevance, and the Viridis color scale shows relative scores (yellow = highest match).
-
-**Critical Fix**: Vectors are L2-normalized before PCA to match Qdrant's cosine distance, ensuring query points position accurately near similar documents. Without normalization, magnitude differences cause misleading spatial separation.
-
-**Results List**:
-
-Each result shows document title (clickable link to Nextcloud), excerpt, raw score, relative percentage, and document type. Click "Show Chunk" to view the matched text segment with surrounding context (up to 500 characters before/after).
-
-## Configuration
-
-**Required**:
-```bash
-VECTOR_SYNC_ENABLED=true
-```
-
-**Optional** (for browser-accessible links):
-```bash
-NEXTCLOUD_PUBLIC_ISSUER_URL=https://your-public-nextcloud-url.com
-```
-
-**Admin Access**: Webhooks tab only visible to Nextcloud admins (verified via Provisioning API).
-
-## Use Cases
-
-**Testing Search Queries**: Preview results before they reach LLMs in RAG workflows. Compare semantic vs. hybrid algorithms, verify relevance scores, and validate that correct documents are retrieved. Use chunk context to see exactly which text segments match and why unexpected documents appear.
-
-**Monitoring Indexing**: Track real-time progress after creating or modifying documents. Check if the queue is backing up (high pending count) or confirm the system is idle after bulk imports. Verify documents become searchable immediately after indexing completes.
-
-**Algorithm Comparison**: Pure semantic search excels at conceptual queries and synonyms. BM25 hybrid combines semantic understanding with precise keyword matching for better accuracy on specific terms. Experiment with RRF vs. DBSF fusion for different score distributions.
-
-## Troubleshooting
-
-**Vector Sync Tab Not Visible**: Set `VECTOR_SYNC_ENABLED=true` and restart the server.
-
-**No Search Results**: Check Vector Sync Status to confirm documents are indexed (not just pending). Try broader queries or lower the score threshold in Advanced options. Initial indexing may take time depending on document volume.
-
-**Links to Nextcloud Apps Not Working**: Set `NEXTCLOUD_PUBLIC_ISSUER_URL` to your browser-accessible Nextcloud URL for correct link generation.
-
-## Related Documentation
-
-- [Configuration Guide](../configuration.md) - Environment variables and settings
-- [Authentication Modes](../authentication.md) - BasicAuth vs OAuth setup
-- [Installation Guide](../installation.md) - Getting started
-- [ADR-008: MCP Sampling for RAG](../ADR-008-mcp-sampling-for-rag.md) - Technical details on RAG workflows

env.sample

@@ -1,236 +1,198 @@
-# ============================================
-# 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 Instance
 NEXTCLOUD_HOST=
 
-# ============================================
-# SINGLE-USER BASICAUTH MODE
-# ============================================
-# Simplest deployment - one user, credentials in environment
-# Use for: Personal instances, local development, testing
-#
-# Required:
+# ===== 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
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
-#
-# Optional features (semantic search, document processing):
-# See "Optional Features" section below
 
 # ============================================
-# MULTI-USER BASICAUTH MODE
+# Document Processing Configuration
 # ============================================
-# 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
+# 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
 
 # ============================================
-# OAUTH SINGLE-AUDIENCE MODE (Recommended)
+# Unstructured.io Processor
 # ============================================
-# 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
+# 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
 
 # ============================================
-# OAUTH TOKEN EXCHANGE MODE (Advanced)
+# Tesseract Processor (Local OCR)
 # ============================================
-# 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
+# Enable Tesseract processor (requires tesseract binary installed)
+# This is a local, lightweight OCR solution for images only
+ENABLE_TESSERACT=false
 
-# ============================================
-# SMITHERY STATELESS MODE
-# ============================================
-# 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
-
-# ============================================
-# OPTIONAL FEATURES (All Deployment Modes)
-# ============================================
-
-# ===== 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)
-#VECTOR_SYNC_SCAN_INTERVAL=300
-#
-# Concurrent indexing workers (default: 3)
-#VECTOR_SYNC_PROCESSOR_WORKERS=3
-#
-# Max queued documents (default: 10000)
-#VECTOR_SYNC_QUEUE_MAX_SIZE=10000
-
-# ===== 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
+# Path to tesseract executable (optional, auto-detected if in PATH)
 #TESSERACT_CMD=/usr/bin/tesseract
-#TESSERACT_LANG=eng
-#
-# Custom Processor (your own API):
-#ENABLE_CUSTOM_PROCESSOR=false
+
+# OCR language (e.g., eng, deu, eng+deu for multiple)
+TESSERACT_LANG=eng
+
+# ============================================
+# Custom Processor (Your own API)
+# ============================================
+# Enable custom document processor via HTTP API
+ENABLE_CUSTOM_PROCESSOR=false
+
+# Unique name for your processor
 #CUSTOM_PROCESSOR_NAME=my_ocr
+
+# Your custom processor API endpoint
 #CUSTOM_PROCESSOR_URL=http://localhost:9000/process
-#CUSTOM_PROCESSOR_API_KEY=
+
+# 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
 
-# ===== SECURITY & ADVANCED =====
-# Cookie security (browser UI)
-# Auto-detects from NEXTCLOUD_HOST protocol if not set
-#COOKIE_SECURE=true
+# ============================================
+# Semantic Search & Vector Sync Configuration
+# ============================================
+# EXPERIMENTAL: Semantic search for Notes app (multi-app support planned)
+# Requires: Qdrant vector database + Ollama embedding service
+# Disabled by default
+
+# Enable background vector indexing
+VECTOR_SYNC_ENABLED=false
+
+# Document scan interval in seconds (default: 300 = 5 minutes)
+# How often to check for new/updated documents
+#VECTOR_SYNC_SCAN_INTERVAL=300
+
+# Concurrent indexing workers (default: 3)
+# Number of parallel workers for embedding generation
+#VECTOR_SYNC_PROCESSOR_WORKERS=3
+
+# Max queued documents (default: 10000)
+# Maximum documents waiting to be processed
+#VECTOR_SYNC_QUEUE_MAX_SIZE=10000
 
 # ============================================
-# DEPRECATED VARIABLES (Backward Compatibility)
+# Qdrant Vector Database Configuration
 # ============================================
-# 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
+# Choose ONE of three modes:
+# 1. In-memory mode (default): Set neither QDRANT_URL nor QDRANT_LOCATION
+# 2. Persistent local: Set QDRANT_LOCATION=/path/to/data
+# 3. Network mode: Set QDRANT_URL=http://qdrant:6333
+
+# Network mode: URL to Qdrant service
+#QDRANT_URL=http://qdrant:6333
+
+# Local mode: Path to store vectors (use :memory: for in-memory)
+#QDRANT_LOCATION=:memory:
+
+# API key for network mode (optional)
+#QDRANT_API_KEY=
+
+# Collection name (optional - auto-generated if not set)
+# Auto-generation format: {deployment-id}-{model-name}
+# Allows safe model switching and multi-server deployments
+#QDRANT_COLLECTION=nextcloud_content
+
+# ============================================
+# Ollama Embedding Service Configuration
+# ============================================
+# Ollama endpoint for embeddings (if not set, uses SimpleEmbeddingProvider fallback)
+#OLLAMA_BASE_URL=http://ollama:11434
+
+# Embedding model to use (default: nomic-embed-text, 768 dimensions)
+# Changing this creates a new collection (requires re-embedding all documents)
+#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Verify SSL certificates (default: true)
+#OLLAMA_VERIFY_SSL=true
+
+# ============================================
+# Document Chunking Configuration
+# ============================================
+# Configure how documents are split before embedding
+
+# Words per chunk (default: 512)
+# Smaller chunks (256-384): More precise, less context, more storage
+# Larger chunks (768-1024): More context, less precise, less storage
+#DOCUMENT_CHUNK_SIZE=512
+
+# Overlapping words between chunks (default: 50)
+# Recommended: 10-20% of chunk size
+# Preserves context across chunk boundaries
+#DOCUMENT_CHUNK_OVERLAP=50

env.sample.oauth-advanced

@@ -1,80 +0,0 @@
-# ============================================
-# 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

@@ -1,77 +0,0 @@
-# ============================================
-# 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

@@ -1,37 +0,0 @@
-# ============================================
-# 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

@@ -1,133 +0,0 @@
-"""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

@@ -1,185 +0,0 @@
-"""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/api/__init__.py

@@ -1,6 +0,0 @@
-"""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.
-"""

nextcloud_mcp_server/auth/astrolabe_client.py

@@ -1,152 +0,0 @@
-"""
-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
-
-import httpx
-
-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 httpx.AsyncClient() 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 httpx.AsyncClient() 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,7 +8,6 @@ import hashlib
 import logging
 import os
 import secrets
-import time
 from base64 import urlsafe_b64encode
 from urllib.parse import urlencode
 
@@ -25,26 +24,6 @@ from nextcloud_mcp_server.auth.userinfo_routes import (
 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.
 
@@ -71,10 +50,6 @@ 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)
 
@@ -96,7 +71,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=next_url,  # Store the redirect URL for after auth
+        client_redirect_uri="/app",
         state=state,
         code_challenge=code_challenge,
         code_challenge_method="S256",
@@ -110,11 +85,6 @@ 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,
@@ -124,7 +94,6 @@ 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)}"
@@ -162,11 +131,6 @@ 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,
@@ -176,7 +140,6 @@ 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
@@ -251,15 +214,12 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
     oauth_client = oauth_ctx["oauth_client"]
     oauth_config = oauth_ctx["config"]
 
-    # Retrieve code_verifier and redirect URL from session storage
+    # Retrieve code_verifier from session storage (PKCE required for all modes)
     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
 
@@ -378,33 +338,16 @@ 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=refresh_expires_at,
+            expires_at=None,
             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(
@@ -440,14 +383,13 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
             # Continue anyway - profile cache is optional for browser UI
 
     # Create response and set session cookie
-    # Redirect to stored next_url (from OAuth session) or /app as default
-    response = RedirectResponse(next_url, status_code=302)
+    response = RedirectResponse("/app", status_code=302)
     response.set_cookie(
         key="mcp_session",
         value=user_id,
         max_age=86400 * 30,  # 30 days
         httponly=True,
-        secure=_should_use_secure_cookies(),
+        secure=False,  # Set to True in production with HTTPS
         samesite="lax",
     )
 

nextcloud_mcp_server/auth/keycloak_oauth.py

@@ -8,7 +8,6 @@ Handles OAuth flows with Keycloak as the identity provider, including:
 - Integration with RefreshTokenStorage
 """
 
-import base64
 import hashlib
 import logging
 import os
@@ -156,6 +155,7 @@ 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,7 +23,6 @@ import hashlib
 import logging
 import os
 import secrets
-import time
 from base64 import urlsafe_b64encode
 from urllib.parse import urlencode
 
@@ -518,21 +517,12 @@ 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,
@@ -541,7 +531,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=refresh_expires_at,
+            expires_at=None,  # Refresh tokens typically don't expire
         )
         logger.info(f"✓ Stored Flow 2 master refresh token for user {user_id}")
         logger.info("=" * 60)

nextcloud_mcp_server/auth/provisioning_decorator.py

@@ -9,7 +9,6 @@ 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
@@ -79,6 +78,8 @@ 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")
@@ -162,6 +163,8 @@ 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,6 +1,7 @@
 """Scope-based authorization for MCP tools."""
 
 import logging
+import os
 from functools import wraps
 from typing import Any, Callable
 
@@ -130,12 +131,9 @@ def require_scopes(*required_scopes: str):
             required_scopes_set = set(required_scopes)
 
             # 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
+            enable_offline_access = (
+                os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
+            )
 
             # In offline access mode, check if Nextcloud scopes require provisioning
             if enable_offline_access:

nextcloud_mcp_server/auth/static/vector-viz.css

@@ -1,219 +0,0 @@
-.viz-layout {
-    display: flex;
-    flex-direction: column;
-    gap: 16px;
-    height: 100%;
-    min-height: 0;
-    overflow-y: auto;
-}
-.viz-card {
-    background: var(--color-main-background);
-    border-radius: 0;
-    padding: 16px;
-    box-shadow: none;
-}
-.viz-controls-card {
-    flex: 0 0 auto;
-    border-bottom: 1px solid var(--color-border);
-    padding-bottom: 16px;
-}
-.viz-controls-grid {
-    display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-    gap: 12px;
-    align-items: end;
-}
-@media (min-width: 768px) {
-    .viz-controls-grid {
-        grid-template-columns: 2fr 1.5fr 1.5fr auto auto;
-    }
-}
-.viz-control-group {
-    display: flex;
-    flex-direction: column;
-    gap: 4px;
-}
-.viz-control-group label {
-    font-weight: 500;
-    color: var(--color-main-text);
-    font-size: 13px;
-}
-.viz-control-group input[type="text"],
-.viz-control-group input[type="number"],
-.viz-control-group select {
-    width: 100%;
-    padding: 7px 10px;
-    border: 1px solid var(--color-border-dark);
-    border-radius: var(--border-radius);
-    font-size: 14px;
-    background: var(--color-main-background);
-    color: var(--color-main-text);
-}
-.viz-control-group input:focus,
-.viz-control-group select:focus {
-    outline: none;
-    border-color: var(--color-primary-element);
-}
-.viz-control-group input[type="range"] {
-    width: 100%;
-}
-.viz-control-group select[multiple] {
-    min-height: 100px;
-}
-.viz-weight-display {
-    display: inline-block;
-    min-width: 40px;
-    text-align: right;
-    color: #666;
-}
-.viz-btn {
-    background: var(--color-primary-element);
-    color: white;
-    border: none;
-    padding: 7px 16px;
-    border-radius: var(--border-radius);
-    cursor: pointer;
-    font-size: 14px;
-    font-weight: 500;
-    white-space: nowrap;
-}
-.viz-btn:hover {
-    background: #0052a3;
-}
-.viz-btn-secondary {
-    background: #6c757d;
-    color: white;
-    border: none;
-    padding: 7px 16px;
-    border-radius: var(--border-radius);
-    cursor: pointer;
-    font-size: 14px;
-    white-space: nowrap;
-}
-.viz-btn-secondary:hover {
-    background: #5a6268;
-}
-.viz-card-plot {
-    flex: 0 0 auto;
-    display: flex;
-    flex-direction: column;
-    min-height: 500px;
-    height: 600px;
-    /* Remove horizontal padding to extend to full viewport width */
-    padding-left: 0;
-    padding-right: 0;
-    margin-left: -16px;
-    margin-right: -16px;
-}
-#viz-plot-container {
-    width: 100%;
-    height: 100%;
-    position: relative;
-    overflow: visible;
-}
-#viz-plot {
-    width: 100%;
-    height: 100%;
-}
-.viz-loading {
-    text-align: center;
-    padding: 40px;
-    color: #666;
-}
-.viz-loading-overlay {
-    position: absolute;
-    inset: 0;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    background: white;
-    color: #666;
-}
-.viz-no-results {
-    text-align: center;
-    padding: 40px;
-    color: #666;
-    font-style: italic;
-}
-.viz-advanced-section {
-    margin-top: 12px;
-    padding: 12px;
-    background: var(--color-background-hover);
-    border-radius: var(--border-radius);
-    border: 1px solid var(--color-border);
-}
-.viz-info-box {
-    background: var(--color-primary-element-light);
-    border-left: 3px solid var(--color-primary-element);
-    padding: 10px 12px;
-    margin-bottom: 16px;
-    font-size: 13px;
-    color: var(--color-main-text);
-}
-.chunk-toggle-btn {
-    background: #6c757d;
-    color: white;
-    border: none;
-    padding: 4px 10px;
-    border-radius: 3px;
-    cursor: pointer;
-    font-size: 12px;
-    margin-top: 6px;
-}
-.chunk-toggle-btn:hover {
-    background: #5a6268;
-}
-.chunk-context {
-    background: var(--color-background-hover);
-    border: 1px solid var(--color-border);
-    border-radius: var(--border-radius);
-    padding: 12px;
-    margin-top: 8px;
-    font-family: 'SFMono-Regular', 'Consolas', 'Liberation Mono', 'Menlo', monospace;
-    font-size: 13px;
-    line-height: 1.6;
-    white-space: pre-wrap;
-    word-wrap: break-word;
-}
-.chunk-text {
-    color: var(--color-text-maxcontrast);
-}
-.chunk-matched {
-    background: #fff3cd;
-    border: 1px solid #ffc107;
-    padding: 2px 4px;
-    border-radius: var(--border-radius);
-    font-weight: 500;
-    color: var(--color-main-text);
-}
-.chunk-ellipsis {
-    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

@@ -1,260 +0,0 @@
-// Initialize vizApp for vector visualization
-function vizApp() {
-    return {
-        query: '',
-        algorithm: 'bm25_hybrid',
-        fusion: 'rrf',
-        showAdvanced: false,
-        showQueryPoint: true,
-        docTypes: [''],
-        limit: 50,
-        scoreThreshold: 0.0,
-        loading: false,
-        results: [],
-        coordinates: null,
-        queryCoords: null,
-        expandedChunks: {},
-        chunkLoading: {},
-
-        init() {
-            // Set up window resize listener to resize plot
-            window.addEventListener('resize', () => {
-                if (this.coordinates && this.results.length > 0) {
-                    Plotly.Plots.resize('viz-plot');
-                }
-            });
-        },
-
-        async executeSearch() {
-            this.loading = true;
-            this.results = [];
-
-            try {
-                const params = new URLSearchParams({
-                    query: this.query,
-                    algorithm: this.algorithm,
-                    limit: this.limit,
-                    score_threshold: this.scoreThreshold,
-                });
-
-                if (this.algorithm === 'bm25_hybrid') {
-                    params.append('fusion', this.fusion);
-                }
-
-                const selectedTypes = this.docTypes.filter(t => t !== '');
-                if (selectedTypes.length > 0) {
-                    params.append('doc_types', selectedTypes.join(','));
-                }
-
-                const response = await fetch(`/app/vector-viz/search?${params}`);
-                const data = await response.json();
-
-                if (data.success) {
-                    this.results = data.results;
-                    this.coordinates = data.coordinates_3d;
-                    this.queryCoords = data.query_coords;
-                    this.renderPlot(this.coordinates, this.queryCoords, this.results);
-                } else {
-                    alert('Search failed: ' + data.error);
-                }
-            } catch (error) {
-                alert('Error: ' + error.message);
-            } finally {
-                this.loading = false;
-            }
-        },
-
-        updatePlot() {
-            // Toggle query point visibility without recreating the plot
-            // This preserves camera position naturally since layout is untouched
-            if (this.coordinates && this.queryCoords && this.results.length > 0) {
-                const plotDiv = document.getElementById('viz-plot');
-
-                // If plot exists, just toggle the query trace visibility
-                if (plotDiv && plotDiv.data && plotDiv.data.length >= 2) {
-                    // Trace index 1 is the query point
-                    Plotly.restyle('viz-plot', { visible: this.showQueryPoint }, [1]);
-                } else {
-                    // Plot doesn't exist yet, render it
-                    this.renderPlot(this.coordinates, this.queryCoords, this.results);
-                }
-            }
-        },
-
-        renderPlot(coordinates, queryCoords, results) {
-            // Get container dimensions before creating layout
-            const container = document.getElementById('viz-plot-container');
-            const width = container.clientWidth;
-            const height = container.clientHeight;
-
-            const scores = results.map(r => r.score);
-
-            // Trace 1: Document results (always visible)
-            const documentTrace = {
-                x: coordinates.map(c => c[0]),
-                y: coordinates.map(c => c[1]),
-                z: coordinates.map(c => c[2]),
-                mode: 'markers',
-                type: 'scatter3d',
-                name: 'Documents',
-                visible: true,
-                customdata: results.map((r, i) => ({
-                    title: r.title,
-                    raw_score: r.original_score,
-                    relative_score: r.score,
-                    x: coordinates[i][0],
-                    y: coordinates[i][1],
-                    z: coordinates[i][2]
-                })),
-                hovertemplate:
-                    '<b>%{customdata.title}</b><br>' +
-                    'Raw Score: %{customdata.raw_score:.3f} (%{customdata.relative_score:.0%} relative)<br>' +
-                    '(x=%{customdata.x}, y=%{customdata.y}, z=%{customdata.z})' +
-                    '<extra></extra>',
-                marker: {
-                    size: results.map(r => 4 + (Math.pow(r.score, 2) * 10)),
-                    opacity: results.map(r => 0.3 + (r.score * 0.7)),
-                    color: scores,
-                    colorscale: 'Viridis',
-                    showscale: true,
-                    colorbar: {
-                        title: 'Relative Score',
-                        x: 1.02,
-                        xanchor: 'left',
-                        thickness: 20,
-                        len: 0.8
-                    },
-                    cmin: 0,
-                    cmax: 1
-                }
-            };
-
-            // Trace 2: Query point (visibility controlled by toggle)
-            const queryTrace = {
-                x: [queryCoords[0]],
-                y: [queryCoords[1]],
-                z: [queryCoords[2]],
-                mode: 'markers',
-                type: 'scatter3d',
-                name: 'Query',
-                visible: this.showQueryPoint,  // Initial visibility from state
-                hovertemplate:
-                    '<b>Search Query</b><br>' +
-                    `(x=${queryCoords[0]}, y=${queryCoords[1]}, z=${queryCoords[2]})` +
-                    '<extra></extra>',
-                marker: {
-                    size: 10,
-                    color: '#ef5350',  // Subdued red (Material Design Red 400)
-                    line: {
-                        color: '#c62828',  // Darker red border (Material Design Red 800)
-                        width: 1
-                    }
-                }
-            };
-
-            const layout = {
-                title: `Vector Space (PCA 3D) - ${results.length} results`,
-                width: width,   // Explicit width from container
-                height: height, // Explicit height from container
-                scene: {
-                    xaxis: { title: 'PC1' },
-                    yaxis: { title: 'PC2' },
-                    zaxis: { title: 'PC3' },
-                    camera: {
-                        eye: { x: 1.5, y: 1.5, z: 1.5 }
-                    },
-                    // Full width for 3D scene
-                    domain: {
-                        x: [0, 1],
-                        y: [0, 1]
-                    }
-                },
-                hovermode: 'closest',
-                autosize: true,  // Enable auto-sizing for window resizes
-                showlegend: false,  // Hide legend
-                margin: { l: 0, r: 100, t: 40, b: 0 }  // Right margin for colorbar
-            };
-
-            // Always render both traces - visibility is controlled by the visible property
-            const traces = [documentTrace, queryTrace];
-
-            // Enable responsive resizing
-            const config = {
-                responsive: true,
-                displayModeBar: true
-            };
-
-            // Use newPlot() with explicit dimensions - renders at correct size immediately
-            // Camera position will be preserved by subsequent Plotly.restyle() calls in updatePlot()
-            Plotly.newPlot('viz-plot', traces, layout, config);
-        },
-
-        getNextcloudUrl(result) {
-            // Use global NEXTCLOUD_BASE_URL if set, otherwise construct from window location
-            const baseUrl = window.NEXTCLOUD_BASE_URL || '';
-            switch (result.doc_type) {
-                case 'note':
-                    return `${baseUrl}/apps/notes/note/${result.id}`;
-                case 'file':
-                    return `${baseUrl}/apps/files/?fileId=${result.id}`;
-                case 'calendar':
-                    return `${baseUrl}/apps/calendar`;
-                case 'contact':
-                    return `${baseUrl}/apps/contacts`;
-                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}`;
-            }
-        },
-
-        hasChunkPosition(result) {
-            return result.chunk_start_offset != null && result.chunk_end_offset != null;
-        },
-
-        isChunkExpanded(resultKey) {
-            return this.expandedChunks[resultKey] !== undefined;
-        },
-
-        async toggleChunk(result) {
-            const resultKey = `${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`;
-
-            if (this.isChunkExpanded(resultKey)) {
-                delete this.expandedChunks[resultKey];
-                return;
-            }
-
-            this.chunkLoading[resultKey] = true;
-
-            try {
-                const params = new URLSearchParams({
-                    doc_type: result.doc_type,
-                    doc_id: result.id,
-                    start: result.chunk_start_offset,
-                    end: result.chunk_end_offset,
-                    context: 500
-                });
-
-                const response = await fetch(`/app/chunk-context?${params}`);
-                const data = await response.json();
-
-                if (data.success) {
-                    this.expandedChunks[resultKey] = data;
-                } else {
-                    alert('Failed to load chunk: ' + data.error);
-                }
-            } catch (error) {
-                alert('Error loading chunk: ' + error.message);
-            } finally {
-                delete this.chunkLoading[resultKey];
-            }
-        }
-    };
-}

nextcloud_mcp_server/auth/storage.py

@@ -28,7 +28,6 @@ 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
@@ -118,14 +117,7 @@ class RefreshTokenStorage:
         return cls(db_path=db_path, encryption_key=encryption_key)
 
     async def initialize(self) -> None:
-        """
-        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
-        """
+        """Initialize database schema"""
         if self._initialized:
             return
 
@@ -133,59 +125,137 @@ class RefreshTokenStorage:
         db_dir = Path(self.db_path).parent
         db_dir.mkdir(parents=True, exist_ok=True)
 
-        # Set restrictive permissions on database file if it exists
+        # Set restrictive permissions on database file
         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:
-            # Check if database is managed by Alembic
-            cursor = await db.execute(
-                "SELECT name FROM sqlite_master WHERE type='table' AND name='alembic_version'"
+            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
+                )
+                """
             )
-            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'"
+            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
                 )
-                has_schema = await cursor.fetchone() is not None
+                """
+            )
 
-                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"
-                    )
+            # 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)"
+            )
 
-        # 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."
+            # 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
                 )
-            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")
+                """
+            )
 
-        # Set restrictive permissions after initialization
+            # 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
         os.chmod(self.db_path, 0o600)
 
         self._initialized = True
@@ -217,8 +287,6 @@ 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
@@ -364,9 +432,6 @@ 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:
@@ -451,9 +516,6 @@ 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(
                 """
@@ -625,9 +687,6 @@ 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 = (
@@ -698,9 +757,6 @@ 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(
                 """
@@ -831,6 +887,7 @@ class RefreshTokenStorage:
             resource_id: Resource identifier
             auth_method: Authentication method used
         """
+        import socket
 
         hostname = socket.gethostname()
         timestamp = int(time.time())
@@ -1253,7 +1310,7 @@ async def generate_encryption_key() -> str:
 
 # Example usage
 if __name__ == "__main__":
-    import anyio
+    import asyncio
 
     async def main():
         # Generate a key for testing
@@ -1261,4 +1318,4 @@ if __name__ == "__main__":
         print(f"Generated encryption key: {key}")
         print(f"Set this in your environment: export TOKEN_ENCRYPTION_KEY='{key}'")
 
-    anyio.run(main)
+    asyncio.run(main())

nextcloud_mcp_server/auth/templates/base.html

@@ -1,524 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta http-equiv="X-UA-Compatible" content="IE=edge">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
-    <meta name="apple-mobile-web-app-capable" content="yes">
-    <meta name="theme-color" content="#0082c9">
-    <title>{% block title %}Nextcloud MCP Server{% endblock %}</title>
-
-    <!-- Favicon -->
-    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='32' height='32' viewBox='0 0 512 512'><rect width='512' height='512' rx='80' ry='80' fill='%230082C9'/><path d='M255.9 21.04c-11.8 0-22.2 4.08-28.6 10.01-5.6 4.98-8.6 11.41-8.6 18.11 0 5.55 2.2 11.01 5.9 15.48-16.4 4.97-30.1 13.64-39 24.53 22.1-7.67 45.7-11.86 70.3-11.86 24.6 0 48.3 4.19 70.3 11.86-8.9-10.89-22.6-19.56-39-24.53 3.9-4.47 5.9-9.93 5.9-15.48 0-6.7-3-13.13-8.5-18.11-6.4-5.93-16.9-10.01-28.7-10.01zm0 20.34c5.3 0 10.1 1.27 13.6 3.52 1.7 1.16 3.4 2.43 3.4 4.27 0 1.76-1.7 3.03-3.4 4.19-3.5 2.33-8.3 3.61-13.6 3.61-5.3 0-10.1-1.28-13.6-3.61-1.6-1.16-3.3-2.43-3.3-4.19 0-1.84 1.7-3.11 3.3-4.27 3.5-2.25 8.3-3.52 13.6-3.52zm.1 48.1c-110.8 0-200.72 90.02-200.72 200.82S145.2 491 256 491s200.7-89.9 200.7-200.7c0-110.8-89.9-200.82-200.7-200.82zm0 32.62c92.9 0 168.2 75.3 168.2 168.2 0 92.8-75.3 168.2-168.2 168.2-92.9 0-168.26-75.4-168.26-168.2 0-92.9 75.36-168.2 168.26-168.2zm-8.2 6.3c-9.6.5-19 1.9-28.3 4.1l2.3 7.8c8.4-2 17.1-3.3 26-3.8v-8.1zm16.2 0v8.1c9 .5 17.7 1.8 26 3.8l2.2-7.8c-9.1-2.2-18.6-3.6-28.2-4.1zm-60 8.5c-9 3.2-17.6 7-25.8 11.6l4.1 7.1c7.7-4.3 15.6-7.9 23.9-10.8l-2.2-7.9zm103.7 0-2 7.9c8.4 2.9 16.2 6.5 23.8 10.8l4.2-7.1c-8.2-4.6-16.9-8.4-26-11.6zm-143.3 20.3c-7.5 5.4-14.6 11.4-21.1 17.9l5.8 5.8c5.9-6.1 12.5-11.7 19.5-16.6l-4.2-7.1zm182.9 0-4 7.1c6.9 4.9 13.5 10.5 19.5 16.6l5.7-5.8c-6.5-6.5-13.7-12.5-21.2-17.9zm-91.4 11.5c-37 0-67.4 28.6-70.3 64.9l15.9 4.7c.7-29.6 24.7-53.4 54.4-53.4 30.1 0 54.4 24.4 54.4 54.3 0 15-6.2 28.7-16 38.5l.1.1c1.7 2.7 3 5.6 4.1 8.6.9 3 1.7 5.7 2.3 8.6v.4c33.8-16.7 57.2-51.5 57.2-91.7 0-3.8-.2-7.3-.6-10.9-3.2-3.3-6.3-6.4-9.8-9.5 1.5 6.5 2.3 13.4 2.3 20.4 0 28.7-13 54.7-33.5 71.8 6.3-10.6 10.1-23 10.1-36.3 0-38.9-31.7-70.5-70.6-70.5zm-91.8 14.6c-3.3 3.1-6.5 6.2-9.7 9.5-.3 3.6-.5 7.1-.5 10.9 0 7.3.7 14.2 2.1 20.9l9.1 2.7c-2.1-7.5-3.1-15.4-3.1-23.6 0-7 .7-13.9 2.1-20.4zm-31.6 4c-5.8 7.1-10.9 14.6-15.4 22.6l7.1 4c4.1-7.4 8.8-14.3 14-20.8l-5.7-5.8zm246.8 0-5.7 5.8c5.3 6.5 10 13.4 13.9 20.8l7.1-4c-4.4-8-9.5-15.5-15.3-22.6zm-269.2 37.1c-2.5 5.7-4.6 11.4-6.4 17.6l.1-.3c3.4-5 7.9-9.3 12.9-12.5l.3-.6-6.9-4.2zm291.8 0-7.2 4.2c3.2 7.3 5.7 15.1 7.6 23.1l7.9-2.1c-2.1-8.8-4.9-17.3-8.3-25.2zm-261.2 11.5c-13.4.1-25.7 9-29.7 22.5l114.8 34.2c-4.9 16.7 4.6 34.2 21.2 39.2L361.7 366c16.6 5 34.1-4.4 39.1-21l-114.6-34.4c4.9-16.5-4.7-34.1-21.3-39.1 0 0-72.4-21.5-114.8-34.3-3.1-.9-6.3-1.4-9.4-1.3zm-42.09 29.7c-.9 6.9-1.4 14-1.4 21.3 0 1.3.1 2.9.1 4.2h8.09v-4.2c0-6.5.4-12.9 1.2-19.2l-7.99-2.1zm314.59 0-7.9 2.1c.7 6.3 1.3 12.7 1.3 19.2 0 1.3 0 2.9-.2 4.2h8.2v-4.2c0-7.3-.5-14.4-1.4-21.3zm-157.3 24.7c6.3 0 11.5 5 11.5 11.3 0 6.4-5.2 11.6-11.5 11.6s-11.5-5.2-11.5-11.6c0-6.3 5.2-11.3 11.5-11.3zM98.51 307.4c1 8.2 2.89 16.4 5.09 24.3l7.9-2.1c-2.1-7.2-3.8-14.6-4.8-22.2h-8.19zm306.69 0c-1.1 7.6-2.7 15-4.8 22.2l7.8 2.1c2.2-7.9 4.1-16.1 5.2-24.3h-8.2zm-191.3 10.9c-19 13.3-31.4 35.3-31.4 60.1 0 10.4 2.3 20.4 6.2 29.7 8.8 4.9 17.9 8.8 27.6 11.7-10.8-10.7-17.5-25.2-17.5-41.4 0-19 9.3-36 23.7-46.3-3.8-4.1-6.7-8.7-8.6-13.8zM116.8 345l-7.9 2c3.1 7.6 6.8 14.7 11 21.6l6.9-4.2c-3.8-6.2-7-12.8-10-19.4zm194.8 20.5c.9 4.1 1.4 8.5 1.4 12.9 0 16.2-6.7 30.7-17.4 41.4 9.6-2.9 18.8-6.8 27.5-11.7 4-9.3 6.2-19.3 6.2-29.7 0-2.7-.2-5.2-.4-7.7l-17.3-5.2zM136 377.9l-7.1 4.1c4.7 6.2 9.7 12.1 15.3 17.3l5.7-5.5c-5.1-5-9.7-10.3-13.9-15.9zm243.9 2.3-.2.1c-2.1.3-4 .6-6.2.7h-.1c-3.6 4.5-7.3 8.8-11.5 12.8l5.8 5.5c5.5-5.2 10.5-11.1 15.2-17.3l-3-1.8zm-217.8 24-5.9 5.9c6 4.8 12.2 9.7 18.8 13.6l3.8-7.8c-5.7-2.9-11.4-6.8-16.7-11.7zm187.7 0c-5.4 4.9-11.1 8.8-16.8 11.7l3.9 7.8c6.5-3.9 12.8-8.8 18.7-13.6l-5.8-5.9zm-156.4 19.5-4.1 6.8c6.6 4 13.7 5.8 20.7 8.8l2.2-7.9c-6.5-1.9-12.7-4.8-18.8-7.7zm125.2 0c-6.2 2.9-12.5 5.8-19.1 7.7l2.3 7.9c7.2-3 14-4.8 20.7-8.8l-3.9-6.8zm-90.7 11.7-2 7.8c7.1 1 14.5 1.9 21.9 1.9v-7.7c-6.8 0-13.5-1.1-19.9-2zm55.9 0c-6.3.9-13 2-19.8 2v7.7c7.5 0 14.8-.9 22.1-1.9l-2.3-7.8z' fill='%23fff'/></svg>">
-
-    <!-- Open Sans font -->
-    <style>
-        @font-face {
-            font-family: 'Open Sans';
-            font-style: normal;
-            font-weight: normal;
-            src: local('Open Sans'), local('OpenSans');
-        }
-        @font-face {
-            font-family: 'Open Sans';
-            font-style: normal;
-            font-weight: bold;
-            src: local('Open Sans Semibold'), local('OpenSans-Semibold');
-        }
-    </style>
-
-    {% block extra_head %}{% endblock %}
-
-    <style>
-        /* Nextcloud App Design System */
-
-        /* CSS Variables */
-        :root {
-            /* Primary Colors */
-            --color-primary: #00679e;
-            --color-primary-element: #00679e;
-            --color-primary-light: #e5eff5;
-            --color-primary-element-light: #e5eff5;
-
-            /* Background Colors */
-            --color-main-background: #ffffff;
-            --color-background-dark: #ededed;
-            --color-background-hover: #f5f5f5;
-
-            /* Text Colors */
-            --color-main-text: #222222;
-            --color-text-maxcontrast: #6b6b6b;
-            --color-text-light: #767676;
-
-            /* Border Colors */
-            --color-border: #ededed;
-            --color-border-dark: #dbdbdb;
-
-            /* Borders & Radius */
-            --border-radius: 3px;
-            --border-radius-large: 10px;
-            --border-radius-pill: 100px;
-
-            /* Spacing */
-            --default-grid-baseline: 4px;
-            --default-clickable-area: 44px;
-        }
-
-        /* SVG Icon Styles */
-        .nav-icon {
-            width: 20px;
-            height: 20px;
-            display: inline-block;
-            fill: var(--color-main-text);
-            opacity: 0.7;
-        }
-
-        .app-navigation-entry.active .nav-icon {
-            fill: var(--color-primary-element);
-            opacity: 1;
-        }
-
-        /* General */
-        * {
-            box-sizing: border-box;
-        }
-
-        body {
-            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-            color: var(--color-main-text);
-            background: var(--color-main-background);
-            margin: 0;
-            padding: 0;
-        }
-
-        h1, h2, h3 {
-            font-weight: 300;
-            line-height: 1.2;
-        }
-
-        h1 {
-            font-size: 32px;
-            margin: 0 0 20px 0;
-            color: var(--color-main-text);
-        }
-
-        h2 {
-            font-size: 20px;
-            margin: 20px 0 12px 0;
-            color: var(--color-main-text);
-            border-bottom: 1px solid var(--color-border);
-            padding-bottom: 8px;
-        }
-
-        h3 {
-            font-size: 16px;
-            margin: 16px 0 8px 0;
-            color: var(--color-main-text);
-            font-weight: 500;
-        }
-
-        img {
-            max-width: 100%;
-        }
-
-        /* App Header (simplified, no full menu) */
-        .app-header {
-            height: 50px;
-            background: var(--color-primary-element);
-            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
-            position: sticky;
-            top: 0;
-            z-index: 100;
-            display: flex;
-            align-items: center;
-            padding: 0 20px;
-        }
-
-        .app-header__brand {
-            color: white;
-            font-size: 18px;
-            font-weight: 600;
-            text-decoration: none;
-            display: flex;
-            align-items: center;
-            gap: 12px;
-        }
-
-        .app-header__brand:hover {
-            opacity: 0.9;
-        }
-
-        .app-header__logo {
-            height: 32px;
-            width: 32px;
-            fill: white;
-        }
-
-        /* App Layout */
-        .app-content-wrapper {
-            display: flex;
-            height: calc(100vh - 50px);
-            overflow: hidden;
-        }
-
-        /* Side Navigation */
-        #app-navigation {
-            width: 250px;
-            background: var(--color-main-background);
-            border-right: 1px solid var(--color-border);
-            display: flex;
-            flex-direction: column;
-            flex-shrink: 0;
-            transition: margin-left 0.3s ease;
-        }
-
-        #app-navigation.app-navigation--closed {
-            margin-left: -250px;
-        }
-
-        .app-navigation__content {
-            flex: 1;
-            overflow-y: auto;
-            padding: 8px;
-            display: flex;
-            flex-direction: column;
-        }
-
-        .app-navigation-list {
-            list-style: none;
-            padding: 0;
-            margin: 0;
-            flex: 1;
-        }
-
-        .app-navigation-entry {
-            position: relative;
-            margin-bottom: 2px;
-        }
-
-        .app-navigation-entry__wrapper {
-            display: flex;
-            align-items: center;
-            position: relative;
-        }
-
-        .app-navigation-entry-link {
-            display: flex;
-            align-items: center;
-            padding: 0 8px;
-            min-height: var(--default-clickable-area);
-            border-radius: var(--border-radius);
-            transition: background-color 100ms ease-in-out;
-            text-decoration: none;
-            color: var(--color-main-text);
-            flex: 1;
-            font-size: 14px;
-        }
-
-        .app-navigation-entry-link:hover {
-            background-color: var(--color-background-hover);
-        }
-
-        .app-navigation-entry.active .app-navigation-entry-link {
-            background-color: var(--color-primary-element-light);
-            font-weight: 500;
-        }
-
-        .app-navigation-entry-icon {
-            width: var(--default-clickable-area);
-            height: var(--default-clickable-area);
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            margin-right: 0;
-        }
-
-        .app-navigation-entry__name {
-            flex: 1;
-            white-space: nowrap;
-            overflow: hidden;
-            text-overflow: ellipsis;
-        }
-
-        .app-navigation-entry__counter {
-            margin-left: auto;
-            padding: 2px 6px;
-            border-radius: var(--border-radius-pill);
-            background-color: var(--color-background-dark);
-            font-size: 11px;
-            color: var(--color-text-maxcontrast);
-            min-width: 20px;
-            text-align: center;
-        }
-
-        .app-navigation__settings {
-            list-style: none;
-            padding: 8px 0 0 0;
-            margin: 8px 0 0 0;
-            border-top: 1px solid var(--color-border);
-            flex-shrink: 0;
-        }
-
-        .app-navigation-toggle {
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            position: fixed;
-            top: 60px;
-            left: 10px;
-            z-index: 110;
-            background: var(--color-main-background);
-            border: 1px solid var(--color-border);
-            border-radius: var(--border-radius);
-            padding: 8px 12px;
-            cursor: pointer;
-            box-shadow: 0 0 5px rgba(0,0,0,0.1);
-            transition: left 0.3s ease;
-        }
-
-        .app-navigation-toggle:hover {
-            background: var(--color-background-hover);
-        }
-
-        #app-navigation:not(.app-navigation--closed) ~ * .app-navigation-toggle {
-            left: 260px;
-        }
-
-        /* Main Content Area */
-        #app-content {
-            flex: 1;
-            overflow-y: auto;
-            background: var(--color-main-background);
-        }
-
-        .page-content {
-            max-width: 1000px;
-            margin: 0 auto;
-            padding: 24px;
-        }
-
-        .content-section {
-            background: var(--color-main-background);
-            border-radius: 0;
-            padding: 0;
-            box-shadow: none;
-        }
-
-        .content-section h1 {
-            font-size: 24px;
-            font-weight: 600;
-            margin-bottom: 24px;
-        }
-
-        .content-section h2 {
-            font-size: 18px;
-            font-weight: 500;
-            margin: 24px 0 12px 0;
-            border-bottom: none;
-            padding-bottom: 0;
-        }
-
-        .content-section h3 {
-            font-size: 16px;
-            font-weight: 500;
-        }
-
-        /* Responsive */
-        @media (max-width: 768px) {
-            #app-navigation {
-                position: fixed;
-                height: calc(100vh - 50px);
-                z-index: 105;
-                box-shadow: 2px 0 8px rgba(0,0,0,0.1);
-            }
-
-            .page-content {
-                padding: 16px;
-            }
-        }
-
-        /* Footer */
-        footer.page-footer {
-            background-color: #0F0833;
-            color: #ffffff;
-            padding: 40px 0;
-            margin-top: 60px;
-        }
-
-        footer.page-footer .bootstrap-container {
-            max-width: 1200px;
-            margin: 0 auto;
-            padding: 0 20px;
-        }
-
-        footer.page-footer h1 {
-            font-size: 15px;
-            font-weight: bold;
-            line-height: 1.8;
-            color: #ffffff;
-            margin-top: 20px;
-        }
-
-        footer.page-footer ul {
-            list-style-type: none;
-            padding-left: 0;
-        }
-
-        footer.page-footer li {
-            font-size: 13px;
-            line-height: 1.8;
-            color: #ffffff;
-            margin-top: 0;
-        }
-
-        footer.page-footer li a {
-            color: #ffffff;
-            text-decoration: none;
-            display: block;
-            padding: 4px 0;
-        }
-
-        footer.page-footer li a:hover {
-            text-decoration: underline;
-        }
-
-        footer.page-footer p {
-            font-size: 15px;
-            line-height: 1.8;
-            color: #ffffff;
-        }
-
-        footer.page-footer p.copyright {
-            color: rgba(255, 255, 255, 0.5);
-            font-size: 13px;
-            text-align: center;
-            margin-top: 30px;
-        }
-
-        /* Buttons */
-        .btn {
-            border-radius: 50px;
-            padding: 10px 20px;
-            text-decoration: none;
-            display: inline-block;
-            cursor: pointer;
-            border: none;
-            font-size: 14px;
-            transition: all 0.3s;
-        }
-
-        .btn-primary {
-            background: #0082C9;
-            border: 1px solid #0062C9;
-            color: #fff;
-        }
-
-        .btn-primary:hover {
-            background: #006ba3;
-        }
-
-        /* Tables */
-        table {
-            width: 100%;
-            border-collapse: collapse;
-            margin: 20px 0;
-        }
-
-        td {
-            padding: 12px 8px;
-            border-bottom: 1px solid var(--color-border);
-            font-size: 14px;
-        }
-
-        td:first-child {
-            width: 180px;
-            color: var(--color-text-maxcontrast);
-            font-weight: 500;
-        }
-
-        code {
-            background-color: var(--color-background-dark);
-            padding: 2px 6px;
-            border-radius: var(--border-radius);
-            font-family: 'SFMono-Regular', 'Consolas', 'Liberation Mono', 'Menlo', monospace;
-            font-size: 90%;
-            color: var(--color-main-text);
-        }
-
-        /* Badges */
-        .badge {
-            display: inline-block;
-            padding: 3px 8px;
-            border-radius: 12px;
-            font-size: 12px;
-            font-weight: bold;
-            text-transform: uppercase;
-        }
-
-        .badge-oauth {
-            background-color: #4caf50;
-            color: white;
-        }
-
-        .badge-basic {
-            background-color: #2196f3;
-            color: white;
-        }
-
-        /* Messages */
-        .warning {
-            background-color: #fff3cd;
-            border-left: 4px solid #ffc107;
-            padding: 15px;
-            margin: 15px 0;
-            color: #856404;
-        }
-
-        .info-message {
-            background-color: #e3f2fd;
-            border-left: 4px solid #2196f3;
-            padding: 15px;
-            margin: 15px 0;
-            color: #1565c0;
-        }
-
-        .error {
-            background-color: #ffebee;
-            border-left: 4px solid #d32f2f;
-            padding: 15px;
-            margin: 15px 0;
-            color: #c62828;
-        }
-
-        .success {
-            background-color: #e8f5e9;
-            border: 2px solid #4caf50;
-            padding: 30px;
-            border-radius: 8px;
-            text-align: center;
-        }
-
-        .success h1 {
-            color: #4caf50;
-        }
-
-        {% block extra_styles %}{% endblock %}
-    </style>
-</head>
-<body>
-    <!-- App Header -->
-    <header class="app-header">
-        <a href="/app" class="app-header__brand">
-            <svg class="app-header__logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
-                <path d="M255.9 21.04c-11.8 0-22.2 4.08-28.6 10.01-5.6 4.98-8.6 11.41-8.6 18.11 0 5.55 2.2 11.01 5.9 15.48-16.4 4.97-30.1 13.64-39 24.53 22.1-7.67 45.7-11.86 70.3-11.86 24.6 0 48.3 4.19 70.3 11.86-8.9-10.89-22.6-19.56-39-24.53 3.9-4.47 5.9-9.93 5.9-15.48 0-6.7-3-13.13-8.5-18.11-6.4-5.93-16.9-10.01-28.7-10.01zm0 20.34c5.3 0 10.1 1.27 13.6 3.52 1.7 1.16 3.4 2.43 3.4 4.27 0 1.76-1.7 3.03-3.4 4.19-3.5 2.33-8.3 3.61-13.6 3.61-5.3 0-10.1-1.28-13.6-3.61-1.6-1.16-3.3-2.43-3.3-4.19 0-1.84 1.7-3.11 3.3-4.27 3.5-2.25 8.3-3.52 13.6-3.52zm.1 48.1c-110.8 0-200.72 90.02-200.72 200.82S145.2 491 256 491s200.7-89.9 200.7-200.7c0-110.8-89.9-200.82-200.7-200.82zm0 32.62c92.9 0 168.2 75.3 168.2 168.2 0 92.8-75.3 168.2-168.2 168.2-92.9 0-168.26-75.4-168.26-168.2 0-92.9 75.36-168.2 168.26-168.2zm-8.2 6.3c-9.6.5-19 1.9-28.3 4.1l2.3 7.8c8.4-2 17.1-3.3 26-3.8v-8.1zm16.2 0v8.1c9 .5 17.7 1.8 26 3.8l2.2-7.8c-9.1-2.2-18.6-3.6-28.2-4.1zm-60 8.5c-9 3.2-17.6 7-25.8 11.6l4.1 7.1c7.7-4.3 15.6-7.9 23.9-10.8l-2.2-7.9zm103.7 0-2 7.9c8.4 2.9 16.2 6.5 23.8 10.8l4.2-7.1c-8.2-4.6-16.9-8.4-26-11.6zm-143.3 20.3c-7.5 5.4-14.6 11.4-21.1 17.9l5.8 5.8c5.9-6.1 12.5-11.7 19.5-16.6l-4.2-7.1zm182.9 0-4 7.1c6.9 4.9 13.5 10.5 19.5 16.6l5.7-5.8c-6.5-6.5-13.7-12.5-21.2-17.9zm-91.4 11.5c-37 0-67.4 28.6-70.3 64.9l15.9 4.7c.7-29.6 24.7-53.4 54.4-53.4 30.1 0 54.4 24.4 54.4 54.3 0 15-6.2 28.7-16 38.5l.1.1c1.7 2.7 3 5.6 4.1 8.6.9 3 1.7 5.7 2.3 8.6v.4c33.8-16.7 57.2-51.5 57.2-91.7 0-3.8-.2-7.3-.6-10.9-3.2-3.3-6.3-6.4-9.8-9.5 1.5 6.5 2.3 13.4 2.3 20.4 0 28.7-13 54.7-33.5 71.8 6.3-10.6 10.1-23 10.1-36.3 0-38.9-31.7-70.5-70.6-70.5zm-91.8 14.6c-3.3 3.1-6.5 6.2-9.7 9.5-.3 3.6-.5 7.1-.5 10.9 0 7.3.7 14.2 2.1 20.9l9.1 2.7c-2.1-7.5-3.1-15.4-3.1-23.6 0-7 .7-13.9 2.1-20.4zm-31.6 4c-5.8 7.1-10.9 14.6-15.4 22.6l7.1 4c4.1-7.4 8.8-14.3 14-20.8l-5.7-5.8zm246.8 0-5.7 5.8c5.3 6.5 10 13.4 13.9 20.8l7.1-4c-4.4-8-9.5-15.5-15.3-22.6zm-269.2 37.1c-2.5 5.7-4.6 11.4-6.4 17.6l.1-.3c3.4-5 7.9-9.3 12.9-12.5l.3-.6-6.9-4.2zm291.8 0-7.2 4.2c3.2 7.3 5.7 15.1 7.6 23.1l7.9-2.1c-2.1-8.8-4.9-17.3-8.3-25.2zm-261.2 11.5c-13.4.1-25.7 9-29.7 22.5l114.8 34.2c-4.9 16.7 4.6 34.2 21.2 39.2L361.7 366c16.6 5 34.1-4.4 39.1-21l-114.6-34.4c4.9-16.5-4.7-34.1-21.3-39.1 0 0-72.4-21.5-114.8-34.3-3.1-.9-6.3-1.4-9.4-1.3zm-42.09 29.7c-.9 6.9-1.4 14-1.4 21.3 0 1.3.1 2.9.1 4.2h8.09v-4.2c0-6.5.4-12.9 1.2-19.2l-7.99-2.1zm314.59 0-7.9 2.1c.7 6.3 1.3 12.7 1.3 19.2 0 1.3 0 2.9-.2 4.2h8.2v-4.2c0-7.3-.5-14.4-1.4-21.3zm-157.3 24.7c6.3 0 11.5 5 11.5 11.3 0 6.4-5.2 11.6-11.5 11.6s-11.5-5.2-11.5-11.6c0-6.3 5.2-11.3 11.5-11.3zM98.51 307.4c1 8.2 2.89 16.4 5.09 24.3l7.9-2.1c-2.1-7.2-3.8-14.6-4.8-22.2h-8.19zm306.69 0c-1.1 7.6-2.7 15-4.8 22.2l7.8 2.1c2.2-7.9 4.1-16.1 5.2-24.3h-8.2zm-191.3 10.9c-19 13.3-31.4 35.3-31.4 60.1 0 10.4 2.3 20.4 6.2 29.7 8.8 4.9 17.9 8.8 27.6 11.7-10.8-10.7-17.5-25.2-17.5-41.4 0-19 9.3-36 23.7-46.3-3.8-4.1-6.7-8.7-8.6-13.8zM116.8 345l-7.9 2c3.1 7.6 6.8 14.7 11 21.6l6.9-4.2c-3.8-6.2-7-12.8-10-19.4zm194.8 20.5c.9 4.1 1.4 8.5 1.4 12.9 0 16.2-6.7 30.7-17.4 41.4 9.6-2.9 18.8-6.8 27.5-11.7 4-9.3 6.2-19.3 6.2-29.7 0-2.7-.2-5.2-.4-7.7l-17.3-5.2zM136 377.9l-7.1 4.1c4.7 6.2 9.7 12.1 15.3 17.3l5.7-5.5c-5.1-5-9.7-10.3-13.9-15.9zm243.9 2.3-.2.1c-2.1.3-4 .6-6.2.7h-.1c-3.6 4.5-7.3 8.8-11.5 12.8l5.8 5.5c5.5-5.2 10.5-11.1 15.2-17.3l-3-1.8zm-217.8 24-5.9 5.9c6 4.8 12.2 9.7 18.8 13.6l3.8-7.8c-5.7-2.9-11.4-6.8-16.7-11.7zm187.7 0c-5.4 4.9-11.1 8.8-16.8 11.7l3.9 7.8c6.5-3.9 12.8-8.8 18.7-13.6l-5.8-5.9zm-156.4 19.5-4.1 6.8c6.6 4 13.7 5.8 20.7 8.8l2.2-7.9c-6.5-1.9-12.7-4.8-18.8-7.7zm125.2 0c-6.2 2.9-12.5 5.8-19.1 7.7l2.3 7.9c7.2-3 14-4.8 20.7-8.8l-3.9-6.8zm-90.7 11.7-2 7.8c7.1 1 14.5 1.9 21.9 1.9v-7.7c-6.8 0-13.5-1.1-19.9-2zm55.9 0c-6.3.9-13 2-19.8 2v7.7c7.5 0 14.8-.9 22.1-1.9l-2.3-7.8z" fill="#fff"/>
-            </svg>
-            <span>Nextcloud MCP Server</span>
-        </a>
-    </header>
-
-    <!-- App Content Wrapper (Sidebar + Main Content) -->
-    {% block content %}{% endblock %}
-
-    {% block scripts %}{% endblock %}
-</body>
-</html>

nextcloud_mcp_server/auth/templates/error.html

@@ -1,19 +0,0 @@
-{% extends "base.html" %}
-
-{% block title %}{{ error_title|default('Error') }} - Nextcloud MCP Server{% endblock %}
-
-{% block content %}
-<h1>{{ error_title|default('Error') }}</h1>
-
-<div class="error">
-    <strong>Error:</strong> {{ error_message }}
-</div>
-
-{% if login_url %}
-<p><a href="{{ login_url }}" class="btn btn-primary">Login again</a></p>
-{% endif %}
-
-{% if back_url %}
-<p><a href="{{ back_url }}" class="btn">Go Back</a></p>
-{% endif %}
-{% endblock %}

nextcloud_mcp_server/auth/templates/success.html

@@ -1,21 +0,0 @@
-{% extends "base.html" %}
-
-{% block title %}{{ success_title|default('Success') }} - Nextcloud MCP Server{% endblock %}
-
-{% block extra_head %}
-{% if redirect_url and redirect_delay %}
-<meta http-equiv="refresh" content="{{ redirect_delay }};url={{ redirect_url }}">
-{% endif %}
-{% endblock %}
-
-{% block content %}
-<div class="success">
-    <h1>{{ success_title|default('✓ Success') }}</h1>
-    {% for message in success_messages %}
-    <p>{{ message }}</p>
-    {% endfor %}
-    {% if redirect_url %}
-    <p>Redirecting...</p>
-    {% endif %}
-</div>
-{% endblock %}

nextcloud_mcp_server/auth/templates/user_info.html

@@ -1,650 +0,0 @@
-{% extends "base.html" %}
-
-{% block title %}Nextcloud MCP Server{% endblock %}
-
-{% block extra_head %}
-    <!-- htmx for dynamic loading -->
-    <script src="https://unpkg.com/htmx.org@1.9.10"></script>
-
-    <!-- Alpine.js for state management -->
-    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
-
-    <!-- Plotly.js for vector visualization -->
-    <script src="https://cdn.plot.ly/plotly-3.3.0.min.js"></script>
-
-    <!-- Vector Viz static assets -->
-    <link rel="stylesheet" href="/app/static/vector-viz.css">
-{% endblock %}
-
-{% block extra_styles %}
-    /* Smooth htmx transitions */
-    .htmx-swapping {
-        opacity: 0;
-        transition: opacity 200ms ease-out;
-    }
-
-    .htmx-settling {
-        opacity: 1;
-        transition: opacity 200ms ease-in;
-    }
-
-    /* Logout button styling */
-    .logout-section {
-        margin-top: 20px;
-        padding-top: 20px;
-        border-top: 1px solid var(--color-border);
-    }
-
-    /* Welcome tab specific styles */
-    .hero-section {
-        background: linear-gradient(135deg, var(--color-primary-element) 0%, #0082c9 100%);
-        color: white;
-        padding: 60px 24px;
-        margin: -24px -24px 40px -24px;
-        border-radius: 0 0 var(--border-radius-large) var(--border-radius-large);
-        text-align: center;
-    }
-
-    .hero-section h1 {
-        color: white;
-        font-size: 36px;
-        margin: 0 0 16px 0;
-        font-weight: 600;
-    }
-
-    .hero-section p {
-        font-size: 18px;
-        opacity: 0.95;
-        max-width: 700px;
-        margin: 0 auto;
-        line-height: 1.6;
-    }
-
-    .feature-grid {
-        display: grid;
-        grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-        gap: 24px;
-        margin: 32px 0;
-    }
-
-    .feature-card {
-        background: var(--color-main-background);
-        border: 2px solid var(--color-border);
-        border-radius: var(--border-radius-large);
-        padding: 24px;
-        transition: all 0.2s;
-        cursor: pointer;
-        text-decoration: none;
-        color: inherit;
-        display: block;
-    }
-
-    .feature-card:hover {
-        border-color: var(--color-primary-element);
-        box-shadow: 0 4px 12px rgba(0, 103, 158, 0.15);
-        transform: translateY(-2px);
-    }
-
-    .feature-card h3 {
-        color: var(--color-primary-element);
-        font-size: 20px;
-        margin: 12px 0 8px 0;
-        font-weight: 600;
-        display: flex;
-        align-items: center;
-        gap: 12px;
-    }
-
-    .feature-card p {
-        color: var(--color-text-maxcontrast);
-        font-size: 14px;
-        line-height: 1.6;
-        margin: 8px 0 0 0;
-    }
-
-    .feature-icon {
-        width: 48px;
-        height: 48px;
-        background: var(--color-primary-element-light);
-        border-radius: var(--border-radius);
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        margin-bottom: 8px;
-    }
-
-    .feature-icon svg {
-        width: 28px;
-        height: 28px;
-        fill: var(--color-primary-element);
-    }
-
-    .info-section {
-        background: var(--color-background-hover);
-        border-radius: var(--border-radius-large);
-        padding: 32px;
-        margin: 32px 0;
-    }
-
-    .info-section h2 {
-        color: var(--color-main-text);
-        font-size: 24px;
-        margin: 0 0 16px 0;
-        border: none;
-        padding: 0;
-    }
-
-    .info-section p {
-        color: var(--color-text-maxcontrast);
-        line-height: 1.7;
-        margin: 12px 0;
-    }
-
-    .info-section ul {
-        margin: 12px 0;
-        padding-left: 24px;
-    }
-
-    .info-section li {
-        color: var(--color-text-maxcontrast);
-        line-height: 1.7;
-        margin: 8px 0;
-    }
-
-    .info-section code {
-        background: var(--color-main-background);
-        padding: 2px 8px;
-        border-radius: var(--border-radius);
-        font-size: 13px;
-    }
-
-    .auth-status {
-        background: var(--color-primary-element-light);
-        border-left: 4px solid var(--color-primary-element);
-        padding: 16px 20px;
-        margin: 24px 0;
-        border-radius: var(--border-radius);
-        display: flex;
-        align-items: center;
-        gap: 12px;
-    }
-
-    .auth-status svg {
-        width: 24px;
-        height: 24px;
-        fill: var(--color-primary-element);
-        flex-shrink: 0;
-    }
-
-    .auth-status-text {
-        flex: 1;
-    }
-
-    .auth-status-text strong {
-        display: block;
-        color: var(--color-main-text);
-        font-size: 14px;
-        margin-bottom: 4px;
-    }
-
-    .auth-status-text span {
-        color: var(--color-text-maxcontrast);
-        font-size: 13px;
-    }
-{% endblock %}
-
-{% block content %}
-<div class="app-content-wrapper" x-data="{ activeSection: 'welcome', navOpen: true }">
-    <!-- Side Navigation -->
-    <nav id="app-navigation" :class="{ 'app-navigation--closed': !navOpen }">
-        <div class="app-navigation__content">
-            <!-- Navigation List -->
-            <ul class="app-navigation-list">
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'welcome' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'welcome'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M10,20V14H14V20H19V12H22L12,3L2,12H5V20H10Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Welcome</span>
-                        </a>
-                    </div>
-                </li>
-
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'user-info' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'user-info'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">User Info</span>
-                        </a>
-                    </div>
-                </li>
-
-                {% if show_vector_sync_tab %}
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'vector-sync' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'vector-sync'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M12,18A6,6 0 0,1 6,12C6,11 6.25,10.03 6.7,9.2L5.24,7.74C4.46,8.97 4,10.43 4,12A8,8 0 0,0 12,20V23L16,19L12,15M12,4V1L8,5L12,9V6A6,6 0 0,1 18,12C18,13 17.75,13.97 17.3,14.8L18.76,16.26C19.54,15.03 20,13.57 20,12A8,8 0 0,0 12,4Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Vector Sync</span>
-                        </a>
-                    </div>
-                </li>
-
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'vector-viz' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'vector-viz'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M22,21H2V3H4V19H6V10H10V19H12V6H16V19H18V14H22V21Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Vector Viz</span>
-                        </a>
-                    </div>
-                </li>
-                {% endif %}
-
-                {% if show_webhooks_tab %}
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'webhooks' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'webhooks'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M10.59,13.41C11,13.8 11,14.44 10.59,14.83C10.2,15.22 9.56,15.22 9.17,14.83C7.22,12.88 7.22,9.71 9.17,7.76V7.76L12.71,4.22C14.66,2.27 17.83,2.27 19.78,4.22C21.73,6.17 21.73,9.34 19.78,11.29L18.29,12.78C18.3,11.96 18.17,11.14 17.89,10.36L18.36,9.88C19.54,8.71 19.54,6.81 18.36,5.64C17.19,4.46 15.29,4.46 14.12,5.64L10.59,9.17C9.41,10.34 9.41,12.24 10.59,13.41M13.41,9.17C13.8,8.78 14.44,8.78 14.83,9.17C16.78,11.12 16.78,14.29 14.83,16.24V16.24L11.29,19.78C9.34,21.73 6.17,21.73 4.22,19.78C2.27,17.83 2.27,14.66 4.22,12.71L5.71,11.22C5.7,12.04 5.83,12.86 6.11,13.65L5.64,14.12C4.46,15.29 4.46,17.19 5.64,18.36C6.81,19.54 8.71,19.54 9.88,18.36L13.41,14.83C14.59,13.66 14.59,11.76 13.41,10.59C13,10.2 13,9.56 13.41,9.17Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Webhooks</span>
-                        </a>
-                    </div>
-                </li>
-                {% endif %}
-            </ul>
-
-            <!-- Settings/Logout at bottom -->
-            {% if logout_url %}
-            <ul class="app-navigation__settings">
-                <li class="app-navigation-entry">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="{{ logout_url }}" class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M16,17V14H9V10H16V7L21,12L16,17M14,2A2,2 0 0,1 16,4V6H14V4H5V20H14V18H16V20A2,2 0 0,1 14,22H5A2,2 0 0,1 3,20V4A2,2 0 0,1 5,2H14Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Logout</span>
-                        </a>
-                    </div>
-                </li>
-            </ul>
-            {% endif %}
-        </div>
-
-        <!-- Toggle Button (mobile) -->
-        <button @click="navOpen = !navOpen"
-                class="app-navigation-toggle"
-                :aria-expanded="navOpen.toString()">
-            ☰
-        </button>
-    </nav>
-
-    <!-- Main Content Area -->
-    <main id="app-content">
-        <div class="page-content">
-            <!-- Welcome Section -->
-            <div x-show="activeSection === 'welcome'">
-                <!-- Hero Section -->
-                <div class="hero-section">
-                    <h1>Welcome to Nextcloud MCP Server</h1>
-                    <p>
-                        Interactive user interface for semantic search and document retrieval.
-                        Test queries, visualize results, and explore your Nextcloud content using RAG workflows.
-                    </p>
-                </div>
-
-                <!-- Authentication Status -->
-                <div class="auth-status">
-                    <svg viewBox="0 0 24 24">
-                        <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                    </svg>
-                    <div class="auth-status-text">
-                        <strong>Authenticated as: {{ username }}</strong>
-                        <span>Authentication mode: <code>{{ auth_mode }}</code></span>
-                    </div>
-                </div>
-
-                {% if vector_sync_enabled %}
-                <!-- Vector Sync Enabled Content -->
-                <div class="info-section">
-                    <h2>About Semantic Search</h2>
-                    <p>
-                        This interface provides access to <strong>semantic search</strong> capabilities powered by vector embeddings.
-                        Unlike traditional keyword search, semantic search understands the <em>meaning</em> of your queries and finds
-                        conceptually similar content across your Nextcloud apps.
-                    </p>
-                    <p>
-                        <strong>How it works:</strong>
-                    </p>
-                    <ul>
-                        <li>Documents from Notes, Calendar, Files, Contacts, and Deck are indexed into a vector database</li>
-                        <li>Each document chunk is converted to a 768-dimensional vector embedding that captures semantic meaning</li>
-                        <li>Queries are also converted to embeddings and matched against document vectors using similarity search</li>
-                        <li>Results can be retrieved using pure semantic search or hybrid BM25 search combining keywords and semantics</li>
-                    </ul>
-                </div>
-
-                <div class="info-section">
-                    <h2>RAG Workflow Integration</h2>
-                    <p>
-                        This UI allows you to <strong>test the same queries that Large Language Models (LLMs) would use</strong> in a
-                        Retrieval-Augmented Generation (RAG) workflow. When an AI assistant needs to answer questions about your data:
-                    </p>
-                    <ul>
-                        <li><strong>Step 1:</strong> The assistant converts your question into a search query</li>
-                        <li><strong>Step 2:</strong> The MCP server retrieves relevant document chunks using semantic search</li>
-                        <li><strong>Step 3:</strong> Retrieved context is passed to the LLM to generate an informed answer</li>
-                    </ul>
-
-                    <!-- RAG Workflow Diagram -->
-                    <div style="background: var(--color-main-background); border: 2px solid var(--color-primary-element); border-radius: var(--border-radius-large); padding: 24px; margin: 24px 0; overflow-x: auto;">
-                        <div style="text-align: center; font-weight: 600; margin-bottom: 20px; color: var(--color-primary-element); font-size: 16px;">
-                            MCP Sampling RAG Workflow
-                        </div>
-
-                        <!-- Four-component bidirectional flow -->
-                        <div style="max-width: 1000px; margin: 0 auto;">
-                            <div style="display: grid; grid-template-columns: 0.7fr auto 1fr auto 1fr auto 0.9fr; gap: 10px; align-items: center;">
-                                <!-- User -->
-                                <div style="background: var(--color-background-hover); border: 2px solid var(--color-border); border-radius: var(--border-radius-large); padding: 14px; text-align: center;">
-                                    <div style="font-size: 26px; margin-bottom: 5px;">👤</div>
-                                    <div style="font-weight: 600; color: var(--color-main-text); font-size: 12px;">User</div>
-                                    <div style="font-size: 9px; color: var(--color-text-maxcontrast); font-style: italic; margin-top: 5px; line-height: 1.2;">
-                                        "What are health<br>benefits of coffee?"
-                                    </div>
-                                </div>
-
-                                <!-- Arrow User <-> Client -->
-                                <div style="text-align: center;">
-                                    <div style="font-size: 20px; color: var(--color-text-maxcontrast);">↔</div>
-                                </div>
-
-                                <!-- MCP Client + LLM (combined) -->
-                                <div style="background: var(--color-primary-element-light); border: 2px solid var(--color-primary-element); border-radius: var(--border-radius-large); padding: 12px; text-align: center;">
-                                    <div style="font-weight: 600; color: var(--color-primary-element); font-size: 13px; margin-bottom: 8px;">MCP Client + LLM</div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 8px; margin-bottom: 6px;">
-                                        <div style="font-size: 9px; color: var(--color-text-maxcontrast);">(Claude Code)</div>
-                                    </div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 8px; border: 2px solid var(--color-primary-element);">
-                                        <div style="font-size: 16px; margin-bottom: 2px;">🧠</div>
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 10px;">Client's LLM</div>
-                                        <div style="font-size: 8px; color: var(--color-text-maxcontrast);">(Claude)</div>
-                                    </div>
-
-                                    <div style="margin-top: 8px; font-size: 8px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                        <strong>Enables RAG:</strong><br>
-                                        Receives context,<br>
-                                        generates answer
-                                    </div>
-                                </div>
-
-                                <!-- Arrow Client <-> Server -->
-                                <div style="text-align: center;">
-                                    <div style="font-size: 20px; color: var(--color-primary-element);">↔</div>
-                                    <div style="font-size: 7px; color: var(--color-text-maxcontrast); margin-top: 2px; font-weight: 600; line-height: 1.1;">
-                                        Query +<br>
-                                        Sampling
-                                    </div>
-                                </div>
-
-                                <!-- MCP Server -->
-                                <div style="background: var(--color-primary-element-light); border: 2px solid var(--color-primary-element); border-radius: var(--border-radius-large); padding: 12px; text-align: center;">
-                                    <div style="font-weight: 600; color: var(--color-primary-element); font-size: 13px; margin-bottom: 8px;">MCP Server</div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 7px; margin-bottom: 5px;">
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 9px; margin-bottom: 2px;">1. Semantic Search</div>
-                                        <div style="font-size: 7px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                            Vector embeddings<br>
-                                            BM25 Hybrid + RRF
-                                        </div>
-                                    </div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 7px; margin-bottom: 5px;">
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 9px; margin-bottom: 2px;">2. Retrieve Context</div>
-                                        <div style="font-size: 7px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                            Top relevant docs<br>
-                                            with scores
-                                        </div>
-                                    </div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 7px; margin-bottom: 5px;">
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 9px; margin-bottom: 2px;">3. Format Response</div>
-                                        <div style="font-size: 7px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                            Document chunks<br>
-                                            with citations
-                                        </div>
-                                    </div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 7px;">
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 9px; margin-bottom: 2px;">4. Send to LLM</div>
-                                        <div style="font-size: 7px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                            Via MCP sampling<br>
-                                            for answer generation
-                                        </div>
-                                    </div>
-                                </div>
-
-                                <!-- Arrow Server <-> Nextcloud -->
-                                <div style="text-align: center;">
-                                    <div style="font-size: 20px; color: var(--color-primary-element);">↔</div>
-                                    <div style="font-size: 7px; color: var(--color-text-maxcontrast); margin-top: 2px; font-weight: 600; line-height: 1.1;">
-                                        Retrieve
-                                    </div>
-                                </div>
-
-                                <!-- Nextcloud -->
-                                <div style="background: var(--color-background-hover); border: 2px solid var(--color-border); border-radius: var(--border-radius-large); padding: 12px; text-align: center; position: relative;">
-                                    <img src="/app/static/nextcloud-logo.png" alt="Nextcloud" style="width: 40px; height: 40px; margin-bottom: 6px;" />
-                                    <div style="font-weight: 600; color: var(--color-main-text); font-size: 12px; margin-bottom: 4px;">Nextcloud</div>
-                                    <div style="font-size: 8px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                        Notes, Calendar,<br>
-                                        Files, Contacts,<br>
-                                        Deck
-                                    </div>
-                                </div>
-                            </div>
-
-                            <!-- Explanation below diagram -->
-                            <div style="margin-top: 24px; padding: 16px; background: var(--color-background-hover); border-radius: var(--border-radius); border-left: 4px solid var(--color-primary-element);">
-                                <div style="font-size: 12px; color: var(--color-main-text); line-height: 1.6;">
-                                    <strong>How RAG works via MCP Sampling:</strong>
-                                </div>
-                                <ol style="margin: 8px 0 0 0; padding-left: 20px; font-size: 11px; color: var(--color-text-maxcontrast); line-height: 1.6;">
-                                    <li>User asks question through MCP Client</li>
-                                    <li>Client sends query to MCP Server</li>
-                                    <li>Server retrieves relevant document context from Nextcloud</li>
-                                    <li><strong>Server sends context back to Client's LLM</strong> (MCP Sampling)</li>
-                                    <li>Client's LLM generates answer with citations using retrieved context</li>
-                                    <li>Answer returned to user</li>
-                                </ol>
-                                <div style="margin-top: 8px; font-size: 10px; color: var(--color-text-maxcontrast); font-style: italic;">
-                                    The server has no LLM - it only retrieves context. The client's existing LLM is reused for answer generation.
-                                </div>
-                            </div>
-                        </div>
-                    </div>
-
-                    <p style="margin-top: 16px;">
-                        <strong>Key Point:</strong> The MCP server retrieves context but doesn't generate answers itself.
-                        Through <strong>MCP sampling</strong>, it requests the client's LLM to generate responses, giving users
-                        full control over which model is used and ensuring all processing happens client-side.
-                    </p>
-
-                    <p>
-                        By using this interface, you can preview search results, understand relevance scores, and verify
-                        that the system retrieves the right information before it reaches the LLM.
-                    </p>
-                </div>
-
-                <!-- Feature Cards -->
-                <h2>Available Features</h2>
-                <div class="feature-grid">
-                    <a href="#" @click.prevent="activeSection = 'user-info'" class="feature-card">
-                        <div class="feature-icon">
-                            <svg viewBox="0 0 24 24">
-                                <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                            </svg>
-                        </div>
-                        <h3>User Information</h3>
-                        <p>
-                            View your authentication details, session information, and IdP profile.
-                            Manage background access permissions.
-                        </p>
-                    </a>
-
-                    <a href="#" @click.prevent="activeSection = 'vector-sync'" class="feature-card">
-                        <div class="feature-icon">
-                            <svg viewBox="0 0 24 24">
-                                <path d="M12,18A6,6 0 0,1 6,12C6,11 6.25,10.03 6.7,9.2L5.24,7.74C4.46,8.97 4,10.43 4,12A8,8 0 0,0 12,20V23L16,19L12,15M12,4V1L8,5L12,9V6A6,6 0 0,1 18,12C18,13 17.75,13.97 17.3,14.8L18.76,16.26C19.54,15.03 20,13.57 20,12A8,8 0 0,0 12,4Z" />
-                            </svg>
-                        </div>
-                        <h3>Vector Sync Status</h3>
-                        <p>
-                            Monitor real-time indexing progress with metrics for indexed documents, pending queue,
-                            and synchronization status.
-                        </p>
-                    </a>
-
-                    <a href="#" @click.prevent="activeSection = 'vector-viz'" class="feature-card">
-                        <div class="feature-icon">
-                            <svg viewBox="0 0 24 24">
-                                <path d="M22,21H2V3H4V19H6V10H10V19H12V6H16V19H18V14H22V21Z" />
-                            </svg>
-                        </div>
-                        <h3>Vector Visualization</h3>
-                        <p>
-                            Interactive search interface with 2D PCA visualization. Compare algorithms,
-                            view relevance scores, and explore matched document chunks.
-                        </p>
-                    </a>
-                </div>
-
-                {% else %}
-                <!-- Vector Sync Disabled Content -->
-                <div class="warning">
-                    <h3 style="margin-top: 0;">Vector Sync is Disabled</h3>
-                    <p>
-                        Semantic search and vector visualization features are currently disabled.
-                        To enable these features, set <code>VECTOR_SYNC_ENABLED=true</code> in your environment configuration.
-                    </p>
-                    <p style="margin-bottom: 0;">
-                        <strong>Learn more:</strong>
-                        <a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md" target="_blank" style="color: inherit; text-decoration: underline;">
-                            Configuration Guide
-                        </a>
-                    </p>
-                </div>
-
-                <!-- Limited Feature Card -->
-                <h2>Available Features</h2>
-                <div class="feature-grid">
-                    <a href="#" @click.prevent="activeSection = 'user-info'" class="feature-card">
-                        <div class="feature-icon">
-                            <svg viewBox="0 0 24 24">
-                                <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                            </svg>
-                        </div>
-                        <h3>User Information</h3>
-                        <p>
-                            View your authentication details, session information, and IdP profile.
-                            Manage background access permissions.
-                        </p>
-                    </a>
-                </div>
-                {% endif %}
-
-                <!-- Documentation Section -->
-                <div class="info-section" style="margin-top: 40px;">
-                    <h2>Documentation</h2>
-                    <p>
-                        For detailed information about configuration, authentication modes, and advanced features,
-                        please refer to the project documentation:
-                    </p>
-                    <ul>
-                        <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md" target="_blank">Installation Guide</a></li>
-                        <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md" target="_blank">Configuration Options</a></li>
-                        <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/authentication.md" target="_blank">Authentication Modes</a></li>
-                        {% if vector_sync_enabled %}
-                        <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/user-guide/vector-sync-ui.md" target="_blank">Vector Sync UI Guide</a></li>
-                        {% endif %}
-                    </ul>
-                </div>
-            </div>
-
-            <!-- User Info Section -->
-            <div x-show="activeSection === 'user-info'">
-                <div class="content-section">
-                    <h1>User Information</h1>
-                    {{ user_info_tab_html|safe }}
-                </div>
-            </div>
-
-            {% if show_vector_sync_tab %}
-            <!-- Vector Sync Section -->
-            <div x-show="activeSection === 'vector-sync'">
-                <div class="content-section">
-                    <h1>Vector Sync Status</h1>
-                    {{ vector_sync_tab_html|safe }}
-                </div>
-            </div>
-
-            <!-- Vector Viz Section -->
-            <div x-show="activeSection === 'vector-viz'">
-                <div class="content-section">
-                    <h1>Vector Visualization</h1>
-                    <div hx-get="/app/vector-viz" hx-trigger="load" hx-swap="outerHTML">
-                        <p style="color: #999;">Loading vector visualization...</p>
-                    </div>
-                </div>
-            </div>
-            {% endif %}
-
-            {% if show_webhooks_tab %}
-            <!-- Webhooks Section -->
-            <div x-show="activeSection === 'webhooks'">
-                <div class="content-section">
-                    <h1>Webhook Management</h1>
-                    {{ webhooks_tab_html|safe }}
-                </div>
-            </div>
-            {% endif %}
-        </div>
-    </main>
-</div>
-
-<script>
-    // Set global Nextcloud base URL for use in external JS
-    window.NEXTCLOUD_BASE_URL = '{{ nextcloud_host_for_links }}';
-</script>
-<script src="/app/static/vector-viz.js"></script>
-{% endblock %}

nextcloud_mcp_server/auth/templates/vector_viz.html

@@ -1,184 +0,0 @@
-<div x-data="vizApp()">
-    <div class="viz-layout">
-        <!-- Top: Search Controls -->
-        <div class="viz-card viz-controls-card">
-            <form @submit.prevent="executeSearch">
-                <div class="viz-controls-grid">
-                    <div class="viz-control-group">
-                        <label>Search Query</label>
-                        <input type="text" x-model="query" placeholder="Enter search query..." required />
-                    </div>
-
-                    <div class="viz-control-group">
-                        <label>Algorithm</label>
-                        <select x-model="algorithm">
-                            <option value="semantic">Semantic (Dense)</option>
-                            <option value="bm25_hybrid" selected>BM25 Hybrid</option>
-                        </select>
-                    </div>
-
-                    <div class="viz-control-group">
-                        <label>Fusion</label>
-                        <select x-model="fusion" :disabled="algorithm !== 'bm25_hybrid'" :style="algorithm !== 'bm25_hybrid' ? 'opacity: 0.5; cursor: not-allowed;' : ''">
-                            <option value="rrf" selected>RRF</option>
-                            <option value="dbsf">DBSF</option>
-                        </select>
-                    </div>
-
-                    <div class="viz-control-group">
-                        <label>&nbsp;</label>
-                        <button type="submit" class="viz-btn">Search</button>
-                    </div>
-
-                    <div class="viz-control-group">
-                        <label>&nbsp;</label>
-                        <button type="button" class="viz-btn-secondary" @click="showAdvanced = !showAdvanced">
-                            <span x-text="showAdvanced ? 'Hide' : 'Advanced'"></span>
-                        </button>
-                    </div>
-                </div>
-
-                <!-- Advanced Options (Collapsible) -->
-                <div x-show="showAdvanced" style="margin-top: 16px;">
-                    <div class="viz-controls-grid" style="grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));">
-                        <div class="viz-control-group">
-                            <label>Document Types</label>
-                            <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 8px; font-size: 13px;">
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="" style="margin-right: 4px;">
-                                    <span>All</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="note" style="margin-right: 4px;">
-                                    <span>Notes</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="file" style="margin-right: 4px;">
-                                    <span>Files</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="calendar" style="margin-right: 4px;">
-                                    <span>Calendar</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="contact" style="margin-right: 4px;">
-                                    <span>Contacts</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <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>
-
-                        <div class="viz-control-group">
-                            <label>Score Threshold</label>
-                            <input type="number" x-model.number="scoreThreshold" min="0" max="1" step="any" />
-                        </div>
-
-                        <div class="viz-control-group">
-                            <label>Result Limit</label>
-                            <input type="number" x-model.number="limit" min="1" max="1000" />
-                        </div>
-
-                        <div class="viz-control-group">
-                            <label>Display Options</label>
-                            <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal; margin-top: 4px;">
-                                <input type="checkbox" x-model="showQueryPoint" @change="updatePlot()" style="margin-right: 6px;">
-                                <span>Show Query Point</span>
-                            </label>
-                        </div>
-                    </div>
-                </div>
-            </form>
-        </div>
-
-        <!-- Plot -->
-        <div class="viz-card viz-card-plot">
-            <div id="viz-plot-container">
-                <div x-show="loading" class="viz-loading-overlay" x-transition.opacity.duration.200ms>
-                    Executing search and computing PCA projection...
-                </div>
-                <div id="viz-plot" x-show="!loading" x-transition.opacity.duration.200ms></div>
-            </div>
-        </div>
-
-        <!-- Results -->
-        <div class="viz-card" style="flex: 0 0 auto;">
-            <h3 style="margin-top: 0;">Search Results (<span x-text="loading ? '...' : results.length"></span>)</h3>
-
-        <div x-show="loading" class="viz-loading" x-transition.opacity.duration.200ms>
-            Loading results...
-        </div>
-
-        <div x-show="!loading && results.length === 0" class="viz-no-results" x-transition.opacity.duration.200ms>
-            No results found. Try a different query or adjust your search parameters.
-        </div>
-
-        <template x-if="!loading && results.length > 0">
-            <div x-transition.opacity.duration.200ms>
-                <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.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) |
-                            Type: <span x-text="result.doc_type"></span>
-                        </div>
-
-                        <!-- Show Chunk button (only if chunk position is available) -->
-                        <template x-if="hasChunkPosition(result)">
-                            <button
-                                class="chunk-toggle-btn"
-                                @click="toggleChunk(result)"
-                                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}_${result.chunk_start_offset || 0}`)">
-                            <div class="chunk-context" x-transition.opacity.duration.200ms>
-                                <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}_${result.chunk_start_offset || 0}`]">
-                                    <div>
-                                        <!-- 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}_${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>
-                                </template>
-                            </div>
-                        </template>
-                    </div>
-                </template>
-            </div>
-        </template>
-        </div><!-- Search Results -->
-    </div><!-- .viz-layout -->
-</div><!-- x-data="vizApp()" -->

nextcloud_mcp_server/auth/templates/welcome.html

@@ -1,392 +0,0 @@
-{% extends "base.html" %}
-
-{% block title %}Welcome - Nextcloud MCP Server{% endblock %}
-
-{% block extra_head %}
-    <!-- Alpine.js for interactive elements -->
-    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
-{% endblock %}
-
-{% block extra_styles %}
-    /* Welcome page specific styles */
-    .hero-section {
-        background: linear-gradient(135deg, var(--color-primary-element) 0%, #0082c9 100%);
-        color: white;
-        padding: 60px 24px;
-        margin: -24px -24px 40px -24px;
-        border-radius: 0 0 var(--border-radius-large) var(--border-radius-large);
-        text-align: center;
-    }
-
-    .hero-section h1 {
-        color: white;
-        font-size: 36px;
-        margin: 0 0 16px 0;
-        font-weight: 600;
-    }
-
-    .hero-section p {
-        font-size: 18px;
-        opacity: 0.95;
-        max-width: 700px;
-        margin: 0 auto;
-        line-height: 1.6;
-    }
-
-    .feature-grid {
-        display: grid;
-        grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-        gap: 24px;
-        margin: 32px 0;
-    }
-
-    .feature-card {
-        background: var(--color-main-background);
-        border: 2px solid var(--color-border);
-        border-radius: var(--border-radius-large);
-        padding: 24px;
-        transition: all 0.2s;
-        cursor: pointer;
-        text-decoration: none;
-        color: inherit;
-        display: block;
-    }
-
-    .feature-card:hover {
-        border-color: var(--color-primary-element);
-        box-shadow: 0 4px 12px rgba(0, 103, 158, 0.15);
-        transform: translateY(-2px);
-    }
-
-    .feature-card h3 {
-        color: var(--color-primary-element);
-        font-size: 20px;
-        margin: 12px 0 8px 0;
-        font-weight: 600;
-        display: flex;
-        align-items: center;
-        gap: 12px;
-    }
-
-    .feature-card p {
-        color: var(--color-text-maxcontrast);
-        font-size: 14px;
-        line-height: 1.6;
-        margin: 8px 0 0 0;
-    }
-
-    .feature-icon {
-        width: 48px;
-        height: 48px;
-        background: var(--color-primary-element-light);
-        border-radius: var(--border-radius);
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        margin-bottom: 8px;
-    }
-
-    .feature-icon svg {
-        width: 28px;
-        height: 28px;
-        fill: var(--color-primary-element);
-    }
-
-    .info-section {
-        background: var(--color-background-hover);
-        border-radius: var(--border-radius-large);
-        padding: 32px;
-        margin: 32px 0;
-    }
-
-    .info-section h2 {
-        color: var(--color-main-text);
-        font-size: 24px;
-        margin: 0 0 16px 0;
-        border: none;
-        padding: 0;
-    }
-
-    .info-section p {
-        color: var(--color-text-maxcontrast);
-        line-height: 1.7;
-        margin: 12px 0;
-    }
-
-    .info-section ul {
-        margin: 12px 0;
-        padding-left: 24px;
-    }
-
-    .info-section li {
-        color: var(--color-text-maxcontrast);
-        line-height: 1.7;
-        margin: 8px 0;
-    }
-
-    .info-section code {
-        background: var(--color-main-background);
-        padding: 2px 8px;
-        border-radius: var(--border-radius);
-        font-size: 13px;
-    }
-
-    .auth-status {
-        background: var(--color-primary-element-light);
-        border-left: 4px solid var(--color-primary-element);
-        padding: 16px 20px;
-        margin: 24px 0;
-        border-radius: var(--border-radius);
-        display: flex;
-        align-items: center;
-        gap: 12px;
-    }
-
-    .auth-status svg {
-        width: 24px;
-        height: 24px;
-        fill: var(--color-primary-element);
-        flex-shrink: 0;
-    }
-
-    .auth-status-text {
-        flex: 1;
-    }
-
-    .auth-status-text strong {
-        display: block;
-        color: var(--color-main-text);
-        font-size: 14px;
-        margin-bottom: 4px;
-    }
-
-    .auth-status-text span {
-        color: var(--color-text-maxcontrast);
-        font-size: 13px;
-    }
-{% endblock %}
-
-{% block content %}
-<div class="app-content-wrapper">
-    <!-- Main Content Area -->
-    <main id="app-content">
-        <div class="page-content">
-            <!-- Hero Section -->
-            <div class="hero-section">
-                <h1>Welcome to Nextcloud MCP Server</h1>
-                <p>
-                    Interactive user interface for semantic search and document retrieval.
-                    Test queries, visualize results, and explore your Nextcloud content using RAG workflows.
-                </p>
-            </div>
-
-            <!-- Authentication Status -->
-            <div class="auth-status">
-                <svg viewBox="0 0 24 24">
-                    <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                </svg>
-                <div class="auth-status-text">
-                    <strong>Authenticated as: {{ username }}</strong>
-                    <span>Authentication mode: <code>{{ auth_mode }}</code></span>
-                </div>
-            </div>
-
-            {% if vector_sync_enabled %}
-            <!-- Vector Sync Enabled Content -->
-            <div class="info-section">
-                <h2>About Semantic Search</h2>
-                <p>
-                    This interface provides access to <strong>semantic search</strong> capabilities powered by vector embeddings.
-                    Unlike traditional keyword search, semantic search understands the <em>meaning</em> of your queries and finds
-                    conceptually similar content across your Nextcloud apps.
-                </p>
-                <p>
-                    <strong>How it works:</strong>
-                </p>
-                <ul>
-                    <li>Documents from Notes, Calendar, Files, Contacts, and Deck are indexed into a vector database</li>
-                    <li>Each document chunk is converted to a 768-dimensional vector embedding that captures semantic meaning</li>
-                    <li>Queries are also converted to embeddings and matched against document vectors using similarity search</li>
-                    <li>Results can be retrieved using pure semantic search or hybrid BM25 search combining keywords and semantics</li>
-                </ul>
-            </div>
-
-            <div class="info-section">
-                <h2>RAG Workflow Integration</h2>
-                <p>
-                    This UI allows you to <strong>test the same queries that Large Language Models (LLMs) would use</strong> in a
-                    Retrieval-Augmented Generation (RAG) workflow. When an AI assistant needs to answer questions about your data:
-                </p>
-                <ul>
-                    <li><strong>Step 1:</strong> The assistant converts your question into a search query</li>
-                    <li><strong>Step 2:</strong> The MCP server retrieves relevant document chunks using semantic search</li>
-                    <li><strong>Step 3:</strong> Retrieved context is passed to the LLM to generate an informed answer</li>
-                </ul>
-
-                <!-- RAG Workflow Diagram -->
-                <div style="background: var(--color-main-background); border: 2px solid var(--color-primary-element); border-radius: var(--border-radius-large); padding: 24px; margin: 24px 0; font-family: 'SFMono-Regular', 'Consolas', 'Liberation Mono', 'Menlo', monospace; font-size: 13px; line-height: 1.8; overflow-x: auto;">
-                    <div style="text-align: center; font-weight: 600; margin-bottom: 16px; color: var(--color-primary-element); font-size: 14px;">
-                        MCP Sampling RAG Workflow
-                    </div>
-                    <pre style="margin: 0; color: var(--color-main-text);">
-┌─────────────────┐
-│   <strong>MCP Client</strong>   │  User asks: "What are health benefits of coffee?"
-│  (Claude Code)  │
-└────────┬────────┘
-         │ (1) User question
-         ↓
-┌────────────────────────────────────────────────────────────────────────┐
-│                      <strong>Nextcloud MCP Server</strong>                          │
-│  ┌──────────────────────────────────────────────────────────────────┐  │
-│  │ <strong>nc_semantic_search_answer</strong> Tool (MCP Sampling-enabled)      │  │
-│  │                                                                  │  │
-│  │  (2) Semantic Search                                             │  │
-│  │  ┌────────────────────────────────────────────────────────┐     │  │
-│  │  │ Query: "health benefits of coffee"                     │     │  │
-│  │  │ → Convert to 768D vector embedding                     │     │  │
-│  │  │ → Search Qdrant (BM25 Hybrid + RRF fusion)             │     │  │
-│  │  │ → Retrieve top 5 relevant document chunks              │     │  │
-│  │  └────────────────────────────────────────────────────────┘     │  │
-│  │                                                                  │  │
-│  │  (3) Construct Prompt with Context                               │  │
-│  │  ┌────────────────────────────────────────────────────────┐     │  │
-│  │  │ "What are health benefits of coffee?                   │     │  │
-│  │  │                                                         │     │  │
-│  │  │  Documents:                                             │     │  │
-│  │  │  - [MED-2155] Effects of habitual coffee consumption...│     │  │
-│  │  │  - [MED-1646] Beverage consumption guidance...         │     │  │
-│  │  │  - [MED-1627] Coffee and depression risk...            │     │  │
-│  │  │  ...                                                    │     │  │
-│  │  │                                                         │     │  │
-│  │  │  Provide answer with citations."                        │     │  │
-│  │  └────────────────────────────────────────────────────────┘     │  │
-│  │                                                                  │  │
-│  │  (4) MCP Sampling Request                                        │  │
-│  │  ─────────────────────────────────────────────────────────────> │  │
-│  └──────────────────────────────────────────────────────────────────┘  │
-└────────────────────────────────────────────────────────────────────────┘
-         │
-         │ Sampling request with prompt + context
-         ↓
-┌─────────────────┐
-│   <strong>MCP Client</strong>   │  (5) Client's LLM generates answer using retrieved context
-│    (Claude)     │      → "Coffee consumption (2-3 cups/day) is associated with
-└────────┬────────┘         reduced risk of type 2 diabetes, cardiovascular disease,
-         │                  and improved liver health (Document 1, 2)..."
-         │
-         │ (6) Answer with citations
-         ↓
-┌─────────────────┐
-│      User       │  Receives comprehensive answer with source citations
-└─────────────────┘</pre>
-                </div>
-
-                <p style="margin-top: 16px;">
-                    <strong>Key Point:</strong> The MCP server retrieves context but doesn't generate answers itself.
-                    Through <strong>MCP sampling</strong>, it requests the client's LLM to generate responses, giving users
-                    full control over which model is used and ensuring all processing happens client-side.
-                </p>
-
-                <p>
-                    By using this interface, you can preview search results, understand relevance scores, and verify
-                    that the system retrieves the right information before it reaches the LLM.
-                </p>
-            </div>
-
-            <!-- Feature Cards -->
-            <h2>Available Features</h2>
-            <div class="feature-grid">
-                <a href="/app/user-info" class="feature-card">
-                    <div class="feature-icon">
-                        <svg viewBox="0 0 24 24">
-                            <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                        </svg>
-                    </div>
-                    <h3>User Information</h3>
-                    <p>
-                        View your authentication details, session information, and IdP profile.
-                        Manage background access permissions.
-                    </p>
-                </a>
-
-                <a href="/app/user-info#vector-sync" class="feature-card">
-                    <div class="feature-icon">
-                        <svg viewBox="0 0 24 24">
-                            <path d="M12,18A6,6 0 0,1 6,12C6,11 6.25,10.03 6.7,9.2L5.24,7.74C4.46,8.97 4,10.43 4,12A8,8 0 0,0 12,20V23L16,19L12,15M12,4V1L8,5L12,9V6A6,6 0 0,1 18,12C18,13 17.75,13.97 17.3,14.8L18.76,16.26C19.54,15.03 20,13.57 20,12A8,8 0 0,0 12,4Z" />
-                        </svg>
-                    </div>
-                    <h3>Vector Sync Status</h3>
-                    <p>
-                        Monitor real-time indexing progress with metrics for indexed documents, pending queue,
-                        and synchronization status.
-                    </p>
-                </a>
-
-                <a href="/app/user-info#vector-viz" class="feature-card">
-                    <div class="feature-icon">
-                        <svg viewBox="0 0 24 24">
-                            <path d="M22,21H2V3H4V19H6V10H10V19H12V6H16V19H18V14H22V21Z" />
-                        </svg>
-                    </div>
-                    <h3>Vector Visualization</h3>
-                    <p>
-                        Interactive search interface with 2D PCA visualization. Compare algorithms,
-                        view relevance scores, and explore matched document chunks.
-                    </p>
-                </a>
-            </div>
-
-            {% else %}
-            <!-- Vector Sync Disabled Content -->
-            <div class="warning">
-                <h3 style="margin-top: 0;">Vector Sync is Disabled</h3>
-                <p>
-                    Semantic search and vector visualization features are currently disabled.
-                    To enable these features, set <code>VECTOR_SYNC_ENABLED=true</code> in your environment configuration.
-                </p>
-                <p style="margin-bottom: 0;">
-                    <strong>Learn more:</strong>
-                    <a href="https://github.com/YOUR_REPO/docs/configuration.md" target="_blank" style="color: inherit; text-decoration: underline;">
-                        Configuration Guide
-                    </a>
-                </p>
-            </div>
-
-            <!-- Limited Feature Card -->
-            <h2>Available Features</h2>
-            <div class="feature-grid">
-                <a href="/app/user-info" class="feature-card">
-                    <div class="feature-icon">
-                        <svg viewBox="0 0 24 24">
-                            <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                        </svg>
-                    </div>
-                    <h3>User Information</h3>
-                    <p>
-                        View your authentication details, session information, and IdP profile.
-                        Manage background access permissions.
-                    </p>
-                </a>
-            </div>
-            {% endif %}
-
-            <!-- Documentation Section -->
-            <div class="info-section" style="margin-top: 40px;">
-                <h2>Documentation</h2>
-                <p>
-                    For detailed information about configuration, authentication modes, and advanced features,
-                    please refer to the project documentation:
-                </p>
-                <ul>
-                    <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md" target="_blank">Installation Guide</a></li>
-                    <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md" target="_blank">Configuration Options</a></li>
-                    <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/authentication.md" target="_blank">Authentication Modes</a></li>
-                    {% if vector_sync_enabled %}
-                    <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/user-guide/vector-sync-ui.md" target="_blank">Vector Sync UI Guide</a></li>
-                    {% endif %}
-                </ul>
-            </div>
-        </div>
-    </main>
-</div>
-{% endblock %}

nextcloud_mcp_server/auth/token_broker.py

@@ -14,13 +14,14 @@ The Token Broker provides:
 - Session vs background token separation (RFC 8693)
 """
 
+import asyncio
 import logging
 from datetime import datetime, timedelta, timezone
 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
@@ -42,7 +43,7 @@ class TokenCache:
         self._cache: Dict[str, Tuple[str, datetime]] = {}
         self._ttl = timedelta(seconds=ttl_seconds)
         self._early_refresh = timedelta(seconds=early_refresh_seconds)
-        self._lock = anyio.Lock()
+        self._lock = asyncio.Lock()
 
     async def get(self, user_id: str) -> Optional[str]:
         """Get cached token if valid."""
@@ -103,8 +104,7 @@ class TokenBrokerService:
         storage: RefreshTokenStorage,
         oidc_discovery_url: str,
         nextcloud_host: str,
-        client_id: str,
-        client_secret: str,
+        encryption_key: str,
         cache_ttl: int = 300,
         cache_early_refresh: int = 30,
     ):
@@ -112,25 +112,23 @@ class TokenBrokerService:
         Initialize the Token Broker Service.
 
         Args:
-            storage: Database storage for refresh tokens (handles encryption internally)
+            storage: Database storage for refresh tokens
             oidc_discovery_url: OIDC provider discovery URL
             nextcloud_host: Nextcloud server URL
-            client_id: OAuth client ID for token operations
-            client_secret: OAuth client secret for token operations
+            encryption_key: Fernet key for token encryption
             cache_ttl: Cache TTL in seconds (default: 5 minutes)
             cache_early_refresh: Early refresh threshold in seconds (default: 30 seconds)
         """
         self.storage = storage
         self.oidc_discovery_url = oidc_discovery_url
         self.nextcloud_host = nextcloud_host
-        self.client_id = client_id
-        self.client_secret = client_secret
+        self.fernet = Fernet(
+            encryption_key.encode()
+            if isinstance(encryption_key, str)
+            else encryption_key
+        )
         self.cache = TokenCache(cache_ttl, cache_early_refresh)
         self._oidc_config = None
-
-        # 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:
@@ -141,24 +139,6 @@ class TokenBrokerService:
             )
         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:
@@ -200,8 +180,9 @@ class TokenBrokerService:
             return None
 
         try:
-            # storage.get_refresh_token() returns already-decrypted token
-            refresh_token = refresh_data["refresh_token"]
+            # Decrypt refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()
 
             # Exchange refresh token for new access token
             access_token, expires_in = await self._refresh_access_token(refresh_token)
@@ -290,79 +271,41 @@ 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
 
-        # 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
+        # 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
 
-            # 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
+        try:
+            # Decrypt refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()
 
-            # Mark refresh as in-progress
-            await self.cache.set(refresh_in_progress_key, "true", expires_in=5)
+            # Get token with specific scopes for background operation
+            access_token, expires_in = await self._refresh_access_token_with_scopes(
+                refresh_token, required_scopes
+            )
 
-            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
+            # Cache the background token
+            await self.cache.set(cache_key, access_token, expires_in)
 
-                # storage.get_refresh_token() returns already-decrypted token
-                refresh_token = refresh_data["refresh_token"]
+            logger.info(
+                f"Generated background token for user {user_id} with scopes: {required_scopes}"
+            )
 
-                # 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
-                )
+            return access_token
 
-                # Cache the background token
-                await self.cache.set(cache_key, access_token, expires_in)
+        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
 
-                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]:
+    async def _refresh_access_token(self, refresh_token: str) -> Tuple[str, int]:
         """
         Exchange refresh token for new access token.
 
@@ -370,7 +313,6 @@ 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)
@@ -381,13 +323,10 @@ 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 offline_access notes:read notes:write calendar:read calendar:write",
-            "client_id": self.client_id,
-            "client_secret": self.client_secret,
+            "scope": "openid profile email notes:read notes:write calendar:read calendar:write",
         }
 
         response = await client.post(
@@ -406,41 +345,23 @@ class TokenBrokerService:
         access_token = token_data["access_token"]
         expires_in = token_data.get("expires_in", 3600)  # Default 1 hour
 
-        # 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
+        # Validate audience
+        await self._validate_token_audience(access_token, "nextcloud")
 
         logger.info(f"Refreshed access token (expires in {expires_in}s)")
         return access_token, expires_in
 
     async def _refresh_access_token_with_scopes(
-        self, refresh_token: str, required_scopes: list[str], user_id: str | None = None
+        self, refresh_token: str, required_scopes: list[str]
     ) -> Tuple[str, int]:
         """
         Exchange refresh token for new access token with specific scopes.
 
         This method implements scope downscoping for least privilege.
 
-        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)
@@ -450,25 +371,16 @@ class TokenBrokerService:
 
         client = await self._get_http_client()
 
-        # Always include basic OpenID scopes + offline_access to get new refresh token
-        scopes = list(
-            set(["openid", "profile", "email", "offline_access"] + required_scopes)
-        )
+        # Always include basic OpenID scopes
+        scopes = list(set(["openid", "profile", "email"] + 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,
@@ -479,29 +391,14 @@ 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
 
-        # 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
+        # Validate audience
+        await self._validate_token_audience(access_token, "nextcloud")
 
         logger.info(
             f"Refreshed access token with scopes {scopes} (expires in {expires_in}s)"
@@ -556,8 +453,11 @@ class TokenBrokerService:
             return False
 
         try:
-            # storage.get_refresh_token() returns already-decrypted token
-            current_refresh_token = refresh_data["refresh_token"]
+            # Decrypt current refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            current_refresh_token = self.fernet.decrypt(
+                encrypted_token.encode()
+            ).decode()
 
             # Get OIDC configuration
             config = await self._get_oidc_config()
@@ -586,15 +486,13 @@ class TokenBrokerService:
             new_refresh_token = token_data.get("refresh_token")
 
             if new_refresh_token and new_refresh_token != current_refresh_token:
-                # 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()
-                )
+                # Encrypt and store new refresh token
+                encrypted_new = self.fernet.encrypt(new_refresh_token.encode()).decode()
                 await self.storage.store_refresh_token(
                     user_id=user_id,
-                    refresh_token=new_refresh_token,
-                    expires_at=expires_at,
+                    refresh_token=encrypted_new,
+                    expires_at=datetime.now(timezone.utc)
+                    + timedelta(days=90),  # 90-day expiry
                 )
                 logger.info(f"Rotated master refresh token for user {user_id}")
 
@@ -638,8 +536,11 @@ class TokenBrokerService:
             refresh_data = await self.storage.get_refresh_token(user_id)
             if refresh_data:
                 try:
-                    # storage.get_refresh_token() returns already-decrypted token
-                    refresh_token = refresh_data["refresh_token"]
+                    # Attempt to revoke at IdP
+                    encrypted_token = refresh_data["refresh_token"]
+                    refresh_token = self.fernet.decrypt(
+                        encrypted_token.encode()
+                    ).decode()
                     await self._revoke_token_at_idp(refresh_token)
                 except Exception as e:
                     logger.warning(f"Failed to revoke at IdP: {e}")

nextcloud_mcp_server/auth/unified_verifier.py

@@ -117,71 +117,6 @@ 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.
@@ -251,78 +186,6 @@ 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.
@@ -367,15 +230,12 @@ class UnifiedTokenVerifier(TokenVerifier):
         """
         return "." in token and token.count(".") == 2
 
-    async def _verify_jwt_signature(
-        self, token: str, skip_issuer_check: bool = False
-    ) -> dict[str, Any] | None:
+    async def _verify_jwt_signature(self, token: str) -> 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
@@ -388,22 +248,25 @@ 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 should_verify_issuer else None),
+                issuer=(
+                    self.settings.oidc_issuer
+                    if hasattr(self.settings, "oidc_issuer")
+                    else None
+                ),
                 options={
                     "verify_signature": True,
                     "verify_exp": True,
                     "verify_iat": True,
-                    "verify_iss": should_verify_issuer,
+                    "verify_iss": (
+                        True
+                        if hasattr(self.settings, "oidc_issuer")
+                        and self.settings.oidc_issuer
+                        else False
+                    ),
                     "verify_aud": False,  # We handle audience validation separately
                 },
             )
@@ -440,13 +303,10 @@ 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=(client_id, client_secret),
+                auth=(self.settings.oidc_client_id, self.settings.oidc_client_secret),
             )
 
             if response.status_code == 200:
@@ -495,24 +355,6 @@ 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
         """
@@ -537,13 +379,14 @@ class UnifiedTokenVerifier(TokenVerifier):
             logger.warning("No 'exp' claim in token, using default TTL")
             exp = int(time.time() + self.cache_ttl)
 
-        # Cache the result with the provided key
+        # Cache the result
+        token_hash = hashlib.sha256(token.encode()).hexdigest()
         userinfo = {
             "sub": username,
             "scope": scope_string,
             **{k: v for k, v in payload.items() if k not in ["sub", "scope"]},
         }
-        self._token_cache[cache_key] = (userinfo, exp)
+        self._token_cache[token_hash] = (userinfo, exp)
 
         return AccessToken(
             token=token,

nextcloud_mcp_server/auth/userinfo_routes.py

@@ -9,39 +9,24 @@ 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
-
 logger = logging.getLogger(__name__)
 
-# Setup Jinja2 environment for templates
-_template_dir = Path(__file__).parent / "templates"
-_jinja_env = Environment(loader=FileSystemLoader(_template_dir))
 
-
-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.
+async def _get_authenticated_client_for_userinfo(request: Request) -> httpx.AsyncClient:
+    """Get an authenticated HTTP client for user info page operations.
 
     Args:
         request: Starlette request object
 
     Returns:
-        Authenticated NextcloudClient
-
-    Raises:
-        RuntimeError: If credentials/session not configured
+        Authenticated httpx.AsyncClient
     """
     oauth_ctx = getattr(request.app.state, "oauth_context", None)
 
@@ -54,15 +39,11 @@ async def _get_authenticated_client_for_userinfo(request: Request) -> NextcloudC
         if not all([nextcloud_host, username, password]):
             raise RuntimeError("BasicAuth credentials not configured")
 
-        from httpx import BasicAuth
-
-        assert nextcloud_host is not None
-        assert username is not None
-        assert password is not None
-        return NextcloudClient(
+        assert nextcloud_host is not None  # Type narrowing for type checker
+        return httpx.AsyncClient(
             base_url=nextcloud_host,
-            username=username,
-            auth=BasicAuth(username, password),
+            auth=(username, password),
+            timeout=30.0,
         )
 
     # OAuth mode - get token from session
@@ -77,14 +58,15 @@ async def _get_authenticated_client_for_userinfo(request: Request) -> NextcloudC
         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 or not username:
-        raise RuntimeError("Nextcloud host or username not configured")
+    if not nextcloud_host:
+        raise RuntimeError("Nextcloud host not configured")
 
-    return NextcloudClient.from_token(
-        base_url=nextcloud_host, token=access_token, username=username
+    return httpx.AsyncClient(
+        base_url=nextcloud_host,
+        headers={"Authorization": f"Bearer {access_token}"},
+        timeout=30.0,
     )
 
 
@@ -386,6 +368,8 @@ 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 {
@@ -433,10 +417,10 @@ async def user_info_html(request: Request) -> HTMLResponse:
     try:
         from nextcloud_mcp_server.auth.permissions import is_nextcloud_admin
 
-        # 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()
+        # 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()
     except Exception as e:
         logger.warning(f"Failed to check admin status: {e}")
         # Default to not admin if check fails
@@ -447,14 +431,51 @@ async def user_info_html(request: Request) -> HTMLResponse:
         oauth_ctx = getattr(request.app.state, "oauth_context", None)
         login_url = str(request.url_for("oauth_login")) if oauth_ctx else "/oauth/login"
 
-        template = _jinja_env.get_template("error.html")
-        return HTMLResponse(
-            content=template.render(
-                error_title="Error Retrieving User Info",
-                error_message=user_context["error"],
-                login_url=login_url,
-            )
-        )
+        error_html = f"""
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>Error - Nextcloud MCP Server</title>
+            <style>
+                body {{
+                    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+                    max-width: 800px;
+                    margin: 50px auto;
+                    padding: 20px;
+                    background-color: #f5f5f5;
+                }}
+                .container {{
+                    background: white;
+                    border-radius: 8px;
+                    padding: 30px;
+                    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+                }}
+                h1 {{
+                    color: #d32f2f;
+                    margin-top: 0;
+                }}
+                .error {{
+                    background-color: #ffebee;
+                    border-left: 4px solid #d32f2f;
+                    padding: 15px;
+                    margin: 20px 0;
+                }}
+            </style>
+        </head>
+        <body>
+            <div class="container">
+                <h1>Error Retrieving User Info</h1>
+                <div class="error">
+                    <strong>Error:</strong> {user_context["error"]}
+                </div>
+                <p><a href="{login_url}">Login again</a></p>
+            </div>
+        </body>
+        </html>
+        """
+        return HTMLResponse(content=error_html)
 
     # Build HTML response
     auth_mode = user_context.get("auth_mode", "unknown")
@@ -633,26 +654,398 @@ async def user_info_html(request: Request) -> HTMLResponse:
             </div>
         """
 
-    # Check if vector sync is enabled (needed for Welcome tab)
-    vector_sync_enabled = os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
+    html_content = f"""
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>Nextcloud MCP Server</title>
 
-    # Render template
-    template = _jinja_env.get_template("user_info.html")
-    return HTMLResponse(
-        content=template.render(
-            user_info_tab_html=user_info_tab_html,
-            vector_sync_tab_html=vector_sync_tab_html,
-            webhooks_tab_html=webhooks_tab_html,
-            show_vector_sync_tab=show_vector_sync_tab,
-            show_webhooks_tab=show_webhooks_tab,
-            logout_url=logout_url if auth_mode == "oauth" else None,
-            nextcloud_host_for_links=nextcloud_host_for_links,
-            # Additional context for Welcome tab
-            vector_sync_enabled=vector_sync_enabled,
-            username=username,
-            auth_mode=auth_mode,
-        )
-    )
+        <!-- htmx for dynamic loading -->
+        <script src="https://unpkg.com/htmx.org@1.9.10"></script>
+
+        <!-- Alpine.js for tab state management -->
+        <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
+
+        <!-- Plotly.js for vector visualization -->
+        <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+
+        <!-- Vector visualization app (Alpine.js component) -->
+        <script>
+            function vizApp() {{
+                return {{
+                    query: '',
+                    algorithm: 'hybrid',
+                    showAdvanced: false,
+                    docTypes: [''],  // Default to "All Types"
+                    limit: 50,
+                    scoreThreshold: 0.7,
+                    semanticWeight: 0.5,
+                    keywordWeight: 0.3,
+                    fuzzyWeight: 0.2,
+                    loading: false,
+                    results: [],
+
+                    async executeSearch() {{
+                        this.loading = true;
+                        this.results = [];
+
+                        try {{
+                            const params = new URLSearchParams({{
+                                query: this.query,
+                                algorithm: this.algorithm,
+                                limit: this.limit,
+                                score_threshold: this.scoreThreshold,
+                                semantic_weight: this.semanticWeight,
+                                keyword_weight: this.keywordWeight,
+                                fuzzy_weight: this.fuzzyWeight,
+                            }});
+
+                            // Add doc_types parameter (filter out empty string for "All Types")
+                            const selectedTypes = this.docTypes.filter(t => t !== '');
+                            if (selectedTypes.length > 0) {{
+                                params.append('doc_types', selectedTypes.join(','));
+                            }}
+
+                            const response = await fetch(`/app/vector-viz/search?${{params}}`);
+                            const data = await response.json();
+
+                            if (data.success) {{
+                                this.results = data.results;
+                                this.renderPlot(data.coordinates_2d, data.results);
+                            }} else {{
+                                alert('Search failed: ' + data.error);
+                            }}
+                        }} catch (error) {{
+                            alert('Error: ' + error.message);
+                        }} finally {{
+                            this.loading = false;
+                        }}
+                    }},
+
+                    renderPlot(coordinates, results) {{
+                        const trace = {{
+                            x: coordinates.map(c => c[0]),
+                            y: coordinates.map(c => c[1]),
+                            mode: 'markers',
+                            type: 'scatter',
+                            text: results.map(r => `${{r.title}}<br>Score: ${{r.score.toFixed(3)}}`),
+                            marker: {{
+                                size: 8,
+                                color: results.map(r => r.score),
+                                colorscale: 'Viridis',
+                                showscale: true,
+                                colorbar: {{ title: 'Score' }},
+                                cmin: 0,
+                                cmax: 1
+                            }}
+                        }};
+
+                        const layout = {{
+                            title: `Vector Space (PCA 2D) - ${{results.length}} results`,
+                            xaxis: {{ title: 'PC1' }},
+                            yaxis: {{ title: 'PC2' }},
+                            hovermode: 'closest',
+                            height: 600
+                        }};
+
+                        Plotly.newPlot('viz-plot', [trace], layout);
+                    }},
+
+                    getNextcloudUrl(result) {{
+                        // Generate Nextcloud URL based on document type
+                        // Use the actual Nextcloud host (port 8080), not the MCP server
+                        const baseUrl = '{nextcloud_host_for_links}';
+
+                        switch (result.doc_type) {{
+                            case 'note':
+                                return `${{baseUrl}}/apps/notes/note/${{result.id}}`;
+                            case 'file':
+                                return `${{baseUrl}}/apps/files/?fileId=${{result.id}}`;
+                            case 'calendar':
+                                return `${{baseUrl}}/apps/calendar`;
+                            case 'contact':
+                                return `${{baseUrl}}/apps/contacts`;
+                            case 'deck':
+                                return `${{baseUrl}}/apps/deck`;
+                            default:
+                                return `${{baseUrl}}`;
+                        }}
+                    }}
+                }}
+            }}
+        </script>
+
+        <style>
+            body {{
+                font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+                max-width: 900px;
+                margin: 50px auto;
+                padding: 20px;
+                background-color: #f5f5f5;
+            }}
+            .container {{
+                background: white;
+                border-radius: 8px;
+                padding: 30px;
+                box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+                min-height: calc(100vh - 200px);
+            }}
+            h1 {{
+                color: #0082c9;
+                margin-top: 0;
+                border-bottom: 2px solid #0082c9;
+                padding-bottom: 10px;
+            }}
+            h2 {{
+                color: #333;
+                margin-top: 20px;
+                border-bottom: 1px solid #e0e0e0;
+                padding-bottom: 5px;
+            }}
+
+            /* Tab navigation */
+            .tabs {{
+                display: flex;
+                gap: 0;
+                margin: 20px 0 0 0;
+                border-bottom: 2px solid #e0e0e0;
+            }}
+            .tab {{
+                padding: 12px 24px;
+                cursor: pointer;
+                background: transparent;
+                border: none;
+                font-size: 14px;
+                font-weight: 500;
+                color: #666;
+                border-bottom: 2px solid transparent;
+                margin-bottom: -2px;
+                transition: all 0.2s;
+            }}
+            .tab:hover {{
+                color: #0082c9;
+                background-color: #f5f5f5;
+            }}
+            .tab.active {{
+                color: #0082c9;
+                border-bottom-color: #0082c9;
+            }}
+
+            /* Tab content - use grid to overlay panes */
+            .tab-content {{
+                padding: 20px 0;
+                display: grid;
+            }}
+
+            /* Tab panes - all occupy the same grid cell to overlay */
+            .tab-pane {{
+                grid-area: 1 / 1;
+            }}
+
+            /* Tables */
+            table {{
+                width: 100%;
+                border-collapse: collapse;
+                margin: 15px 0;
+            }}
+            td {{
+                padding: 10px;
+                border-bottom: 1px solid #e0e0e0;
+            }}
+            td:first-child {{
+                width: 200px;
+                color: #666;
+            }}
+            code {{
+                background-color: #f5f5f5;
+                padding: 2px 6px;
+                border-radius: 3px;
+                font-family: 'Courier New', monospace;
+            }}
+
+            /* Badges */
+            .badge {{
+                display: inline-block;
+                padding: 3px 8px;
+                border-radius: 12px;
+                font-size: 12px;
+                font-weight: bold;
+                text-transform: uppercase;
+            }}
+            .badge-oauth {{
+                background-color: #4caf50;
+                color: white;
+            }}
+            .badge-basic {{
+                background-color: #2196f3;
+                color: white;
+            }}
+
+            /* Messages */
+            .warning {{
+                background-color: #fff3cd;
+                border-left: 4px solid #ffc107;
+                padding: 15px;
+                margin: 15px 0;
+                color: #856404;
+            }}
+            .info-message {{
+                background-color: #e3f2fd;
+                border-left: 4px solid #2196f3;
+                padding: 15px;
+                margin: 15px 0;
+                color: #1565c0;
+            }}
+
+            /* Buttons */
+            .button {{
+                display: inline-block;
+                padding: 10px 20px;
+                background-color: #d32f2f;
+                color: white;
+                text-decoration: none;
+                border-radius: 4px;
+                transition: background-color 0.3s;
+                border: none;
+                cursor: pointer;
+                font-size: 14px;
+            }}
+            .button:hover {{
+                background-color: #b71c1c;
+            }}
+            .button-primary {{
+                background-color: #0082c9;
+            }}
+            .button-primary:hover {{
+                background-color: #006ba3;
+            }}
+
+            /* Logout section */
+            .logout {{
+                margin-top: 30px;
+                padding-top: 20px;
+                border-top: 1px solid #e0e0e0;
+            }}
+
+            /* Smooth htmx content swaps */
+            .htmx-swapping {{
+                opacity: 0;
+                transition: opacity 200ms ease-out;
+            }}
+
+            /* Smooth htmx content settling */
+            .htmx-settling {{
+                opacity: 1;
+                transition: opacity 200ms ease-in;
+            }}
+        </style>
+    </head>
+    <body>
+        <div class="container" x-data="{{ activeTab: 'user-info' }}">
+            <h1>Nextcloud MCP Server</h1>
+
+            <!-- Tab Navigation -->
+            <div class="tabs">
+                <button
+                    class="tab"
+                    :class="activeTab === 'user-info' ? 'active' : ''"
+                    @click="activeTab = 'user-info'">
+                    User Info
+                </button>
+                {
+        ""
+        if not show_vector_sync_tab
+        else '''
+                <button
+                    class="tab"
+                    :class="activeTab === 'vector-sync' ? 'active' : ''"
+                    @click="activeTab = 'vector-sync'">
+                    Vector Sync
+                </button>
+                '''
+    }
+                {
+        ""
+        if not show_vector_sync_tab
+        else '''
+                <button
+                    class="tab"
+                    :class="activeTab === 'vector-viz' ? 'active' : ''"
+                    @click="activeTab = 'vector-viz'">
+                    Vector Viz
+                </button>
+                '''
+    }
+                {
+        ""
+        if not show_webhooks_tab
+        else '''
+                <button
+                    class="tab"
+                    :class="activeTab === 'webhooks' ? 'active' : ''"
+                    @click="activeTab = 'webhooks'">
+                    Webhooks
+                </button>
+                '''
+    }
+            </div>
+
+            <!-- Tab Content -->
+            <div class="tab-content">
+                <!-- User Info Tab -->
+                <div class="tab-pane" x-show="activeTab === 'user-info'" x-transition.opacity.duration.150ms>
+                    {user_info_tab_html}
+                </div>
+
+                {
+        ""
+        if not show_vector_sync_tab
+        else f'''
+                <!-- Vector Sync Tab -->
+                <div class="tab-pane" x-show="activeTab === 'vector-sync'" x-transition.opacity.duration.150ms>
+                    {vector_sync_tab_html}
+                </div>
+                '''
+    }
+
+                {
+        ""
+        if not show_vector_sync_tab
+        else '''
+                <!-- Vector Viz Tab -->
+                <div class="tab-pane" x-show="activeTab === 'vector-viz'" x-transition.opacity.duration.150ms>
+                    <div hx-get="/app/vector-viz" hx-trigger="load" hx-swap="outerHTML">
+                        <p style="color: #999;">Loading vector visualization...</p>
+                    </div>
+                </div>
+                '''
+    }
+
+                {
+        ""
+        if not show_webhooks_tab
+        else f'''
+                <!-- Webhooks Tab (admin-only, loaded dynamically) -->
+                <div class="tab-pane" x-show="activeTab === 'webhooks'" x-transition.opacity.duration.150ms>
+                    {webhooks_tab_html}
+                </div>
+                '''
+    }
+            </div>
+
+            {
+        f'<div class="logout"><a href="{logout_url}" class="button">Logout</a></div>'
+        if auth_mode == "oauth"
+        else ""
+    }
+        </div>
+    </body>
+    </html>
+    """
+
+    return HTMLResponse(content=html_content)
 
 
 @requires("authenticated", redirect="oauth_login")
@@ -672,12 +1065,17 @@ async def revoke_session(request: Request) -> HTMLResponse:
     oauth_ctx = getattr(request.app.state, "oauth_context", None)
 
     if not oauth_ctx:
-        template = _jinja_env.get_template("error.html")
         return HTMLResponse(
-            content=template.render(
-                error_title="Error",
-                error_message="OAuth mode not enabled",
-            ),
+            """
+            <!DOCTYPE html>
+            <html>
+            <head><title>Error</title></head>
+            <body>
+                <h1>Error</h1>
+                <p>OAuth mode not enabled</p>
+            </body>
+            </html>
+            """,
             status_code=400,
         )
 
@@ -685,12 +1083,17 @@ async def revoke_session(request: Request) -> HTMLResponse:
     session_id = request.cookies.get("mcp_session")
 
     if not storage or not session_id:
-        template = _jinja_env.get_template("error.html")
         return HTMLResponse(
-            content=template.render(
-                error_title="Error",
-                error_message="Session not found",
-            ),
+            """
+            <!DOCTYPE html>
+            <html>
+            <head><title>Error</title></head>
+            <body>
+                <h1>Error</h1>
+                <p>Session not found</p>
+            </body>
+            </html>
+            """,
             status_code=400,
         )
 
@@ -703,26 +1106,57 @@ async def revoke_session(request: Request) -> HTMLResponse:
         # Redirect back to user page
         user_page_url = str(request.url_for("user_info_html"))
 
-        template = _jinja_env.get_template("success.html")
         return HTMLResponse(
-            content=template.render(
-                success_title="✓ Background Access Revoked",
-                success_messages=[
-                    "Your refresh token has been deleted successfully.",
-                    "Browser session remains active.",
-                ],
-                redirect_url=user_page_url,
-                redirect_delay=2,
-            )
+            f"""
+            <!DOCTYPE html>
+            <html lang="en">
+            <head>
+                <meta charset="UTF-8">
+                <meta http-equiv="refresh" content="2;url={user_page_url}">
+                <title>Background Access Revoked</title>
+                <style>
+                    body {{
+                        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+                        max-width: 600px;
+                        margin: 50px auto;
+                        padding: 20px;
+                        text-align: center;
+                    }}
+                    .success {{
+                        background-color: #e8f5e9;
+                        border: 2px solid #4caf50;
+                        padding: 30px;
+                        border-radius: 8px;
+                    }}
+                    h1 {{
+                        color: #4caf50;
+                    }}
+                </style>
+            </head>
+            <body>
+                <div class="success">
+                    <h1>✓ Background Access Revoked</h1>
+                    <p>Your refresh token has been deleted successfully.</p>
+                    <p>Browser session remains active.</p>
+                    <p>Redirecting back to user page...</p>
+                </div>
+            </body>
+            </html>
+            """
         )
 
     except Exception as e:
         logger.error(f"Failed to revoke background access: {e}")
-        template = _jinja_env.get_template("error.html")
         return HTMLResponse(
-            content=template.render(
-                error_title="Error",
-                error_message=f"Failed to revoke background access: {e}",
-            ),
+            f"""
+            <!DOCTYPE html>
+            <html>
+            <head><title>Error</title></head>
+            <body>
+                <h1>Error</h1>
+                <p>Failed to revoke background access: {e}</p>
+            </body>
+            </html>
+            """,
             status_code=500,
         )

nextcloud_mcp_server/auth/webhook_routes.py

@@ -139,7 +139,6 @@ 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
-        assert username is not None and password is not None  # Type narrowing
         return httpx.AsyncClient(
             base_url=nextcloud_host,
             auth=(username, password),

nextcloud_mcp_server/cli.py

@@ -29,9 +29,9 @@ from .app import get_app
 @click.option(
     "--transport",
     "-t",
-    default="streamable-http",
+    default="sse",
     show_default=True,
-    type=click.Choice(["streamable-http", "http"]),
+    type=click.Choice(["sse", "streamable-http", "http"]),
     help="MCP transport protocol",
 )
 @click.option(
@@ -253,195 +253,5 @@ 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__":
-    cli()
+    run()

nextcloud_mcp_server/client/__init__.py

@@ -18,7 +18,6 @@ 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
@@ -82,7 +81,6 @@ 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)
@@ -132,75 +130,10 @@ 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/base.py

@@ -5,7 +5,6 @@ import time
 from abc import ABC
 from functools import wraps
 
-import anyio
 from httpx import AsyncClient, HTTPStatusError, RequestError, codes
 
 from nextcloud_mcp_server.observability.metrics import (
@@ -48,7 +47,7 @@ def retry_on_429(func):
                     # Record retry metric (extract app name from args if available)
                     if len(args) > 0 and hasattr(args[0], "app_name"):
                         record_nextcloud_api_retry(app=args[0].app_name, reason="429")
-                    await anyio.sleep(5)
+                    time.sleep(5)
                 elif e.response.status_code == 404:
                     # 404 errors are often expected (e.g., checking if attachments exist)
                     # Log as debug instead of warning