chore(deps): update dependency python to 3.14

chore(deps): update docker/setup-buildx-action digest to 8d2750c

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

@@ -0,0 +1,89 @@
+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@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@v4
+        with:
+          node-version: 22
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.1
+          coverage: none
+
+      - name: Checkout Nextcloud server (for signing)
+        uses: actions/checkout@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@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@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

@@ -0,0 +1,275 @@
+# 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,26 +7,152 @@ on:
 
 jobs:
   bump-version:
-    if: "!startsWith(github.event.head_commit.message, 'bump:')"
+    if: "!startsWith(github.event.head_commit.message, 'bump:') && !startsWith(github.event.head_commit.message, 'chore(release):')"
     runs-on: ubuntu-latest
-    name: "Bump version and create changelog with commitizen"
+    name: "Bump version and create changelog for monorepo components"
     permissions:
       contents: write
       packages: write
     steps:
       - name: Check out
-        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
         with:
           fetch-depth: 0
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
-      - name: Create bump and changelog
-        uses: commitizen-tools/commitizen-action@bb4f1df6601e2a1a891506581b0c53acdc88e07d # 0.26.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-          changelog_increment_filename: body.md
-      - name: Release
-        uses: softprops/action-gh-release@5be0e66d93ac7ed76da52eca8bb058f665c3a5fe # v2.4.2
-        with:
-          body_path: "body.md"
-          tag_name: v${{ env.REVISION }}
-          token: ${{ secrets.GITHUB_TOKEN }}
+          python-version: '3.14'
+
+      - 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
+        if: steps.bump.outputs.bumped == 'true'
+        run: |
+          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

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

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

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@d7b6d50442a89f005016e778bf825a72ef582525 # 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,7 +2,8 @@ name: Build and Publish Docker Image
 
 on:
   push:
-    tags: ["*"]
+    tags:
+      - "v*"
 
 jobs:
   build-and-push:
@@ -12,11 +13,11 @@ jobs:
       packages: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
         with:
           # list of Docker images to use as base name for tags
           images: |
@@ -33,7 +34,7 @@ jobs:
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
 
       - name: Log in to GitHub Container Registry
         if: github.event_name != 'pull_request'

.github/workflows/helm-release.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
         with:
           fetch-depth: 0
 
@@ -38,6 +38,8 @@ jobs:
 
       - name: Run chart-releaser
         uses: helm/chart-releaser-action@cae68fefc6b5f367a0275617c9f83181ba54714f # v1.7.0
+        with:
+          skip_existing: true
         env:
           CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
 

.github/workflows/rag-evaluation.yml

@@ -24,39 +24,25 @@ jobs:
       models: read
 
     steps:
-      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
-        with:
-          submodules: 'true'
-
-      ###### Required to build OIDC App ######
-      - name: Set up php 8.4
-        uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # v2
-        with:
-          php-version: 8.4
-          coverage: none
-
-      - name: Install OIDC app composer dependencies
-        run: |
-          cd third_party/oidc
-          composer install --no-dev
-      ###### Required to build OIDC App ######
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Run docker compose with vector sync
-        uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
+        uses: hoverkraft-tech/compose-action@248470ecc5ed40d8ed3d4480d8260d77179ef579 # v2.4.2
         with:
-          compose-file: "./docker-compose.yml"
+          compose-file: |
+            ./docker-compose.yml
+            ./docker-compose.ci.yml
           up-flags: "--build"
         env:
-          # Override MCP container environment for OpenAI + vector sync
-          VECTOR_SYNC_ENABLED: "true"
-          VECTOR_SYNC_SCAN_INTERVAL: "30"
+          # 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@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
 
       - name: Wait for Nextcloud to be ready
         run: |
@@ -79,7 +65,7 @@ jobs:
           echo "Waiting for MCP server..."
           max_attempts=30
           attempt=0
-          until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8000/health | grep -q "200"; do
+          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."
@@ -101,11 +87,17 @@ jobs:
           OPENAI_EMBEDDING_MODEL: ${{ inputs.embedding_model }}
           OPENAI_GENERATION_MODEL: ${{ inputs.generation_model }}
         run: |
-          uv run pytest tests/integration/test_rag_openai.py -v --log-cli-level=INFO
+          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@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
         with:
           name: rag-evaluation-results
           path: |

.github/workflows/release.yml

@@ -18,9 +18,9 @@ jobs:
       contents: read
     steps:
       - name: Checkout
-        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
       - name: Install uv
-        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
       - 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@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
       - name: Check format
         run: |
           uv run --frozen ruff format --diff
@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           submodules: 'true'
 
@@ -35,7 +35,7 @@ jobs:
       ###### Required to build OIDC App ######
 
       - name: Set up php 8.4
-        uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # v2
+        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # v2
         with:
           php-version: 8.4
           coverage: none
@@ -49,14 +49,14 @@ jobs:
 
 
       - name: Run docker compose
-        uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
+        uses: hoverkraft-tech/compose-action@248470ecc5ed40d8ed3d4480d8260d77179ef579 # v2.4.2
         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@1e862dfacbd1d6d858c55d9b792c756523627244 # v7.1.4
+        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
 
       - name: Install Playwright dependencies
         run: |

CHANGELOG.md

@@ -1,3 +1,224 @@
+# 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.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

CLAUDE.md

@@ -56,6 +56,68 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
   - Pass-through (default): Simple, stateless (ENABLE_TOKEN_EXCHANGE=false)
   - Token exchange (opt-in): RFC 8693 delegation (ENABLE_TOKEN_EXCHANGE=true)
 
+### MCP Tool Annotations (ADR-017)
+
+**All tools MUST include annotations** following these patterns:
+
+```python
+from mcp.types import ToolAnnotations
+
+# Read-only tools (list, search, get)
+@mcp.tool(
+    title="Human Readable Name",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=True,  # Nextcloud is external to MCP server
+    ),
+)
+
+# Create operations
+@mcp.tool(
+    title="Create Resource",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # Creates new resources each time
+        openWorldHint=True,
+    ),
+)
+
+# Update operations (with etag/version control)
+@mcp.tool(
+    title="Update Resource",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # ETag changes = different inputs
+        openWorldHint=True,
+    ),
+)
+
+# Delete operations
+@mcp.tool(
+    title="Delete Resource",
+    annotations=ToolAnnotations(
+        destructiveHint=True,   # Permanently deletes data
+        idempotentHint=True,    # Same end state if called repeatedly
+        openWorldHint=True,
+    ),
+)
+
+# HTTP PUT without version control (special case)
+@mcp.tool(
+    title="Write File",
+    annotations=ToolAnnotations(
+        idempotentHint=True,  # Same content = same end state
+        openWorldHint=True,
+    ),
+)
+```
+
+**Key Principles**:
+- **Idempotency**: Same inputs → same result. ETags change after updates, making them non-idempotent
+- **Destructive**: Operations that permanently delete/overwrite data
+- **Open World**: All Nextcloud tools access external service (openWorldHint=True)
+- **Titles**: Use human-readable names, not snake_case function names
+
+**See**: `docs/ADR-017-mcp-tool-annotations.md` for detailed rationale and examples
+
 ### Project Structure
 - `nextcloud_mcp_server/client/` - HTTP clients for Nextcloud APIs
 - `nextcloud_mcp_server/server/` - MCP tool/resource definitions
@@ -444,6 +506,29 @@ docker compose exec app php occ user_oidc:provider keycloak
 **Nextcloud**: `docker compose exec app php occ ...` for occ commands
 **MariaDB**: `docker compose exec db mariadb -u [user] -p [password] [database]` for queries
 
+### Querying Nextcloud Application Logs
+
+**Use this pattern** to inspect Nextcloud application logs during debugging:
+
+```bash
+# View recent log entries
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq | tail
+
+# Filter by app
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.app == "astrolabe")' | tail
+
+# Filter by log level (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=FATAL)
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.level >= 3)' | tail
+
+# Search for specific messages
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.message | contains("OAuth"))' | tail -20
+
+# View full exception traces
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.exception != null)' | tail -5
+```
+
+**Log Structure**: Each entry is a JSON object with fields: `reqId`, `level`, `time`, `remoteAddr`, `user`, `app`, `method`, `url`, `message`, `userAgent`, `version`, `exception`
+
 **For detailed setup, see**:
 - `docs/installation.md` - Installation guide
 - `docs/configuration.md` - Configuration options

CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# 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,6 +1,6 @@
-FROM docker.io/library/python:3.12-slim-trixie@sha256:b43ff04d5df04ad5cabb80890b7ef74e8410e3395b19af970dcd52d7a4bff921
+FROM docker.io/library/python:3.12-slim-trixie@sha256:fa48eefe2146644c2308b909d6bb7651a768178f84fc9550dcd495e4d6d84d01
 
-COPY --from=ghcr.io/astral-sh/uv:0.9.11@sha256:5aa820129de0a600924f166aec9cb51613b15b68f1dcd2a02f31a500d2ede568 /uv /uvx /bin/
+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)
@@ -12,13 +12,17 @@ RUN apt update && apt install --no-install-recommends --no-install-suggests -y \
 
 WORKDIR /app
 
+COPY pyproject.toml uv.lock README.md .
+
+RUN uv sync --locked --no-dev --no-install-project --no-cache
+
 COPY . .
 
 RUN uv sync --locked --no-dev --no-editable --no-cache
 
 ENV PYTHONUNBUFFERED=1
 ENV VIRTUAL_ENV=/app/.venv
-ENV PATH=/app/.vnev/bin:$PATH
+ENV PATH=/app/.venv/bin:$PATH
 ENV TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata
 
-ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "--host", "0.0.0.0"]
+ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "run", "--host", "0.0.0.0"]

Dockerfile.smithery

@@ -12,12 +12,12 @@
 # - Per-session app password authentication
 # - Multi-user support via Smithery session config
 
-FROM docker.io/library/python:3.12-slim-trixie@sha256:b43ff04d5df04ad5cabb80890b7ef74e8410e3395b19af970dcd52d7a4bff921
+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.11@sha256:5aa820129de0a600924f166aec9cb51613b15b68f1dcd2a02f31a500d2ede568 /uv /uvx /bin/
+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)

README.md

@@ -4,8 +4,8 @@
 
 # Nextcloud MCP Server
 
-[![smithery badge](https://smithery.ai/badge/@cbcoutinho/nextcloud-mcp-server)](https://smithery.ai/server/@cbcoutinho/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.**
 
@@ -63,7 +63,7 @@ http://127.0.0.1:8000/mcp
 
 - **90+ MCP Tools** - Comprehensive API coverage across 8 Nextcloud apps
 - **MCP Resources** - Structured data URIs for browsing Nextcloud data
-- **Semantic Search (Experimental)** - Optional vector-powered search for Notes (requires Qdrant + Ollama)
+- **Semantic Search (Experimental)** - Optional vector-powered search for Notes, Files, News items, and Deck cards (requires Qdrant + Ollama)
 - **Document Processing** - OCR and text extraction from PDFs, DOCX, images with progress notifications
 - **Flexible Deployment** - Docker, Kubernetes (Helm), VM, or local installation
 - **Production-Ready Auth** - Basic Auth with app passwords (recommended) or OAuth2/OIDC (experimental)
@@ -81,7 +81,7 @@ http://127.0.0.1:8000/mcp
 | **Cookbook** | 13 | Recipe management, URL import (schema.org) |
 | **Tables** | 5 | Row operations on Nextcloud Tables |
 | **Sharing** | 10+ | Create and manage shares |
-| **Semantic Search** | 2+ | Vector search for Notes (experimental, opt-in, requires infrastructure) |
+| **Semantic Search** | 2+ | Vector search for Notes, Files, News items, and Deck cards (experimental, opt-in, requires infrastructure) |
 
 Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request!
 
@@ -145,7 +145,7 @@ This enables natural language queries and helps discover related content across
 ### Features
 - **[App Documentation](docs/)** - Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables
 - **[Document Processing](docs/configuration.md#document-processing)** - OCR and text extraction setup
-- **[Semantic Search Architecture](docs/semantic-search-architecture.md)** - Experimental vector search (Notes only, opt-in)
+- **[Semantic Search Architecture](docs/semantic-search-architecture.md)** - Experimental vector search (Notes, Files, News items, Deck cards; opt-in)
 - **[Vector Sync UI Guide](docs/user-guide/vector-sync-ui.md)** - Browser interface for semantic search visualization and testing
 
 ### Advanced Topics
@@ -222,4 +222,4 @@ This project is licensed under the AGPL-3.0 License. See [LICENSE](./LICENSE) fo
 
 - [Model Context Protocol](https://github.com/modelcontextprotocol)
 - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
-- [Nextcloud](https://nextcloud.com/)
+- [Nextcloud](https://nextcloud.com/)

alembic.ini

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

alembic/README

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

alembic/script.py.mako

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

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

@@ -3,3 +3,9 @@
 set -euox pipefail
 
 php /var/www/html/occ config:system:set trusted_domains 2 --value=host.docker.internal
+
+# Set overwrite settings for URL generation (needed for OIDC discovery to return correct URLs)
+# These ensure that URLs generated by Nextcloud include the correct host:port
+php /var/www/html/occ config:system:set overwritehost --value="localhost:8080"
+php /var/www/html/occ config:system:set overwriteprotocol --value="http"
+php /var/www/html/occ config:system:set overwrite.cli.url --value="http://localhost:8080"

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

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

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

@@ -0,0 +1,84 @@
+#!/bin/bash
+
+set -euox pipefail
+
+echo "Installing and configuring 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
+
+# Configure MCP server URLs in Nextcloud system config
+# - mcp_server_url: Internal URL for PHP app to call MCP server APIs (Docker internal network)
+# - mcp_server_public_url: Public URL for OAuth token audience (what browsers/MCP clients see)
+php /var/www/html/occ config:system:set mcp_server_url --value='http://mcp-oauth:8001'
+php /var/www/html/occ config:system:set mcp_server_public_url --value='http://localhost:8001'
+
+# Create OAuth client for Astrolabe app
+# The resource_url MUST match what the MCP server expects as token audience
+# This allows tokens from this client to be validated by MCP server's UnifiedTokenVerifier
+MCP_CLIENT_ID="nextcloudMcpServerUIPublicClient"
+MCP_RESOURCE_URL="http://localhost:8001"
+MCP_REDIRECT_URI="http://localhost:8080/apps/astrolabe/oauth/callback"
+
+echo "Configuring OAuth client for Astrolabe..."
+
+# Check if client already exists
+if php /var/www/html/occ oidc:list 2>/dev/null | grep -q "$MCP_CLIENT_ID"; then
+    echo "OAuth client $MCP_CLIENT_ID already exists, removing to recreate with correct settings..."
+    php /var/www/html/occ oidc:remove "$MCP_CLIENT_ID" || true
+fi
+
+# Create OAuth client with correct resource_url for MCP server audience
+echo "Creating OAuth confidential client with resource_url=$MCP_RESOURCE_URL"
+CLIENT_OUTPUT=$(php /var/www/html/occ oidc:create \
+    "Astrolabe" \
+    "$MCP_REDIRECT_URI" \
+    --client_id="$MCP_CLIENT_ID" \
+    --type=confidential \
+    --flow=code \
+    --token_type=jwt \
+    --resource_url="$MCP_RESOURCE_URL" \
+    --allowed_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")
+
+echo "$CLIENT_OUTPUT"
+
+# Extract client_secret from JSON output
+CLIENT_SECRET=$(echo "$CLIENT_OUTPUT" | php -r 'echo json_decode(file_get_contents("php://stdin"), true)["client_secret"] ?? "";')
+
+if [ -n "$CLIENT_SECRET" ]; then
+    echo "Configuring Astrolabe client secret in system config..."
+    php /var/www/html/occ config:system:set astrolabe_client_secret --value="$CLIENT_SECRET"
+    echo "✓ Client secret configured: ${CLIENT_SECRET:0:8}..."
+else
+    echo "⚠ Warning: Could not extract client_secret from OIDC client creation"
+fi
+
+# Configure OAuth client ID in system config
+echo "Configuring Astrolabe client ID in system config..."
+php /var/www/html/occ config:system:set astrolabe_client_id --value="$MCP_CLIENT_ID"
+echo "✓ Client ID configured: $MCP_CLIENT_ID"
+
+echo "Astrolabe app installed and configured successfully"

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

@@ -0,0 +1,24 @@
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.54.0"
+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
+[tool.commitizen.customize]
+changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:"
+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

@@ -0,0 +1,746 @@
+# 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.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.0
+  version: 1.16.2
 - name: ollama
   repository: https://otwld.github.io/ollama-helm
-  version: 1.35.0
-digest: sha256:da8db198b12ce0252df220fabb297cfe69186edb8e67952c52e05de778189b92
-generated: "2025-11-21T11:09:07.997781541Z"
+  version: 1.36.0
+digest: sha256:fab8008217b27ff4e3e139c2f481eedaa23f9f64a3a086d0e9deea2195b69b63
+generated: "2025-12-14T11:07:07.024787592Z"

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.48.0
-appVersion: "0.48.0"
+version: 0.54.0
+appVersion: "0.56.2"
 keywords:
   - nextcloud
   - mcp
@@ -27,10 +27,10 @@ annotations:
   grafana_dashboard_folder: "Nextcloud MCP"
 dependencies:
   - name: qdrant
-    version: "1.16.0"
+    version: "1.16.2"
     repository: https://qdrant.github.io/qdrant-helm
     condition: qdrant.networkMode.deploySubchart
   - name: ollama
-    version: "1.35.0"
+    version: "1.36.0"
     repository: https://otwld.github.io/ollama-helm
     condition: ollama.enabled

docker-compose.ci.yml

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

docker-compose.yml

@@ -21,7 +21,7 @@ services:
     restart: always
 
   app:
-    image: docker.io/library/nextcloud:32.0.2@sha256:ac08482d73ffd85d94069ba291bbd5fb39a70ff21502030a2e3e2d89a7246a48
+    image: docker.io/library/nextcloud:32.0.3@sha256:53231a9fb9233af2c15bfe70fc03ebe639fd53243fa42a9369884b1e0008deae
     restart: always
     ports:
       - 0.0.0.0:8080:80
@@ -34,7 +34,8 @@ services:
       - ./app-hooks:/docker-entrypoint-hooks.d:ro
       # Mount OIDC development directory outside /var/www/html to avoid rsync conflicts
       # The post-installation hook will register /opt/apps as an additional app directory
-      - ./third_party:/opt/apps:ro
+      #- ./third_party:/opt/apps:ro
+      #- ./third_party/astrolabe:/opt/apps/astrolabe:ro
     environment:
       - NEXTCLOUD_TRUSTED_DOMAINS=app
       - NEXTCLOUD_ADMIN_USER=admin
@@ -51,7 +52,7 @@ services:
       retries: 30
 
   recipes:
-    image: docker.io/library/nginx:alpine@sha256:b3c656d55d7ad751196f21b7fd2e8d4da9cb430e32f646adcf92441b72f82b14
+    image: docker.io/library/nginx:alpine@sha256:052b75ab72f690f33debaa51c7e08d9b969a0447a133eb2b99cc905d9188cb2b
     restart: always
     volumes:
       - ./tests/fixtures/test_recipe.html:/usr/share/nginx/html/test_recipe.html:ro
@@ -150,6 +151,14 @@ 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)
+      - VECTOR_SYNC_ENABLED=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+
+      # Qdrant configuration - persistent local storage
+      - QDRANT_LOCATION=/app/data/qdrant
+
       # NO admin credentials - using OAuth with Dynamic Client Registration (DCR)
       # Client credentials registered via RFC 7591 and stored in volume
       # JWT token type is used for testing (faster validation, scopes embedded in token)
@@ -158,7 +167,7 @@ services:
       - oauth-tokens:/app/data
 
   keycloak:
-    image: quay.io/keycloak/keycloak:26.4.5@sha256:653852bfdea2be6e958b9e90a976eff1c6de34edd55f2f679bdc48ef16bc528e
+    image: quay.io/keycloak/keycloak:26.4.7@sha256:9409c59bdfb65dbffa20b11e6f18b8abb9281d480c7ca402f51ed3d5977e6007
     command:
       - "start-dev"
       - "--import-realm"
@@ -245,7 +254,7 @@ services:
       - smithery
 
   qdrant:
-    image: qdrant/qdrant:v1.16.0@sha256:1005201498cf927d835383d0f918b17d8c9da7db58550f169f694455e42d78f4
+    image: qdrant/qdrant:v1.16.2@sha256:dab6de32f7b2cc599985a7c764db3e8b062f70508fb85ca074aa856f829bf335
     restart: always
     ports:
       - 127.0.0.1:6333:6333  # REST API

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

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

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

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

docs/database-migrations.md

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

docs/running.md

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

docs/semantic-search-architecture.md

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

env.sample

@@ -51,6 +51,11 @@ NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
 
+# Cookie security (browser UI)
+# Auto-detects from NEXTCLOUD_HOST protocol if not set
+# Set explicitly for non-standard setups
+#COOKIE_SECURE=true
+
 # ============================================
 # Document Processing Configuration
 # ============================================

nextcloud_mcp_server/alembic/env.py

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

nextcloud_mcp_server/alembic/versions/20251217_2200_001_initial_schema.py

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

nextcloud_mcp_server/api/__init__.py

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

@@ -5,7 +5,7 @@ from collections.abc import AsyncIterator
 from contextlib import AsyncExitStack, asynccontextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Optional, cast
 
 from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
 
@@ -19,6 +19,7 @@ import httpx
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from mcp.server.auth.settings import AuthSettings
 from mcp.server.fastmcp import Context, FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
 from pydantic import AnyHttpUrl
 from starlette.applications import Starlette
 from starlette.middleware.authentication import AuthenticationMiddleware
@@ -60,6 +61,7 @@ from nextcloud_mcp_server.server import (
     configure_contacts_tools,
     configure_cookbook_tools,
     configure_deck_tools,
+    configure_news_tools,
     configure_notes_tools,
     configure_semantic_tools,
     configure_sharing_tools,
@@ -243,6 +245,25 @@ def validate_pkce_support(discovery: dict, discovery_url: str) -> None:
     click.echo(f"✓ PKCE support validated: {code_challenge_methods}")
 
 
+@dataclass
+class VectorSyncState:
+    """
+    Module-level state for vector sync background tasks.
+
+    This singleton bridges the Starlette server lifespan (where background tasks run)
+    and FastMCP session lifespans (where MCP tools need access to the streams).
+    """
+
+    document_send_stream: Optional[MemoryObjectSendStream] = None
+    document_receive_stream: Optional[MemoryObjectReceiveStream] = None
+    shutdown_event: Optional[anyio.Event] = None
+    scanner_wake_event: Optional[anyio.Event] = None
+
+
+# Module-level singleton for vector sync state
+_vector_sync_state = VectorSyncState()
+
+
 @dataclass
 class AppContext:
     """Application context for BasicAuth mode."""
@@ -495,7 +516,7 @@ async def load_oauth_client_credentials(
         # and the authorization server will limit them to these allowed scopes.
         #
         # The PRM endpoint advertises the same scopes dynamically via @require_scopes decorators.
-        dcr_scopes = "openid profile email notes:read notes:write calendar:read calendar:write todo:read todo:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write"
+        dcr_scopes = "openid profile email notes:read notes:write calendar:read calendar:write todo:read todo:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write news:read news:write"
 
         # Add offline_access scope if refresh tokens are enabled
         enable_offline_access = os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() in (
@@ -555,15 +576,15 @@ async def load_oauth_client_credentials(
 @asynccontextmanager
 async def app_lifespan_basic(server: FastMCP) -> AsyncIterator[AppContext]:
     """
-    Manage application lifecycle for BasicAuth mode.
+    Manage application lifecycle for BasicAuth mode (FastMCP session lifespan).
 
     Creates a single Nextcloud client with basic authentication
-    that is shared across all requests.
+    that is shared across all requests within a session.
 
-    If vector sync is enabled (VECTOR_SYNC_ENABLED=true), also starts
-    background tasks for automatic document indexing (ADR-007).
+    Note: Background tasks (scanner, processor) are started at server level
+    in starlette_lifespan, not here. This lifespan runs per-session.
     """
-    logger.info("Starting MCP server in BasicAuth mode")
+    logger.info("Starting MCP session in BasicAuth mode")
     logger.info("Creating Nextcloud client with BasicAuth")
 
     client = NextcloudClient.from_env()
@@ -579,91 +600,20 @@ async def app_lifespan_basic(server: FastMCP) -> AsyncIterator[AppContext]:
     # Initialize document processors
     initialize_document_processors()
 
-    settings = get_settings()
-
-    # Check if vector sync is enabled
-    if settings.vector_sync_enabled:
-        logger.info("Vector sync enabled - starting background tasks")
-
-        # Get username from environment for BasicAuth mode
-        username = os.getenv("NEXTCLOUD_USERNAME")
-        if not username:
-            raise ValueError(
-                "NEXTCLOUD_USERNAME is required for vector sync in BasicAuth mode"
-            )
-
-        # Initialize Qdrant collection before starting background tasks
-        logger.info("Initializing Qdrant collection...")
-        from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
-        try:
-            await get_qdrant_client()  # Triggers collection creation if needed
-            logger.info("Qdrant collection ready")
-        except Exception as e:
-            logger.error(f"Failed to initialize Qdrant collection: {e}")
-            raise RuntimeError(
-                f"Cannot start vector sync - Qdrant initialization failed: {e}"
-            ) from e
-
-        # Initialize shared state
-        send_stream, receive_stream = anyio.create_memory_object_stream(
-            max_buffer_size=settings.vector_sync_queue_max_size
+    # Yield client context - scanner runs at server level (starlette_lifespan)
+    # Include vector sync state from module singleton (set by starlette_lifespan)
+    try:
+        yield AppContext(
+            client=client,
+            storage=storage,
+            document_send_stream=_vector_sync_state.document_send_stream,
+            document_receive_stream=_vector_sync_state.document_receive_stream,
+            shutdown_event=_vector_sync_state.shutdown_event,
+            scanner_wake_event=_vector_sync_state.scanner_wake_event,
         )
-        shutdown_event = anyio.Event()
-        scanner_wake_event = anyio.Event()
-
-        # Start background tasks using anyio TaskGroup
-        async with anyio.create_task_group() as tg:
-            # Start scanner task
-            await tg.start(
-                scanner_task,
-                send_stream,
-                shutdown_event,
-                scanner_wake_event,
-                client,
-                username,
-            )
-
-            # Start processor pool (each gets a cloned receive stream)
-            for i in range(settings.vector_sync_processor_workers):
-                await tg.start(
-                    processor_task,
-                    i,
-                    receive_stream.clone(),
-                    shutdown_event,
-                    client,
-                    username,
-                )
-
-            logger.info(
-                f"Background sync tasks started: 1 scanner + {settings.vector_sync_processor_workers} processors"
-            )
-
-            # Yield with background tasks running
-            try:
-                yield AppContext(
-                    client=client,
-                    storage=storage,
-                    document_send_stream=send_stream,
-                    document_receive_stream=receive_stream,
-                    shutdown_event=shutdown_event,
-                    scanner_wake_event=scanner_wake_event,
-                )
-            finally:
-                # Shutdown signal
-                logger.info("Shutting down background sync tasks")
-                shutdown_event.set()
-
-                # TaskGroup automatically cancels all tasks on exit
-                logger.info("Background sync tasks stopped")
-                await client.close()
-    else:
-        # No vector sync - simple lifecycle
-        try:
-            yield AppContext(client=client, storage=storage)
-        finally:
-            logger.info("Shutting down BasicAuth mode")
-            await client.close()
+    finally:
+        logger.info("Shutting down BasicAuth session")
+        await client.close()
 
 
 async def setup_oauth_config():
@@ -726,6 +676,29 @@ async def setup_oauth_config():
         logger.info(f"OIDC_JWKS_URI override: {jwks_uri} → {jwks_uri_override}")
         jwks_uri = jwks_uri_override
 
+    # Rewrite discovered endpoint URLs from public issuer to internal host
+    # This is needed when OIDC discovery returns public URLs (e.g., http://localhost:8080)
+    # but the server needs to access them via internal docker network (e.g., http://app:80)
+    from urllib.parse import urlparse
+
+    issuer_parsed = urlparse(issuer)
+    nextcloud_parsed = urlparse(nextcloud_host)
+    issuer_base = f"{issuer_parsed.scheme}://{issuer_parsed.netloc}"
+    nextcloud_base = f"{nextcloud_parsed.scheme}://{nextcloud_parsed.netloc}"
+
+    if issuer_base != nextcloud_base:
+        logger.info(f"Rewriting OIDC endpoints: {issuer_base} → {nextcloud_base}")
+
+        def rewrite_url(url: str | None) -> str | None:
+            if url and url.startswith(issuer_base):
+                return url.replace(issuer_base, nextcloud_base, 1)
+            return url
+
+        userinfo_uri = rewrite_url(userinfo_uri) or userinfo_uri
+        jwks_uri = rewrite_url(jwks_uri)
+        introspection_uri = rewrite_url(introspection_uri)
+        registration_endpoint = rewrite_url(registration_endpoint)
+
     logger.info("OIDC endpoints discovered:")
     logger.info(f"  Issuer: {issuer}")
     logger.info(f"  Userinfo: {userinfo_uri}")
@@ -737,8 +710,6 @@ async def setup_oauth_config():
     # Auto-detect provider mode based on issuer
     # External IdP mode: issuer doesn't match Nextcloud host
     # Normalize URLs for comparison (handle port differences like :80 for HTTP)
-    from urllib.parse import urlparse
-
     def normalize_url(url: str) -> str:
         """Normalize URL by removing default ports (80 for HTTP, 443 for HTTPS)."""
         parsed = urlparse(url)
@@ -754,7 +725,16 @@ async def setup_oauth_config():
     issuer_normalized = normalize_url(issuer)
     nextcloud_normalized = normalize_url(nextcloud_host)
 
-    is_external_idp = not issuer_normalized.startswith(nextcloud_normalized)
+    # Use NEXTCLOUD_PUBLIC_ISSUER_URL for IdP detection when set
+    # This handles the case where MCP server accesses Nextcloud via internal URL (http://app:80)
+    # but the issuer in OIDC discovery is the public URL (http://localhost:8080)
+    public_issuer_for_detection = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+    if public_issuer_for_detection:
+        comparison_issuer = normalize_url(public_issuer_for_detection)
+    else:
+        comparison_issuer = nextcloud_normalized
+
+    is_external_idp = not issuer_normalized.startswith(comparison_issuer)
 
     if is_external_idp:
         oauth_provider = "external"  # Could be Keycloak, Auth0, Okta, etc.
@@ -766,6 +746,28 @@ async def setup_oauth_config():
         oauth_provider = "nextcloud"
         logger.info("✓ Detected integrated mode (Nextcloud OIDC app)")
 
+        # For integrated mode, rewrite OIDC endpoints to use internal URL
+        # The discovery document returns external URLs (http://localhost:8080)
+        # but the MCP server needs internal URLs (http://app:80) for backend requests
+        if jwks_uri and not os.getenv("OIDC_JWKS_URI"):
+            internal_jwks_uri = f"{nextcloud_host}/apps/oidc/jwks"
+            logger.info(
+                f"  Auto-rewriting JWKS URI for internal access: {jwks_uri} → {internal_jwks_uri}"
+            )
+            jwks_uri = internal_jwks_uri
+        if introspection_uri and not os.getenv("OIDC_INTROSPECTION_URI"):
+            internal_introspection_uri = f"{nextcloud_host}/apps/oidc/introspect"
+            logger.info(
+                f"  Auto-rewriting introspection URI for internal access: {introspection_uri} → {internal_introspection_uri}"
+            )
+            introspection_uri = internal_introspection_uri
+        if userinfo_uri:
+            internal_userinfo_uri = f"{nextcloud_host}/apps/oidc/userinfo"
+            logger.info(
+                f"  Auto-rewriting userinfo URI for internal access: {userinfo_uri} → {internal_userinfo_uri}"
+            )
+            userinfo_uri = internal_userinfo_uri
+
     # Check if offline access (refresh tokens) is enabled
     enable_offline_access = os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() in (
         "true",
@@ -979,7 +981,7 @@ async def setup_oauth_config():
     )
 
 
-def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
+def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None = None):
     # Initialize observability (logging will be configured by uvicorn)
     settings = get_settings()
 
@@ -1067,6 +1069,11 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
             lifespan=oauth_lifespan,
             token_verifier=token_verifier,
             auth=auth_settings,
+            # Disable DNS rebinding protection for containerized deployments (k8s, Docker)
+            # MCP 1.23+ auto-enables this for localhost, breaking k8s service DNS names
+            transport_security=TransportSecuritySettings(
+                enable_dns_rebinding_protection=False
+            ),
         )
     else:
         # ADR-016: Use Smithery lifespan for stateless mode, BasicAuth otherwise
@@ -1075,11 +1082,26 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
             # json_response=True returns plain JSON-RPC instead of SSE format,
             # required for Smithery scanner compatibility
             mcp = FastMCP(
-                "Nextcloud MCP", lifespan=app_lifespan_smithery, json_response=True
+                "Nextcloud MCP",
+                lifespan=app_lifespan_smithery,
+                json_response=True,
+                # Disable DNS rebinding protection for containerized deployments (k8s, Docker)
+                # MCP 1.23+ auto-enables this for localhost, breaking k8s service DNS names
+                transport_security=TransportSecuritySettings(
+                    enable_dns_rebinding_protection=False
+                ),
             )
         else:
             logger.info("Configuring MCP server for BasicAuth mode")
-            mcp = FastMCP("Nextcloud MCP", lifespan=app_lifespan_basic)
+            mcp = FastMCP(
+                "Nextcloud MCP",
+                lifespan=app_lifespan_basic,
+                # Disable DNS rebinding protection for containerized deployments (k8s, Docker)
+                # MCP 1.23+ auto-enables this for localhost, breaking k8s service DNS names
+                transport_security=TransportSecuritySettings(
+                    enable_dns_rebinding_protection=False
+                ),
+            )
 
     @mcp.resource("nc://capabilities")
     async def nc_get_capabilities():
@@ -1098,6 +1120,7 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
         "contacts": configure_contacts_tools,
         "cookbook": configure_cookbook_tools,
         "deck": configure_deck_tools,
+        "news": configure_news_tools,
     }
 
     # If no specific apps are specified, enable all
@@ -1197,180 +1220,347 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
             "Dynamic tool filtering enabled for OAuth mode (JWT and Bearer tokens)"
         )
 
-    if transport == "sse":
-        mcp_app = mcp.sse_app()
-        starlette_lifespan = None
-    elif transport in ("http", "streamable-http"):
-        mcp_app = mcp.streamable_http_app()
+    mcp_app = mcp.streamable_http_app()
 
-        @asynccontextmanager
-        async def starlette_lifespan(app: Starlette):
-            # Set OAuth context for OAuth login routes (ADR-004)
-            if oauth_enabled:
-                # Prepare OAuth config from setup_oauth_config closure variables
-                mcp_server_url = os.getenv(
-                    "NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000"
-                )
-                nextcloud_resource_uri = os.getenv(
-                    "NEXTCLOUD_RESOURCE_URI", nextcloud_host
-                )
-                discovery_url = os.getenv(
-                    "OIDC_DISCOVERY_URL",
-                    f"{nextcloud_host}/.well-known/openid-configuration",
-                )
-                scopes = os.getenv("NEXTCLOUD_OIDC_SCOPES", "")
+    @asynccontextmanager
+    async def starlette_lifespan(app: Starlette):
+        # Set OAuth context for OAuth login routes (ADR-004)
+        if oauth_enabled:
+            # Prepare OAuth config from setup_oauth_config closure variables
+            mcp_server_url = os.getenv(
+                "NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000"
+            )
+            nextcloud_resource_uri = os.getenv("NEXTCLOUD_RESOURCE_URI", nextcloud_host)
+            discovery_url = os.getenv(
+                "OIDC_DISCOVERY_URL",
+                f"{nextcloud_host}/.well-known/openid-configuration",
+            )
+            scopes = os.getenv("NEXTCLOUD_OIDC_SCOPES", "")
 
-                oauth_context_dict = {
-                    "storage": refresh_token_storage,
-                    "oauth_client": oauth_client,
-                    "token_verifier": token_verifier,  # For querying IdP userinfo endpoint
-                    "config": {
-                        "mcp_server_url": mcp_server_url,
-                        "discovery_url": discovery_url,
-                        "client_id": client_id,  # From setup_oauth_config (DCR or static)
-                        "client_secret": client_secret,  # From setup_oauth_config (DCR or static)
-                        "scopes": scopes,
-                        "nextcloud_host": nextcloud_host,
-                        "nextcloud_resource_uri": nextcloud_resource_uri,
-                        "oauth_provider": oauth_provider,
-                    },
-                }
-                app.state.oauth_context = oauth_context_dict
+            oauth_context_dict = {
+                "storage": refresh_token_storage,
+                "oauth_client": oauth_client,
+                "token_verifier": token_verifier,  # For querying IdP userinfo endpoint
+                "config": {
+                    "mcp_server_url": mcp_server_url,
+                    "discovery_url": discovery_url,
+                    "client_id": client_id,  # From setup_oauth_config (DCR or static)
+                    "client_secret": client_secret,  # From setup_oauth_config (DCR or static)
+                    "scopes": scopes,
+                    "nextcloud_host": nextcloud_host,
+                    "nextcloud_resource_uri": nextcloud_resource_uri,
+                    "oauth_provider": oauth_provider,
+                },
+            }
+            app.state.oauth_context = oauth_context_dict
 
-                # Also set oauth_context on browser_app for session authentication
-                # browser_app is in the same function scope (defined later in create_app)
-                # We need to find it in the mounted routes
-                for route in app.routes:
-                    if isinstance(route, Mount) and route.path == "/app":
-                        route.app.state.oauth_context = oauth_context_dict
-                        logger.info(
-                            "OAuth context shared with browser_app for session auth"
-                        )
-                        break
-
-                logger.info(
-                    f"OAuth context initialized for login routes (client_id={client_id[:16]}...)"
-                )
-            else:
-                # BasicAuth mode - share storage with browser_app for webhook management
-                from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
-                storage = RefreshTokenStorage.from_env()
-                await storage.initialize()
-
-                app.state.storage = storage
-
-                # Also share with browser_app for webhook routes
-                for route in app.routes:
-                    if isinstance(route, Mount) and route.path == "/app":
-                        route.app.state.storage = storage
-                        logger.info(
-                            "Storage shared with browser_app for webhook management"
-                        )
-                        break
-
-            # Start background vector sync tasks for BasicAuth mode (ADR-007)
-            # For streamable-http transport, FastMCP lifespan isn't automatically triggered
-            # so we manually start background tasks here if vector sync is enabled
-            import anyio as anyio_module
-
-            settings = get_settings()
-            if not oauth_enabled and settings.vector_sync_enabled:
-                logger.info("Starting background vector sync tasks for BasicAuth mode")
-
-                # Get username from environment
-                username = os.getenv("NEXTCLOUD_USERNAME")
-                if not username:
-                    raise ValueError(
-                        "NEXTCLOUD_USERNAME required for vector sync in BasicAuth mode"
+            # Also set oauth_context on browser_app for session authentication
+            # browser_app is in the same function scope (defined later in create_app)
+            # We need to find it in the mounted routes
+            for route in app.routes:
+                if isinstance(route, Mount) and route.path == "/app":
+                    browser_app = cast(Starlette, route.app)
+                    browser_app.state.oauth_context = oauth_context_dict
+                    logger.info(
+                        "OAuth context shared with browser_app for session auth"
                     )
+                    break
 
-                # Get Nextcloud client from MCP app context
-                # Create client since we're outside FastMCP lifespan
-                client = NextcloudClient.from_env()
+            logger.info(
+                f"OAuth context initialized for login routes (client_id={client_id[:16]}...)"
+            )
+        else:
+            # BasicAuth mode - share storage with browser_app for webhook management
+            from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 
-                # Initialize Qdrant collection before starting background tasks
-                logger.info("Initializing Qdrant collection...")
-                from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+            storage = RefreshTokenStorage.from_env()
+            await storage.initialize()
 
-                try:
-                    await get_qdrant_client()  # Triggers collection creation if needed
-                    logger.info("Qdrant collection ready")
-                except Exception as e:
-                    logger.error(f"Failed to initialize Qdrant collection: {e}")
-                    raise RuntimeError(
-                        f"Cannot start vector sync - Qdrant initialization failed: {e}"
-                    ) from e
+            app.state.storage = storage
 
-                # Initialize shared state
-                send_stream, receive_stream = anyio_module.create_memory_object_stream(
-                    max_buffer_size=settings.vector_sync_queue_max_size
+            # Also share with browser_app for webhook routes
+            for route in app.routes:
+                if isinstance(route, Mount) and route.path == "/app":
+                    browser_app = cast(Starlette, route.app)
+                    browser_app.state.storage = storage
+                    logger.info(
+                        "Storage shared with browser_app for webhook management"
+                    )
+                    break
+
+        # Start background vector sync tasks (ADR-007)
+        # Scanner runs at server-level (once), not per-session
+        import anyio as anyio_module
+
+        settings = get_settings()
+
+        # Check if vector sync is enabled and determine the mode
+        enable_offline_access_for_sync = os.getenv(
+            "ENABLE_OFFLINE_ACCESS", "false"
+        ).lower() in ("true", "1", "yes")
+        encryption_key = os.getenv("TOKEN_ENCRYPTION_KEY")
+
+        if settings.vector_sync_enabled and not oauth_enabled:
+            # BasicAuth mode - single user sync
+            logger.info("Starting background vector sync tasks for BasicAuth mode")
+
+            # Get username from environment
+            username = os.getenv("NEXTCLOUD_USERNAME")
+            if not username:
+                raise ValueError(
+                    "NEXTCLOUD_USERNAME required for vector sync in BasicAuth mode"
                 )
-                shutdown_event = anyio_module.Event()
-                scanner_wake_event = anyio_module.Event()
 
-                # Store in app state for access from routes (ADR-007)
-                app.state.document_send_stream = send_stream
-                app.state.document_receive_stream = receive_stream
-                app.state.shutdown_event = shutdown_event
-                app.state.scanner_wake_event = scanner_wake_event
+            # Create client for vector sync (server-level, not per-session)
+            client = NextcloudClient.from_env()
 
-                # Also share with browser_app for /app route
-                for route in app.routes:
-                    if isinstance(route, Mount) and route.path == "/app":
-                        route.app.state.document_send_stream = send_stream
-                        route.app.state.document_receive_stream = receive_stream
-                        route.app.state.shutdown_event = shutdown_event
-                        route.app.state.scanner_wake_event = scanner_wake_event
-                        logger.info(
-                            "Vector sync state shared with browser_app for /app"
-                        )
-                        break
+            # Initialize Qdrant collection before starting background tasks
+            logger.info("Initializing Qdrant collection...")
+            from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
 
-                # Start background tasks using anyio TaskGroup
-                async with anyio_module.create_task_group() as tg:
-                    # Start scanner task
+            try:
+                await get_qdrant_client()  # Triggers collection creation if needed
+                logger.info("Qdrant collection ready")
+            except Exception as e:
+                logger.error(f"Failed to initialize Qdrant collection: {e}")
+                raise RuntimeError(
+                    f"Cannot start vector sync - Qdrant initialization failed: {e}"
+                ) from e
+
+            # Initialize shared state
+            send_stream, receive_stream = anyio_module.create_memory_object_stream(
+                max_buffer_size=settings.vector_sync_queue_max_size
+            )
+            shutdown_event = anyio_module.Event()
+            scanner_wake_event = anyio_module.Event()
+
+            # Store in app state for access from routes (ADR-007)
+            app.state.document_send_stream = send_stream
+            app.state.document_receive_stream = receive_stream
+            app.state.shutdown_event = shutdown_event
+            app.state.scanner_wake_event = scanner_wake_event
+
+            # Also store in module singleton for FastMCP session lifespans
+            _vector_sync_state.document_send_stream = send_stream
+            _vector_sync_state.document_receive_stream = receive_stream
+            _vector_sync_state.shutdown_event = shutdown_event
+            _vector_sync_state.scanner_wake_event = scanner_wake_event
+            logger.info("Vector sync state stored in module singleton")
+
+            # Also share with browser_app for /app route
+            for route in app.routes:
+                if isinstance(route, Mount) and route.path == "/app":
+                    browser_app = cast(Starlette, route.app)
+                    browser_app.state.document_send_stream = send_stream
+                    browser_app.state.document_receive_stream = receive_stream
+                    browser_app.state.shutdown_event = shutdown_event
+                    browser_app.state.scanner_wake_event = scanner_wake_event
+                    logger.info("Vector sync state shared with browser_app for /app")
+                    break
+
+            # Start background tasks using anyio TaskGroup
+            async with anyio_module.create_task_group() as tg:
+                # Start scanner task
+                await tg.start(
+                    scanner_task,
+                    send_stream,
+                    shutdown_event,
+                    scanner_wake_event,
+                    client,
+                    username,
+                )
+
+                # Start processor pool (each gets a cloned receive stream)
+                for i in range(settings.vector_sync_processor_workers):
                     await tg.start(
-                        scanner_task,
-                        send_stream,
+                        processor_task,
+                        i,
+                        receive_stream.clone(),
                         shutdown_event,
-                        scanner_wake_event,
                         client,
                         username,
                     )
 
-                    # Start processor pool (each gets a cloned receive stream)
-                    for i in range(settings.vector_sync_processor_workers):
-                        await tg.start(
-                            processor_task,
-                            i,
-                            receive_stream.clone(),
-                            shutdown_event,
-                            client,
-                            username,
-                        )
+                logger.info(
+                    f"Background sync tasks started: 1 scanner + "
+                    f"{settings.vector_sync_processor_workers} processors"
+                )
 
-                    logger.info(
-                        f"Background sync tasks started: 1 scanner + "
-                        f"{settings.vector_sync_processor_workers} processors"
-                    )
-
-                    # Run MCP session manager and yield
-                    async with AsyncExitStack() as stack:
-                        await stack.enter_async_context(mcp.session_manager.run())
-                        try:
-                            yield
-                        finally:
-                            # Shutdown signal
-                            logger.info("Shutting down background sync tasks")
-                            shutdown_event.set()
-                            await client.close()
-                            # TaskGroup automatically cancels all tasks on exit
-            else:
-                # No vector sync - just run MCP session manager
+                # Run MCP session manager and yield
                 async with AsyncExitStack() as stack:
                     await stack.enter_async_context(mcp.session_manager.run())
-                    yield
+                    try:
+                        yield
+                    finally:
+                        # Shutdown signal
+                        logger.info("Shutting down background sync tasks")
+                        shutdown_event.set()
+                        await client.close()
+                        # TaskGroup automatically cancels all tasks on exit
+
+        elif (
+            settings.vector_sync_enabled
+            and oauth_enabled
+            and enable_offline_access_for_sync
+            and refresh_token_storage
+            and encryption_key
+        ):
+            # OAuth mode with offline access - multi-user sync
+            logger.info("Starting background vector sync tasks for OAuth mode")
+
+            from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
+            from nextcloud_mcp_server.vector.oauth_sync import (
+                oauth_processor_task,
+                user_manager_task,
+            )
+
+            # Get OIDC discovery URL (same as used for OAuth setup)
+            discovery_url = os.getenv(
+                "OIDC_DISCOVERY_URL",
+                f"{nextcloud_host}/.well-known/openid-configuration",
+            )
+
+            # Get client credentials from oauth_context (set by setup_oauth_config)
+            # This includes credentials from DCR if dynamic registration was used
+            # Use different variable names to avoid shadowing client_id/client_secret from outer scope
+            oauth_ctx = getattr(app.state, "oauth_context", {})
+            oauth_config = oauth_ctx.get("config", {})
+            sync_client_id = oauth_config.get("client_id")
+            sync_client_secret = oauth_config.get("client_secret")
+
+            if not sync_client_id or not sync_client_secret:
+                logger.error(
+                    "Cannot start OAuth vector sync: client credentials not found in oauth_context"
+                )
+                raise ValueError("OAuth client credentials required for vector sync")
+
+            # Create token broker for background operations
+            # Note: storage handles encryption internally, no key needed here
+            # Client credentials are needed for token refresh operations
+            token_broker = TokenBrokerService(
+                storage=refresh_token_storage,
+                oidc_discovery_url=discovery_url,
+                nextcloud_host=nextcloud_host,
+                client_id=sync_client_id,
+                client_secret=sync_client_secret,
+            )
+
+            # Store token broker in oauth_context for management API (revoke endpoint)
+            if hasattr(app.state, "oauth_context"):
+                app.state.oauth_context["token_broker"] = token_broker
+                logger.info("Token broker added to oauth_context for management API")
+
+            # Initialize Qdrant collection before starting background tasks
+            logger.info("Initializing Qdrant collection...")
+            from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+            try:
+                await get_qdrant_client()  # Triggers collection creation if needed
+                logger.info("Qdrant collection ready")
+            except Exception as e:
+                logger.error(f"Failed to initialize Qdrant collection: {e}")
+                raise RuntimeError(
+                    f"Cannot start vector sync - Qdrant initialization failed: {e}"
+                ) from e
+
+            # Initialize shared state
+            send_stream, receive_stream = anyio_module.create_memory_object_stream(
+                max_buffer_size=settings.vector_sync_queue_max_size
+            )
+            shutdown_event = anyio_module.Event()
+            scanner_wake_event = anyio_module.Event()
+
+            # User state tracking for user manager
+            user_states: dict = {}
+
+            # Store in app state for access from routes (ADR-007)
+            app.state.document_send_stream = send_stream
+            app.state.document_receive_stream = receive_stream
+            app.state.shutdown_event = shutdown_event
+            app.state.scanner_wake_event = scanner_wake_event
+
+            # Also store in module singleton for FastMCP session lifespans
+            _vector_sync_state.document_send_stream = send_stream
+            _vector_sync_state.document_receive_stream = receive_stream
+            _vector_sync_state.shutdown_event = shutdown_event
+            _vector_sync_state.scanner_wake_event = scanner_wake_event
+            logger.info("Vector sync state stored in module singleton")
+
+            # Also share with browser_app for /app route
+            for route in app.routes:
+                if isinstance(route, Mount) and route.path == "/app":
+                    browser_app = cast(Starlette, route.app)
+                    browser_app.state.document_send_stream = send_stream
+                    browser_app.state.document_receive_stream = receive_stream
+                    browser_app.state.shutdown_event = shutdown_event
+                    browser_app.state.scanner_wake_event = scanner_wake_event
+                    logger.info("Vector sync state shared with browser_app for /app")
+                    break
+
+            # Start background tasks using anyio TaskGroup
+            async with anyio_module.create_task_group() as tg:
+                # Start user manager task (supervises per-user scanners)
+                await tg.start(
+                    user_manager_task,
+                    send_stream,
+                    shutdown_event,
+                    scanner_wake_event,
+                    token_broker,
+                    refresh_token_storage,
+                    nextcloud_host,
+                    user_states,
+                    tg,
+                )
+
+                # Start processor pool (each gets a cloned receive stream)
+                for i in range(settings.vector_sync_processor_workers):
+                    await tg.start(
+                        oauth_processor_task,
+                        i,
+                        receive_stream.clone(),
+                        shutdown_event,
+                        token_broker,
+                        nextcloud_host,
+                    )
+
+                logger.info(
+                    f"Background sync tasks started: 1 user manager + "
+                    f"{settings.vector_sync_processor_workers} processors"
+                )
+
+                # Run MCP session manager and yield
+                async with AsyncExitStack() as stack:
+                    await stack.enter_async_context(mcp.session_manager.run())
+                    try:
+                        yield
+                    finally:
+                        # Shutdown signal
+                        logger.info("Shutting down background sync tasks")
+                        shutdown_event.set()
+                        # Close token broker HTTP client
+                        if token_broker._http_client:
+                            await token_broker._http_client.aclose()
+                        # TaskGroup automatically cancels all tasks on exit
+        else:
+            # No vector sync - just run MCP session manager
+            if settings.vector_sync_enabled:
+                # Log why vector sync is not starting
+                if oauth_enabled and not enable_offline_access_for_sync:
+                    logger.warning(
+                        "Vector sync enabled but ENABLE_OFFLINE_ACCESS=false - "
+                        "vector sync requires offline access in OAuth mode"
+                    )
+                elif oauth_enabled and not refresh_token_storage:
+                    logger.warning(
+                        "Vector sync enabled but refresh token storage not available"
+                    )
+                elif oauth_enabled and not encryption_key:
+                    logger.warning(
+                        "Vector sync enabled but TOKEN_ENCRYPTION_KEY not set"
+                    )
+            async with AsyncExitStack() as stack:
+                await stack.enter_async_context(mcp.session_manager.run())
+                yield
 
     # Health check endpoints for Kubernetes probes
     def health_live(request):
@@ -1523,6 +1713,66 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     )
     logger.info("Test webhook endpoint enabled: /webhooks/nextcloud")
 
+    # Add management API endpoints for Nextcloud PHP app (OAuth mode only)
+    if oauth_enabled:
+        from nextcloud_mcp_server.api.management import (
+            create_webhook,
+            delete_webhook,
+            get_chunk_context,
+            get_installed_apps,
+            get_server_status,
+            get_user_session,
+            get_vector_sync_status,
+            list_webhooks,
+            revoke_user_access,
+            unified_search,
+            vector_search,
+        )
+
+        routes.append(Route("/api/v1/status", get_server_status, methods=["GET"]))
+        routes.append(
+            Route(
+                "/api/v1/vector-sync/status",
+                get_vector_sync_status,
+                methods=["GET"],
+            )
+        )
+        routes.append(
+            Route(
+                "/api/v1/users/{user_id}/session",
+                get_user_session,
+                methods=["GET"],
+            )
+        )
+        routes.append(
+            Route(
+                "/api/v1/users/{user_id}/revoke",
+                revoke_user_access,
+                methods=["POST"],
+            )
+        )
+        routes.append(
+            Route("/api/v1/vector-viz/search", vector_search, methods=["POST"])
+        )
+        routes.append(
+            Route("/api/v1/chunk-context", get_chunk_context, methods=["GET"])
+        )
+        # ADR-018: Unified search endpoint for Nextcloud PHP app integration
+        routes.append(Route("/api/v1/search", unified_search, methods=["POST"]))
+        routes.append(Route("/api/v1/apps", get_installed_apps, methods=["GET"]))
+        # Webhook management endpoints
+        routes.append(Route("/api/v1/webhooks", list_webhooks, methods=["GET"]))
+        routes.append(Route("/api/v1/webhooks", create_webhook, methods=["POST"]))
+        routes.append(
+            Route("/api/v1/webhooks/{webhook_id}", delete_webhook, methods=["DELETE"])
+        )
+        logger.info(
+            "Management API endpoints enabled: /api/v1/status, /api/v1/vector-sync/status, "
+            "/api/v1/users/{user_id}/session, /api/v1/users/{user_id}/revoke, "
+            "/api/v1/vector-viz/search, /api/v1/search, /api/v1/apps, "
+            "/api/v1/webhooks"
+        )
+
     # ADR-016: Add Smithery well-known config endpoint for container runtime discovery
     if deployment_mode == DeploymentMode.SMITHERY_STATELESS:
 

nextcloud_mcp_server/auth/browser_oauth_routes.py

@@ -24,6 +24,26 @@ 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.
 
@@ -50,6 +70,10 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
     logger.info(f"oauth_login called - client_id: {oauth_config.get('client_id')}")
     logger.info(f"oauth_login called - oauth_client: {oauth_client is not None}")
 
+    # Get redirect URL from query params (default to /app)
+    next_url = request.query_params.get("next", "/app")
+    logger.info(f"oauth_login - next_url: {next_url}")
+
     # Generate state for CSRF protection
     state = secrets.token_urlsafe(32)
 
@@ -71,7 +95,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
     await storage.store_oauth_session(
         session_id=state,  # Use state as session ID
         client_id="browser-ui",
-        client_redirect_uri="/app",
+        client_redirect_uri=next_url,  # Store the redirect URL for after auth
         state=state,
         code_challenge=code_challenge,
         code_challenge_method="S256",
@@ -85,6 +109,11 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
         if not oauth_client.authorization_endpoint:
             await oauth_client.discover()
 
+        # Get Nextcloud resource URI for audience (background sync needs Nextcloud-scoped tokens)
+        nextcloud_resource_uri = oauth_config.get(
+            "nextcloud_resource_uri", oauth_config.get("nextcloud_host")
+        )
+
         idp_params = {
             "client_id": oauth_client.client_id,
             "redirect_uri": callback_uri,
@@ -94,6 +123,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
             "code_challenge": code_challenge,
             "code_challenge_method": "S256",
             "prompt": "consent",  # Ensure refresh token
+            "resource": nextcloud_resource_uri,  # Request tokens for Nextcloud API access
         }
 
         auth_url = f"{oauth_client.authorization_endpoint}?{urlencode(idp_params)}"
@@ -131,6 +161,11 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
                     f"{public_parsed.scheme}://{public_parsed.netloc}{auth_parsed.path}"
                 )
 
+        # Get Nextcloud resource URI for audience (background sync needs Nextcloud-scoped tokens)
+        nextcloud_resource_uri = oauth_config.get(
+            "nextcloud_resource_uri", oauth_config.get("nextcloud_host")
+        )
+
         idp_params = {
             "client_id": oauth_config["client_id"],
             "redirect_uri": callback_uri,
@@ -140,6 +175,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
             "code_challenge": code_challenge,
             "code_challenge_method": "S256",
             "prompt": "consent",  # Ensure refresh token
+            "resource": nextcloud_resource_uri,  # Request tokens for Nextcloud API access
         }
 
         # Debug: Log full parameters
@@ -214,12 +250,15 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
     oauth_client = oauth_ctx["oauth_client"]
     oauth_config = oauth_ctx["config"]
 
-    # Retrieve code_verifier from session storage (PKCE required for all modes)
+    # Retrieve code_verifier and redirect URL from session storage
     code_verifier = ""
+    next_url = "/app"  # Default redirect
     oauth_session = await storage.get_oauth_session(state)
     if oauth_session:
         # code_verifier was stored in mcp_authorization_code field
         code_verifier = oauth_session.get("mcp_authorization_code", "")
+        # next_url was stored in client_redirect_uri field
+        next_url = oauth_session.get("client_redirect_uri", "/app")
         # Clean up the temporary session
         # Note: We don't have delete_oauth_session method, but it will expire after TTL
 
@@ -262,6 +301,25 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
                 discovery = response.json()
                 token_endpoint = discovery["token_endpoint"]
 
+            # Rewrite token_endpoint from public URL to internal Docker URL
+            # Discovery document returns public URLs (e.g., http://localhost:8080/...)
+            # but server-side requests must use internal Docker network (e.g., http://app:80/...)
+            public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+            if public_issuer:
+                from urllib.parse import urlparse as parse_url
+
+                internal_host = oauth_config["nextcloud_host"]
+                internal_parsed = parse_url(internal_host)
+                token_parsed = parse_url(token_endpoint)
+                public_parsed = parse_url(public_issuer)
+
+                if token_parsed.hostname == public_parsed.hostname:
+                    # Replace public URL with internal Docker URL
+                    token_endpoint = f"{internal_parsed.scheme}://{internal_parsed.netloc}{token_parsed.path}"
+                    logger.info(
+                        f"Rewrote token endpoint to internal URL: {token_endpoint}"
+                    )
+
             token_params = {
                 "grant_type": "authorization_code",
                 "code": code,
@@ -338,16 +396,35 @@ 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:
+        import time
+
+        refresh_expires_at = int(time.time()) + refresh_expires_in
+        logger.info(
+            f"Refresh token expires in {refresh_expires_in}s (at timestamp {refresh_expires_at})"
+        )
+
+    # Extract granted scopes
+    granted_scopes = (
+        token_data.get("scope", "").split() if token_data.get("scope") else None
+    )
+
     # Store refresh token (for background jobs ONLY)
     if refresh_token:
         logger.info(f"Storing refresh token for user_id: {user_id}")
         logger.info(f"  State parameter (provisioning_client_id): {state[:16]}...")
+        logger.info(f"  Granted scopes: {granted_scopes}")
+        logger.info(f"  Expires at: {refresh_expires_at}")
         await storage.store_refresh_token(
             user_id=user_id,
             refresh_token=refresh_token,
-            expires_at=None,
+            expires_at=refresh_expires_at,
             flow_type="browser",  # Browser-based login flow
             provisioning_client_id=state,  # Store state for unified session lookup
+            scopes=granted_scopes,
         )
         logger.info(f"✓ Refresh token stored successfully for user_id: {user_id}")
         logger.info(
@@ -383,13 +460,14 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
             # Continue anyway - profile cache is optional for browser UI
 
     # Create response and set session cookie
-    response = RedirectResponse("/app", status_code=302)
+    # Redirect to stored next_url (from OAuth session) or /app as default
+    response = RedirectResponse(next_url, status_code=302)
     response.set_cookie(
         key="mcp_session",
         value=user_id,
         max_age=86400 * 30,  # 30 days
         httponly=True,
-        secure=False,  # Set to True in production with HTTPS
+        secure=_should_use_secure_cookies(),
         samesite="lax",
     )
 

nextcloud_mcp_server/auth/oauth_routes.py

@@ -517,12 +517,23 @@ 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:
+            import time
+
+            refresh_expires_at = int(time.time()) + refresh_expires_in
+            logger.info(f"  refresh_expires_in: {refresh_expires_in}s")
+            logger.info(f"  refresh_expires_at: {refresh_expires_at}")
+
         logger.info("Storing refresh token:")
         logger.info(f"  user_id: {user_id}")
         logger.info("  flow_type: flow2")
         logger.info("  token_audience: nextcloud")
         logger.info(f"  provisioning_client_id: {state[:16]}...")
         logger.info(f"  scopes: {granted_scopes}")
+        logger.info(f"  expires_at: {refresh_expires_at}")
 
         await storage.store_refresh_token(
             user_id=user_id,
@@ -531,7 +542,7 @@ async def oauth_callback_nextcloud(request: Request):
             token_audience="nextcloud",
             provisioning_client_id=state,  # Store which client initiated provisioning
             scopes=granted_scopes,
-            expires_at=None,  # Refresh tokens typically don't expire
+            expires_at=refresh_expires_at,
         )
         logger.info(f"✓ Stored Flow 2 master refresh token for user {user_id}")
         logger.info("=" * 60)

nextcloud_mcp_server/auth/static/vector-viz.js

@@ -201,8 +201,15 @@ function vizApp() {
                     return `${baseUrl}/apps/calendar`;
                 case 'contact':
                     return `${baseUrl}/apps/contacts`;
-                case 'deck':
+                case 'deck_card':
+                    // URL pattern: /apps/deck/board/:boardId/card/:cardId
+                    if (result.metadata && result.metadata.board_id) {
+                        return `${baseUrl}/apps/deck/board/${result.metadata.board_id}/card/${result.id}`;
+                    }
+                    // Fallback if board_id not available
                     return `${baseUrl}/apps/deck`;
+                case 'news_item':
+                    return `${baseUrl}/apps/news/item/${result.id}`;
                 default:
                     return `${baseUrl}`;
             }

nextcloud_mcp_server/auth/storage.py

@@ -117,7 +117,14 @@ class RefreshTokenStorage:
         return cls(db_path=db_path, encryption_key=encryption_key)
 
     async def initialize(self) -> None:
-        """Initialize database schema"""
+        """
+        Initialize database schema using Alembic migrations.
+
+        This method handles three scenarios:
+        1. New database: Run migrations from scratch
+        2. Pre-Alembic database: Stamp with initial revision (no changes)
+        3. Alembic-managed database: Upgrade to latest version
+        """
         if self._initialized:
             return
 
@@ -125,137 +132,59 @@ class RefreshTokenStorage:
         db_dir = Path(self.db_path).parent
         db_dir.mkdir(parents=True, exist_ok=True)
 
-        # Set restrictive permissions on database file
+        # Set restrictive permissions on database file if it exists
         if Path(self.db_path).exists():
             os.chmod(self.db_path, 0o600)
 
+        # Check database state and run appropriate migration strategy
         async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS refresh_tokens (
-                    user_id TEXT PRIMARY KEY,
-                    encrypted_token BLOB NOT NULL,
-                    expires_at INTEGER,
-                    created_at INTEGER NOT NULL,
-                    updated_at INTEGER NOT NULL,
-                    -- ADR-004 Progressive Consent fields
-                    flow_type TEXT DEFAULT 'hybrid',  -- 'hybrid', 'flow1', 'flow2'
-                    token_audience TEXT DEFAULT 'nextcloud',  -- 'mcp-server' or 'nextcloud'
-                    provisioned_at INTEGER,  -- When Flow 2 was completed
-                    provisioning_client_id TEXT,  -- Which MCP client initiated Flow 1
-                    scopes TEXT,  -- JSON array of granted scopes
-                    -- Browser session profile cache
-                    user_profile TEXT,  -- JSON cache of IdP user profile (for browser UI only)
-                    profile_cached_at INTEGER  -- When profile was last cached
+            # Check if database is managed by Alembic
+            cursor = await db.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='alembic_version'"
+            )
+            has_alembic = await cursor.fetchone() is not None
+
+            if not has_alembic:
+                # Check if this is a pre-Alembic database with existing schema
+                cursor = await db.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table' AND name='refresh_tokens'"
                 )
-                """
-            )
+                has_schema = await cursor.fetchone() is not None
 
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS audit_logs (
-                    id INTEGER PRIMARY KEY AUTOINCREMENT,
-                    timestamp INTEGER NOT NULL,
-                    event TEXT NOT NULL,
-                    user_id TEXT NOT NULL,
-                    resource_type TEXT,
-                    resource_id TEXT,
-                    auth_method TEXT,
-                    hostname TEXT
+                if has_schema:
+                    logger.info(
+                        f"Detected pre-Alembic database at {self.db_path}, "
+                        "stamping with initial revision"
+                    )
+                else:
+                    logger.info(
+                        f"Initializing new database at {self.db_path} with migrations"
+                    )
+
+        # Run migrations in a worker thread using anyio.to_thread
+        # This allows Alembic to run its own async operations in a separate context
+        from anyio import to_thread
+
+        from nextcloud_mcp_server.migrations import stamp_database, upgrade_database
+
+        if not has_alembic:
+            if has_schema:
+                # Stamp existing database without running migrations
+                await to_thread.run_sync(stamp_database, self.db_path, "001")
+                logger.info(
+                    "Pre-Alembic database stamped successfully. "
+                    "Future schema changes will use migrations."
                 )
-                """
-            )
+            else:
+                # New database - run migrations
+                await to_thread.run_sync(upgrade_database, self.db_path, "head")
+                logger.info("Database initialized with migrations")
+        else:
+            # Alembic-managed database - upgrade to latest
+            await to_thread.run_sync(upgrade_database, self.db_path, "head")
+            logger.info("Database upgraded to latest version")
 
-            # Create index on audit logs for efficient queries
-            await db.execute(
-                "CREATE INDEX IF NOT EXISTS idx_audit_user_timestamp "
-                "ON audit_logs(user_id, timestamp)"
-            )
-
-            # OAuth client credentials storage
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS oauth_clients (
-                    id INTEGER PRIMARY KEY,
-                    client_id TEXT UNIQUE NOT NULL,
-                    encrypted_client_secret BLOB NOT NULL,
-                    client_id_issued_at INTEGER NOT NULL,
-                    client_secret_expires_at INTEGER NOT NULL,
-                    redirect_uris TEXT NOT NULL,
-                    encrypted_registration_access_token BLOB,
-                    registration_client_uri TEXT,
-                    created_at INTEGER NOT NULL,
-                    updated_at INTEGER NOT NULL
-                )
-                """
-            )
-
-            # OAuth flow sessions (ADR-004 Progressive Consent)
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS oauth_sessions (
-                    session_id TEXT PRIMARY KEY,
-                    client_id TEXT,
-                    client_redirect_uri TEXT NOT NULL,
-                    state TEXT,
-                    code_challenge TEXT,
-                    code_challenge_method TEXT,
-                    mcp_authorization_code TEXT UNIQUE,
-                    idp_access_token TEXT,
-                    idp_refresh_token TEXT,
-                    user_id TEXT,
-                    created_at INTEGER NOT NULL,
-                    expires_at INTEGER NOT NULL,
-                    -- ADR-004 Progressive Consent fields
-                    flow_type TEXT DEFAULT 'hybrid',  -- 'hybrid', 'flow1', 'flow2'
-                    requested_scopes TEXT,  -- JSON array of requested scopes
-                    granted_scopes TEXT,  -- JSON array of granted scopes
-                    is_provisioning BOOLEAN DEFAULT FALSE  -- True if this is a Flow 2 provisioning session
-                )
-                """
-            )
-
-            # Create index for MCP authorization code lookups
-            await db.execute(
-                "CREATE INDEX IF NOT EXISTS idx_oauth_sessions_mcp_code "
-                "ON oauth_sessions(mcp_authorization_code)"
-            )
-
-            # Schema version tracking
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS schema_version (
-                    version INTEGER PRIMARY KEY,
-                    applied_at REAL NOT NULL
-                )
-                """
-            )
-
-            # Registered webhooks tracking (both BasicAuth and OAuth modes)
-            await db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS registered_webhooks (
-                    id INTEGER PRIMARY KEY AUTOINCREMENT,
-                    webhook_id INTEGER NOT NULL UNIQUE,
-                    preset_id TEXT NOT NULL,
-                    created_at REAL NOT NULL
-                )
-                """
-            )
-
-            # Create indexes for efficient webhook queries
-            await db.execute(
-                "CREATE INDEX IF NOT EXISTS idx_webhooks_preset "
-                "ON registered_webhooks(preset_id)"
-            )
-            await db.execute(
-                "CREATE INDEX IF NOT EXISTS idx_webhooks_created "
-                "ON registered_webhooks(created_at)"
-            )
-
-            await db.commit()
-
-        # Set restrictive permissions after creation
+        # Set restrictive permissions after initialization
         os.chmod(self.db_path, 0o600)
 
         self._initialized = True
@@ -287,6 +216,8 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
         encrypted_token = self.cipher.encrypt(refresh_token.encode())
         now = int(time.time())
         scopes_json = json.dumps(scopes) if scopes else None
@@ -432,6 +363,9 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
+
         start_time = time.time()
         try:
             async with aiosqlite.connect(self.db_path) as db:
@@ -516,6 +450,9 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
+
         async with aiosqlite.connect(self.db_path) as db:
             async with db.execute(
                 """
@@ -687,6 +624,9 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
+
         # Encrypt sensitive data
         encrypted_secret = self.cipher.encrypt(client_secret.encode())
         encrypted_reg_token = (
@@ -757,6 +697,9 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
+        # Type narrowing: cipher is set after initialize()
+        assert self.cipher is not None
+
         async with aiosqlite.connect(self.db_path) as db:
             async with db.execute(
                 """

nextcloud_mcp_server/auth/templates/vector_viz.html

@@ -65,8 +65,12 @@
                                     <span>Contacts</span>
                                 </label>
                                 <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="deck" style="margin-right: 4px;">
-                                    <span>Deck</span>
+                                    <input type="checkbox" x-model="docTypes" value="deck_card" style="margin-right: 4px;">
+                                    <span>Deck Cards</span>
+                                </label>
+                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
+                                    <input type="checkbox" x-model="docTypes" value="news_item" style="margin-right: 4px;">
+                                    <span>News</span>
                                 </label>
                             </div>
                         </div>

nextcloud_mcp_server/auth/token_broker.py

@@ -21,7 +21,6 @@ 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
@@ -104,7 +103,8 @@ class TokenBrokerService:
         storage: RefreshTokenStorage,
         oidc_discovery_url: str,
         nextcloud_host: str,
-        encryption_key: str,
+        client_id: str,
+        client_secret: str,
         cache_ttl: int = 300,
         cache_early_refresh: int = 30,
     ):
@@ -112,23 +112,25 @@ class TokenBrokerService:
         Initialize the Token Broker Service.
 
         Args:
-            storage: Database storage for refresh tokens
+            storage: Database storage for refresh tokens (handles encryption internally)
             oidc_discovery_url: OIDC provider discovery URL
             nextcloud_host: Nextcloud server URL
-            encryption_key: Fernet key for token encryption
+            client_id: OAuth client ID for token operations
+            client_secret: OAuth client secret for token operations
             cache_ttl: Cache TTL in seconds (default: 5 minutes)
             cache_early_refresh: Early refresh threshold in seconds (default: 30 seconds)
         """
         self.storage = storage
         self.oidc_discovery_url = oidc_discovery_url
         self.nextcloud_host = nextcloud_host
-        self.fernet = Fernet(
-            encryption_key.encode()
-            if isinstance(encryption_key, str)
-            else encryption_key
-        )
+        self.client_id = client_id
+        self.client_secret = client_secret
         self.cache = TokenCache(cache_ttl, cache_early_refresh)
         self._oidc_config = None
+
+        # Per-user locks for token refresh operations (prevents race conditions)
+        self._user_refresh_locks: dict[str, anyio.Lock] = {}
+        self._locks_lock = anyio.Lock()  # Protects the locks dict itself
         self._http_client = None
 
     async def _get_http_client(self) -> httpx.AsyncClient:
@@ -139,6 +141,24 @@ 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:
@@ -148,6 +168,37 @@ class TokenBrokerService:
             self._oidc_config = response.json()
         return self._oidc_config
 
+    def _rewrite_token_endpoint(self, token_endpoint: str) -> str:
+        """Rewrite token endpoint from public URL to internal Docker URL.
+
+        OIDC discovery documents return public URLs (e.g., http://localhost:8080/...)
+        but server-side requests must use internal Docker network (e.g., http://app:80/...).
+
+        Args:
+            token_endpoint: Token endpoint URL from discovery document
+
+        Returns:
+            Rewritten URL using internal Docker host
+        """
+        import os
+        from urllib.parse import urlparse
+
+        public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+        if not public_issuer:
+            return token_endpoint
+
+        internal_parsed = urlparse(self.nextcloud_host)
+        token_parsed = urlparse(token_endpoint)
+        public_parsed = urlparse(public_issuer)
+
+        if token_parsed.hostname == public_parsed.hostname:
+            # Replace public URL with internal Docker URL
+            rewritten = f"{internal_parsed.scheme}://{internal_parsed.netloc}{token_parsed.path}"
+            logger.info(f"Rewrote token endpoint: {token_endpoint} -> {rewritten}")
+            return rewritten
+
+        return token_endpoint
+
     async def get_nextcloud_token(self, user_id: str) -> Optional[str]:
         """
         Get a valid Nextcloud access token for the user.
@@ -180,9 +231,8 @@ class TokenBrokerService:
             return None
 
         try:
-            # Decrypt refresh token
-            encrypted_token = refresh_data["refresh_token"]
-            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()
+            # storage.get_refresh_token() returns already-decrypted token
+            refresh_token = refresh_data["refresh_token"]
 
             # Exchange refresh token for new access token
             access_token, expires_in = await self._refresh_access_token(refresh_token)
@@ -271,41 +321,79 @@ class TokenBrokerService:
         """
         # Check cache first (background tokens can be cached)
         cache_key = f"{user_id}:background:{','.join(sorted(required_scopes))}"
+        refresh_in_progress_key = f"{user_id}:refresh_in_progress"
+
         cached_token = await self.cache.get(cache_key)
         if cached_token:
             return cached_token
 
-        # Get stored refresh token
-        refresh_data = await self.storage.get_refresh_token(user_id)
-        if not refresh_data:
-            logger.info(f"No refresh token found for user {user_id}")
-            return None
+        # Acquire per-user lock BEFORE refresh operation to prevent race conditions
+        refresh_lock = await self._get_user_refresh_lock(user_id)
+        async with refresh_lock:
+            # Double-check cache after acquiring lock
+            # (another thread may have refreshed while we waited)
+            cached_token = await self.cache.get(cache_key)
+            if cached_token:
+                logger.debug(
+                    f"Token found in cache after lock acquisition for user {user_id}"
+                )
+                return cached_token
 
-        try:
-            # Decrypt refresh token
-            encrypted_token = refresh_data["refresh_token"]
-            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()
+            # Check if another thread is currently refreshing
+            if await self.cache.get(refresh_in_progress_key):
+                logger.debug(f"Refresh in progress for user {user_id}, waiting briefly")
+                await anyio.sleep(0.1)  # Brief wait for in-progress refresh
+                # Check cache one more time after wait
+                cached_token = await self.cache.get(cache_key)
+                if cached_token:
+                    logger.debug(
+                        f"Token refreshed by another thread for user {user_id}"
+                    )
+                    return cached_token
 
-            # Get token with specific scopes for background operation
-            access_token, expires_in = await self._refresh_access_token_with_scopes(
-                refresh_token, required_scopes
-            )
+            # Mark refresh as in-progress
+            await self.cache.set(refresh_in_progress_key, "true", expires_in=5)
 
-            # Cache the background token
-            await self.cache.set(cache_key, access_token, expires_in)
+            try:
+                # Get stored refresh token
+                refresh_data = await self.storage.get_refresh_token(user_id)
+                if not refresh_data:
+                    logger.info(f"No refresh token found for user {user_id}")
+                    return None
 
-            logger.info(
-                f"Generated background token for user {user_id} with scopes: {required_scopes}"
-            )
+                # storage.get_refresh_token() returns already-decrypted token
+                refresh_token = refresh_data["refresh_token"]
 
-            return access_token
+                # Get token with specific scopes for background operation
+                # Pass user_id to enable refresh token rotation storage
+                access_token, expires_in = await self._refresh_access_token_with_scopes(
+                    refresh_token, required_scopes, user_id=user_id
+                )
 
-        except Exception as e:
-            logger.error(f"Failed to get background token for user {user_id}: {e}")
-            await self.cache.invalidate(cache_key)
-            return None
+                # Cache the background token
+                await self.cache.set(cache_key, access_token, expires_in)
 
-    async def _refresh_access_token(self, refresh_token: str) -> Tuple[str, int]:
+                logger.info(
+                    f"Generated background token for user {user_id} with scopes: {required_scopes}"
+                )
+
+                return access_token
+
+            except Exception as e:
+                logger.error(
+                    f"Failed to get background token for user {user_id}: {e}",
+                    exc_info=True,
+                )
+                await self.cache.invalidate(cache_key)
+                return None
+
+            finally:
+                # Always clear the in-progress marker
+                await self.cache.invalidate(refresh_in_progress_key)
+
+    async def _refresh_access_token(
+        self, refresh_token: str, user_id: str | None = None
+    ) -> Tuple[str, int]:
         """
         Exchange refresh token for new access token.
 
@@ -313,20 +401,24 @@ 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)
         """
         config = await self._get_oidc_config()
-        token_endpoint = config["token_endpoint"]
+        token_endpoint = self._rewrite_token_endpoint(config["token_endpoint"])
 
         client = await self._get_http_client()
 
         # Request new access token using refresh token
+        # Include client credentials as required by most OAuth servers
         data = {
             "grant_type": "refresh_token",
             "refresh_token": refresh_token,
-            "scope": "openid profile email notes:read notes:write calendar:read calendar:write",
+            "scope": "openid profile email offline_access notes:read notes:write calendar:read calendar:write",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
         }
 
         response = await client.post(
@@ -345,42 +437,69 @@ class TokenBrokerService:
         access_token = token_data["access_token"]
         expires_in = token_data.get("expires_in", 3600)  # Default 1 hour
 
-        # Validate audience
-        await self._validate_token_audience(access_token, "nextcloud")
+        # Handle refresh token rotation (Nextcloud OIDC rotates on every use)
+        new_refresh_token = token_data.get("refresh_token")
+        if user_id and new_refresh_token and new_refresh_token != refresh_token:
+            # Calculate expiry as Unix timestamp (90 days from now)
+            expires_at = int(
+                (datetime.now(timezone.utc) + timedelta(days=90)).timestamp()
+            )
+            await self.storage.store_refresh_token(
+                user_id=user_id,
+                refresh_token=new_refresh_token,
+                expires_at=expires_at,
+            )
+            logger.info(f"Stored rotated refresh token for user {user_id}")
+
+        # Note: Nextcloud validates token audience on API calls - no need to pre-validate here
 
         logger.info(f"Refreshed access token (expires in {expires_in}s)")
         return access_token, expires_in
 
     async def _refresh_access_token_with_scopes(
-        self, refresh_token: str, required_scopes: list[str]
+        self, refresh_token: str, required_scopes: list[str], user_id: str | None = None
     ) -> Tuple[str, int]:
         """
         Exchange refresh token for new access token with specific scopes.
 
         This method implements scope downscoping for least privilege.
 
+        IMPORTANT: Nextcloud OIDC rotates refresh tokens on every use (one-time use).
+        When user_id is provided, this method stores the new refresh token returned
+        by Nextcloud to ensure subsequent refresh operations succeed.
+
         Args:
             refresh_token: The refresh token
             required_scopes: Minimal scopes needed for this operation
+            user_id: If provided, store the rotated refresh token for this user
 
         Returns:
             Tuple of (access_token, expires_in_seconds)
         """
         config = await self._get_oidc_config()
-        token_endpoint = config["token_endpoint"]
+        token_endpoint = self._rewrite_token_endpoint(config["token_endpoint"])
 
         client = await self._get_http_client()
 
-        # Always include basic OpenID scopes
-        scopes = list(set(["openid", "profile", "email"] + required_scopes))
+        # Always include basic OpenID scopes + offline_access to get new refresh token
+        scopes = list(
+            set(["openid", "profile", "email", "offline_access"] + required_scopes)
+        )
 
         # Request new access token with specific scopes
+        # Include client credentials as required by most OAuth servers
         data = {
             "grant_type": "refresh_token",
             "refresh_token": refresh_token,
             "scope": " ".join(scopes),
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
         }
 
+        logger.info(
+            f"Token refresh request to {token_endpoint} with client_id={self.client_id[:16]}..."
+        )
+
         response = await client.post(
             token_endpoint,
             data=data,
@@ -391,14 +510,29 @@ class TokenBrokerService:
             logger.error(
                 f"Token refresh with scopes failed: {response.status_code} - {response.text}"
             )
+            logger.error(f"  client_id used: {self.client_id[:16]}...")
             raise Exception(f"Token refresh failed: {response.status_code}")
 
         token_data = response.json()
         access_token = token_data["access_token"]
         expires_in = token_data.get("expires_in", 3600)  # Default 1 hour
 
-        # Validate audience
-        await self._validate_token_audience(access_token, "nextcloud")
+        # Handle refresh token rotation (Nextcloud OIDC rotates on every use)
+        new_refresh_token = token_data.get("refresh_token")
+        if user_id and new_refresh_token and new_refresh_token != refresh_token:
+            # Store the new refresh token for future use
+            # Calculate expiry as Unix timestamp (90 days from now)
+            expires_at = int(
+                (datetime.now(timezone.utc) + timedelta(days=90)).timestamp()
+            )
+            await self.storage.store_refresh_token(
+                user_id=user_id,
+                refresh_token=new_refresh_token,
+                expires_at=expires_at,
+            )
+            logger.info(f"Stored rotated refresh token for user {user_id}")
+
+        # Note: Nextcloud validates token audience on API calls - no need to pre-validate here
 
         logger.info(
             f"Refreshed access token with scopes {scopes} (expires in {expires_in}s)"
@@ -453,11 +587,8 @@ class TokenBrokerService:
             return False
 
         try:
-            # Decrypt current refresh token
-            encrypted_token = refresh_data["refresh_token"]
-            current_refresh_token = self.fernet.decrypt(
-                encrypted_token.encode()
-            ).decode()
+            # storage.get_refresh_token() returns already-decrypted token
+            current_refresh_token = refresh_data["refresh_token"]
 
             # Get OIDC configuration
             config = await self._get_oidc_config()
@@ -486,13 +617,15 @@ class TokenBrokerService:
             new_refresh_token = token_data.get("refresh_token")
 
             if new_refresh_token and new_refresh_token != current_refresh_token:
-                # Encrypt and store new refresh token
-                encrypted_new = self.fernet.encrypt(new_refresh_token.encode()).decode()
+                # storage.store_refresh_token() handles encryption internally
+                # Convert datetime to Unix timestamp (int) for database storage
+                expires_at = int(
+                    (datetime.now(timezone.utc) + timedelta(days=90)).timestamp()
+                )
                 await self.storage.store_refresh_token(
                     user_id=user_id,
-                    refresh_token=encrypted_new,
-                    expires_at=datetime.now(timezone.utc)
-                    + timedelta(days=90),  # 90-day expiry
+                    refresh_token=new_refresh_token,
+                    expires_at=expires_at,
                 )
                 logger.info(f"Rotated master refresh token for user {user_id}")
 
@@ -536,11 +669,8 @@ class TokenBrokerService:
             refresh_data = await self.storage.get_refresh_token(user_id)
             if refresh_data:
                 try:
-                    # Attempt to revoke at IdP
-                    encrypted_token = refresh_data["refresh_token"]
-                    refresh_token = self.fernet.decrypt(
-                        encrypted_token.encode()
-                    ).decode()
+                    # storage.get_refresh_token() returns already-decrypted token
+                    refresh_token = refresh_data["refresh_token"]
                     await self._revoke_token_at_idp(refresh_token)
                 except Exception as e:
                     logger.warning(f"Failed to revoke at IdP: {e}")

nextcloud_mcp_server/auth/unified_verifier.py

@@ -303,10 +303,13 @@ class UnifiedTokenVerifier(TokenVerifier):
 
         try:
             # Introspection requires client authentication
+            client_id = self.settings.oidc_client_id
+            client_secret = self.settings.oidc_client_secret
+            assert client_id is not None and client_secret is not None
             response = await self.http_client.post(
                 self.introspection_uri,
                 data={"token": token},
-                auth=(self.settings.oidc_client_id, self.settings.oidc_client_secret),
+                auth=(client_id, client_secret),
             )
 
             if response.status_code == 200:

nextcloud_mcp_server/auth/viz_routes.py

@@ -22,6 +22,7 @@ from starlette.requests import Request
 from starlette.responses import HTMLResponse, JSONResponse
 
 from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.observability.tracing import trace_operation
 from nextcloud_mcp_server.search import (
     BM25HybridSearchAlgorithm,
     SemanticSearchAlgorithm,
@@ -139,7 +140,10 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             _get_authenticated_client_for_userinfo,
         )
 
-        async with await _get_authenticated_client_for_userinfo(request) as nc_client:  # noqa: F841
+        with trace_operation("vector_viz.get_auth_client"):
+            auth_client_ctx = await _get_authenticated_client_for_userinfo(request)
+
+        async with auth_client_ctx as nc_client:  # noqa: F841
             # Create search algorithm (no client needed - verification removed)
             if algorithm == "semantic":
                 search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
@@ -159,24 +163,40 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
             all_results = []
             if doc_types is None or len(doc_types) == 0:
                 # Cross-app search - search all indexed types
-                unverified_results = await search_algo.search(
-                    query=query,
-                    user_id=username,
-                    limit=limit * 2,  # Buffer for verification filtering
-                    doc_type=None,  # Search all types
-                    score_threshold=score_threshold,
-                )
-                all_results.extend(unverified_results)
-            else:
-                # Search each document type and combine
-                for doc_type in doc_types:
+                with trace_operation(
+                    "vector_viz.search_execute",
+                    attributes={
+                        "search.algorithm": algorithm,
+                        "search.limit": limit * 2,
+                        "search.doc_type": "all",
+                    },
+                ):
                     unverified_results = await search_algo.search(
                         query=query,
                         user_id=username,
                         limit=limit * 2,  # Buffer for verification filtering
-                        doc_type=doc_type,
+                        doc_type=None,  # Search all types
                         score_threshold=score_threshold,
                     )
+                all_results.extend(unverified_results)
+            else:
+                # Search each document type and combine
+                for doc_type in doc_types:
+                    with trace_operation(
+                        "vector_viz.search_execute",
+                        attributes={
+                            "search.algorithm": algorithm,
+                            "search.limit": limit * 2,
+                            "search.doc_type": doc_type,
+                        },
+                    ):
+                        unverified_results = await search_algo.search(
+                            query=query,
+                            user_id=username,
+                            limit=limit * 2,  # Buffer for verification filtering
+                            doc_type=doc_type,
+                            score_threshold=score_threshold,
+                        )
                     all_results.extend(unverified_results)
                 # Sort by score before verification
                 all_results.sort(key=lambda r: r.score, reverse=True)
@@ -190,22 +210,26 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
         # Store original scores and normalize for visualization
         # (best result = 1.0, worst result = 0.0 within THIS result set)
         # This makes visual encoding meaningful regardless of RRF normalization
-        if search_results:
-            scores = [r.score for r in search_results]
-            min_score, max_score = min(scores), max(scores)
-            score_range = max_score - min_score if max_score > min_score else 1.0
+        with trace_operation(
+            "vector_viz.score_normalize",
+            attributes={"normalize.num_results": len(search_results)},
+        ):
+            if search_results:
+                scores = [r.score for r in search_results]
+                min_score, max_score = min(scores), max(scores)
+                score_range = max_score - min_score if max_score > min_score else 1.0
 
-            logger.info(
-                f"Normalizing scores for viz: original range [{min_score:.3f}, {max_score:.3f}] "
-                f"→ [0.0, 1.0]"
-            )
+                logger.info(
+                    f"Normalizing scores for viz: original range [{min_score:.3f}, {max_score:.3f}] "
+                    f"→ [0.0, 1.0]"
+                )
 
-            # Store original score and rescale to 0-1 for visualization
-            for r in search_results:
-                # Store original score before normalization
-                r.original_score = r.score
-                # Rescale for visual encoding
-                r.score = (r.score - min_score) / score_range
+                # Store original score and rescale to 0-1 for visualization
+                for r in search_results:
+                    # Store original score before normalization
+                    r.original_score = r.score
+                    # Rescale for visual encoding
+                    r.score = (r.score - min_score) / score_range
 
         if not search_results:
             return JSONResponse(
@@ -220,7 +244,9 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
 
         # Fetch vectors for specific matching chunks from Qdrant using batch retrieve
         vector_fetch_start = time.perf_counter()
-        qdrant_client = await get_qdrant_client()
+
+        with trace_operation("vector_viz.get_qdrant_client"):
+            qdrant_client = await get_qdrant_client()
 
         chunk_vectors_map = {}  # Map (doc_id, chunk_start, chunk_end) -> vector
 
@@ -231,12 +257,16 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
         if point_ids:
             # Single batch retrieve call instead of N sequential scroll calls
             # This is ~50x faster for 50 results (1 HTTP request vs 50)
-            points_response = await qdrant_client.retrieve(
-                collection_name=settings.get_collection_name(),
-                ids=point_ids,
-                with_vectors=["dense"],
-                with_payload=["doc_id", "chunk_start_offset", "chunk_end_offset"],
-            )
+            with trace_operation(
+                "vector_viz.vector_retrieve",
+                attributes={"retrieve.num_points": len(point_ids)},
+            ):
+                points_response = await qdrant_client.retrieve(
+                    collection_name=settings.get_collection_name(),
+                    ids=point_ids,
+                    with_vectors=["dense"],
+                    with_payload=["doc_id", "chunk_start_offset", "chunk_end_offset"],
+                )
 
             # Build chunk_vectors_map from batch response
             for point in points_response:
@@ -268,6 +298,7 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
                             "title": r.title,
                             "excerpt": r.excerpt,
                             "score": r.score,
+                            "metadata": r.metadata,
                         }
                         for r in search_results
                     ],
@@ -367,9 +398,16 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
 
         import anyio
 
-        coords_3d, pca = await anyio.to_thread.run_sync(  # type: ignore[attr-defined]
-            lambda: _compute_pca(all_vectors_normalized)
-        )
+        with trace_operation(
+            "vector_viz.pca_compute",
+            attributes={
+                "pca.num_vectors": len(all_vectors_normalized),
+                "pca.embedding_dim": embedding_dim,
+            },
+        ):
+            coords_3d, pca = await anyio.to_thread.run_sync(  # type: ignore[attr-defined]
+                lambda: _compute_pca(all_vectors_normalized)
+            )
         pca_duration = time.perf_counter() - pca_start
 
         # After fit, these attributes are guaranteed to be set
@@ -421,6 +459,7 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
                 ),  # Raw score from algorithm
                 "chunk_start_offset": r.chunk_start_offset,
                 "chunk_end_offset": r.chunk_end_offset,
+                "metadata": r.metadata,  # Include metadata (e.g., board_id for deck_card)
             }
             for r in search_results
         ]

nextcloud_mcp_server/auth/webhook_routes.py

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

nextcloud_mcp_server/client/__init__.py

@@ -18,6 +18,7 @@ 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
@@ -81,6 +82,7 @@ class NextcloudClient:
         self.contacts = ContactsClient(self._client, username)
         self.cookbook = CookbookClient(self._client, username)
         self.deck = DeckClient(self._client, username)
+        self.news = NewsClient(self._client, username)
         self.users = UsersClient(self._client, username)
         self.groups = GroupsClient(self._client, username)
         self.sharing = SharingClient(self._client, username)

nextcloud_mcp_server/client/news.py

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

nextcloud_mcp_server/client/webdav.py

@@ -1174,13 +1174,17 @@ class WebDAVClient(BaseNextcloudClient):
 
             if display_name_elem is not None and display_name_elem.text == tag_name:
                 tag_info = {
-                    "id": int(tag_id_elem.text) if tag_id_elem is not None else None,
+                    "id": int(tag_id_elem.text)
+                    if tag_id_elem is not None and tag_id_elem.text is not None
+                    else None,
                     "name": display_name_elem.text,
                     "userVisible": user_visible_elem.text.lower() == "true"
                     if user_visible_elem is not None
+                    and user_visible_elem.text is not None
                     else True,
                     "userAssignable": user_assignable_elem.text.lower() == "true"
                     if user_assignable_elem is not None
+                    and user_assignable_elem.text is not None
                     else True,
                 }
                 logger.debug(f"Found tag '{tag_name}' with ID {tag_info['id']}")
@@ -1369,7 +1373,9 @@ class WebDAVClient(BaseNextcloudClient):
         )
 
         file_info = {
-            "id": int(fileid_elem.text) if fileid_elem is not None else None,
+            "id": int(fileid_elem.text)
+            if fileid_elem is not None and fileid_elem.text is not None
+            else None,
             "path": path,
             "name": displayname_elem.text
             if displayname_elem is not None
@@ -1398,7 +1404,7 @@ class WebDAVClient(BaseNextcloudClient):
         user_visible: bool = True,
         user_assignable: bool = True,
     ) -> dict[str, Any]:
-        """Create a system tag via OCS API.
+        """Create a system tag via WebDAV.
 
         Args:
             name: Name of the tag to create
@@ -1411,12 +1417,10 @@ class WebDAVClient(BaseNextcloudClient):
         Raises:
             HTTPStatusError: If tag creation fails (409 if already exists)
         """
+        # Use WebDAV POST with JSON body to create tag
         response = await self._client.post(
-            "/ocs/v2.php/apps/systemtags/api/v1/tags",
-            headers={
-                "OCS-APIRequest": "true",
-                "Content-Type": "application/json",
-            },
+            "/remote.php/dav/systemtags/",
+            headers={"Content-Type": "application/json"},
             json={
                 "name": name,
                 "userVisible": user_visible,
@@ -1425,15 +1429,21 @@ class WebDAVClient(BaseNextcloudClient):
         )
         response.raise_for_status()
 
-        # Parse OCS response
-        data = response.json()
-        ocs_data = data.get("ocs", {}).get("data", {})
+        # Extract tag ID from Content-Location header (e.g., /remote.php/dav/systemtags/42)
+        content_location = response.headers.get("Content-Location", "")
+        tag_id = None
+        if content_location:
+            # Extract the numeric ID from the path
+            try:
+                tag_id = int(content_location.rstrip("/").split("/")[-1])
+            except (ValueError, IndexError):
+                pass
 
         tag_info = {
-            "id": ocs_data.get("id"),
-            "name": ocs_data.get("name", name),
-            "userVisible": ocs_data.get("userVisible", user_visible),
-            "userAssignable": ocs_data.get("userAssignable", user_assignable),
+            "id": tag_id,
+            "name": name,
+            "userVisible": user_visible,
+            "userAssignable": user_assignable,
         }
 
         logger.info(f"Created tag '{name}' with ID {tag_info['id']}")

nextcloud_mcp_server/config.py

@@ -205,6 +205,7 @@ class Settings:
     vector_sync_scan_interval: int = 300  # seconds (5 minutes)
     vector_sync_processor_workers: int = 3
     vector_sync_queue_max_size: int = 10000
+    vector_sync_user_poll_interval: int = 60  # seconds - OAuth mode user discovery
 
     # Qdrant settings (mutually exclusive modes)
     qdrant_url: Optional[str] = None  # Network mode: http://qdrant:6333
@@ -391,6 +392,9 @@ def get_settings() -> Settings:
         vector_sync_queue_max_size=int(
             os.getenv("VECTOR_SYNC_QUEUE_MAX_SIZE", "10000")
         ),
+        vector_sync_user_poll_interval=int(
+            os.getenv("VECTOR_SYNC_USER_POLL_INTERVAL", "60")
+        ),
         # Qdrant settings
         qdrant_url=os.getenv("QDRANT_URL"),
         qdrant_location=os.getenv("QDRANT_LOCATION"),

nextcloud_mcp_server/migrations.py

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

nextcloud_mcp_server/models/news.py

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

nextcloud_mcp_server/models/semantic.py

@@ -38,6 +38,9 @@ class SemanticSearchResult(BaseModel):
     page_number: Optional[int] = Field(
         default=None, description="Page number for PDF documents"
     )
+    page_count: Optional[int] = Field(
+        default=None, description="Total number of pages in PDF document"
+    )
     # Context expansion fields (optional, populated when include_context=True)
     has_context_expansion: bool = Field(
         default=False, description="Whether context expansion was performed"

nextcloud_mcp_server/observability/logging_config.py

@@ -60,7 +60,7 @@ class TraceContextFormatter(JsonFormatter):
 
     def add_fields(
         self,
-        log_record: dict[str, Any],
+        log_data: dict[str, Any],
         record: logging.LogRecord,
         message_dict: dict[str, Any],
     ) -> None:
@@ -68,28 +68,28 @@ class TraceContextFormatter(JsonFormatter):
         Add custom fields to the log record, including trace context.
 
         Args:
-            log_record: Dictionary to be serialized as JSON
+            log_data: Dictionary to be serialized as JSON
             record: LogRecord instance
             message_dict: Dictionary of extra fields from log call
         """
         # Call parent to add standard fields
-        super().add_fields(log_record, record, message_dict)
+        super().add_fields(log_data, record, message_dict)
 
         # Add trace context if available
         trace_context = get_trace_context()
         if trace_context:
-            log_record["trace_id"] = trace_context.get("trace_id")
-            log_record["span_id"] = trace_context.get("span_id")
+            log_data["trace_id"] = trace_context.get("trace_id")
+            log_data["span_id"] = trace_context.get("span_id")
 
         # Add standard fields with consistent naming
-        log_record["timestamp"] = self.formatTime(record)
-        log_record["level"] = record.levelname
-        log_record["logger"] = record.name
-        log_record["message"] = record.getMessage()
+        log_data["timestamp"] = self.formatTime(record)
+        log_data["level"] = record.levelname
+        log_data["logger"] = record.name
+        log_data["message"] = record.getMessage()
 
         # Include exception info if present
         if record.exc_info:
-            log_record["exception"] = self.formatException(record.exc_info)
+            log_data["exception"] = self.formatException(record.exc_info)
 
 
 class TraceContextTextFormatter(logging.Formatter):

nextcloud_mcp_server/observability/tracing.py

@@ -53,10 +53,11 @@ def setup_tracing(
     global _tracer
 
     # Create resource with service name
+    pkg_name = __package__.split(".")[0] if __package__ else "nextcloud_mcp_server"
     resource = Resource.create(
         {
             "service.name": service_name,
-            "service.version": version(__package__.split(".")[0]),
+            "service.version": version(pkg_name),
         }
     )
 

nextcloud_mcp_server/providers/anthropic.py

@@ -17,18 +17,20 @@ class AnthropicProvider(Provider):
     Note: Anthropic doesn't provide embedding models, only text generation.
     """
 
-    def __init__(self, api_key: str, model: str = "claude-3-5-sonnet-20241022"):
+    def __init__(
+        self, api_key: str, generation_model: str = "claude-3-5-sonnet-20241022"
+    ):
         """
         Initialize Anthropic provider.
 
         Args:
             api_key: Anthropic API key
-            model: Model name (e.g., "claude-3-5-sonnet-20241022")
+            generation_model: Model name (e.g., "claude-3-5-sonnet-20241022")
         """
         self.client = AsyncAnthropic(api_key=api_key)
-        self.model = model
+        self.model = generation_model
 
-        logger.info(f"Initialized Anthropic provider (model={model})")
+        logger.info(f"Initialized Anthropic provider (model={self.model})")
 
     @property
     def supports_embeddings(self) -> bool:

nextcloud_mcp_server/providers/openai.py

@@ -7,13 +7,48 @@ Supports:
 """
 
 import logging
+from functools import wraps
 
-from openai import AsyncOpenAI
+import anyio
+from openai import AsyncOpenAI, RateLimitError
 
 from .base import Provider
 
 logger = logging.getLogger(__name__)
 
+# Rate limit retry configuration
+MAX_RETRIES = 5
+INITIAL_RETRY_DELAY = 2.0  # seconds
+MAX_RETRY_DELAY = 60.0  # seconds
+
+
+def retry_on_rate_limit(func):
+    """Decorator to retry on OpenAI rate limit errors with exponential backoff."""
+
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        retry_delay = INITIAL_RETRY_DELAY
+        last_error: Exception | None = None
+
+        for attempt in range(1, MAX_RETRIES + 1):
+            try:
+                return await func(*args, **kwargs)
+            except RateLimitError as e:
+                last_error = e
+                if attempt < MAX_RETRIES:
+                    logger.warning(
+                        f"Rate limit hit (attempt {attempt}/{MAX_RETRIES}), "
+                        f"retrying in {retry_delay:.1f}s..."
+                    )
+                    await anyio.sleep(retry_delay)
+                    retry_delay = min(retry_delay * 2, MAX_RETRY_DELAY)
+
+        logger.error(f"Rate limit exceeded after {MAX_RETRIES} attempts")
+        raise last_error  # type: ignore[misc]
+
+    return wrapper
+
+
 # Well-known embedding dimensions for OpenAI models
 OPENAI_EMBEDDING_DIMENSIONS: dict[str, int] = {
     "text-embedding-3-small": 1536,
@@ -86,6 +121,7 @@ class OpenAIProvider(Provider):
         """Whether this provider supports text generation."""
         return self.generation_model is not None
 
+    @retry_on_rate_limit
     async def embed(self, text: str) -> list[float]:
         """
         Generate embedding vector for text.
@@ -104,6 +140,7 @@ class OpenAIProvider(Provider):
                 "Embedding not supported - no embedding_model configured"
             )
 
+        assert self.embedding_model is not None  # Type narrowing
         response = await self.client.embeddings.create(
             input=text,
             model=self.embedding_model,
@@ -151,14 +188,8 @@ class OpenAIProvider(Provider):
         for i in range(0, len(texts), batch_size):
             batch = texts[i : i + batch_size]
 
-            response = await self.client.embeddings.create(
-                input=batch,
-                model=self.embedding_model,
-            )
-
-            # Sort by index to maintain order
-            sorted_data = sorted(response.data, key=lambda x: x.index)
-            batch_embeddings = [item.embedding for item in sorted_data]
+            # Use helper method with retry logic for each batch
+            batch_embeddings = await self._embed_batch_request(batch)
             all_embeddings.extend(batch_embeddings)
 
             # Update dimension if not set
@@ -171,6 +202,18 @@ class OpenAIProvider(Provider):
 
         return all_embeddings
 
+    @retry_on_rate_limit
+    async def _embed_batch_request(self, batch: list[str]) -> list[list[float]]:
+        """Make a single batch embedding request with retry logic."""
+        assert self.embedding_model is not None  # Type narrowing
+        response = await self.client.embeddings.create(
+            input=batch,
+            model=self.embedding_model,
+        )
+        # Sort by index to maintain order
+        sorted_data = sorted(response.data, key=lambda x: x.index)
+        return [item.embedding for item in sorted_data]
+
     def get_dimension(self) -> int:
         """
         Get embedding dimension.
@@ -194,6 +237,7 @@ class OpenAIProvider(Provider):
             )
         return self._dimension
 
+    @retry_on_rate_limit
     async def generate(self, prompt: str, max_tokens: int = 500) -> str:
         """
         Generate text from a prompt.

nextcloud_mcp_server/search/algorithms.py

@@ -108,10 +108,10 @@ async def get_indexed_doc_types(user_id: str) -> set[str]:
             with_vectors=False,  # Don't need vectors for type discovery
         )
 
-        doc_types = {
-            point.payload.get("doc_type")
+        doc_types: set[str] = {
+            str(point.payload.get("doc_type"))
             for point in scroll_results
-            if point.payload.get("doc_type")
+            if point.payload and point.payload.get("doc_type")
         }
 
         logger.debug(f"Found indexed document types for user {user_id}: {doc_types}")
@@ -138,6 +138,7 @@ class SearchResult:
         chunk_start_offset: Character position where chunk starts (None if not available)
         chunk_end_offset: Character position where chunk ends (None if not available)
         page_number: Page number for PDF documents (None for other doc types)
+        page_count: Total number of pages in PDF document (None for other doc types)
         chunk_index: Zero-based index of this chunk in the document
         total_chunks: Total number of chunks in the document
         point_id: Qdrant point ID for batch vector retrieval (None if not from Qdrant)
@@ -152,6 +153,7 @@ class SearchResult:
     chunk_start_offset: int | None = None
     chunk_end_offset: int | None = None
     page_number: int | None = None
+    page_count: int | None = None
     chunk_index: int = 0
     total_chunks: int = 1
     point_id: str | None = None

nextcloud_mcp_server/search/bm25_hybrid.py

@@ -9,6 +9,7 @@ from qdrant_client.models import FieldCondition, Filter, MatchValue
 from nextcloud_mcp_server.config import get_settings
 from nextcloud_mcp_server.embedding import get_bm25_service, get_embedding_service
 from nextcloud_mcp_server.observability.metrics import record_qdrant_operation
+from nextcloud_mcp_server.observability.tracing import trace_operation
 from nextcloud_mcp_server.search.algorithms import SearchAlgorithm, SearchResult
 from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
 from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
@@ -99,15 +100,19 @@ class BM25HybridSearchAlgorithm(SearchAlgorithm):
         )
 
         # Generate dense embedding for semantic search
-        embedding_service = get_embedding_service()
-        dense_embedding = await embedding_service.embed(query)
+        with trace_operation("search.get_embedding_service"):
+            embedding_service = get_embedding_service()
+        with trace_operation("search.dense_embedding"):
+            dense_embedding = await embedding_service.embed(query)
         # Store for reuse by callers (e.g., viz_routes PCA visualization)
         self.query_embedding = dense_embedding
         logger.debug(f"Generated dense embedding (dimension={len(dense_embedding)})")
 
         # Generate sparse embedding for BM25 keyword search
-        bm25_service = get_bm25_service()
-        sparse_embedding = await bm25_service.encode_async(query)
+        with trace_operation("search.get_bm25_service"):
+            bm25_service = get_bm25_service()
+        with trace_operation("search.sparse_embedding_bm25"):
+            sparse_embedding = await bm25_service.encode_async(query)
         logger.debug(
             f"Generated sparse embedding "
             f"({len(sparse_embedding['indices'])} non-zero terms)"
@@ -134,38 +139,44 @@ class BM25HybridSearchAlgorithm(SearchAlgorithm):
         query_filter = Filter(must=filter_conditions)
 
         # Execute hybrid search with Qdrant native RRF fusion
-        qdrant_client = await get_qdrant_client()
+        with trace_operation("search.get_qdrant_client"):
+            qdrant_client = await get_qdrant_client()
+
         try:
             # Use prefetch to run both dense and sparse searches
             # Qdrant will automatically merge results using RRF
-            search_response = await qdrant_client.query_points(
-                collection_name=settings.get_collection_name(),
-                prefetch=[
-                    # Dense semantic search
-                    models.Prefetch(
-                        query=dense_embedding,
-                        using="dense",
-                        limit=limit * 2,  # Get extra for deduplication
-                        filter=query_filter,
-                    ),
-                    # Sparse BM25 search
-                    models.Prefetch(
-                        query=models.SparseVector(
-                            indices=sparse_embedding["indices"],
-                            values=sparse_embedding["values"],
+            with trace_operation(
+                "search.qdrant_query",
+                attributes={"query.limit": limit * 2, "query.fusion": self.fusion_name},
+            ):
+                search_response = await qdrant_client.query_points(
+                    collection_name=settings.get_collection_name(),
+                    prefetch=[
+                        # Dense semantic search
+                        models.Prefetch(
+                            query=dense_embedding,
+                            using="dense",
+                            limit=limit * 2,  # Get extra for deduplication
+                            filter=query_filter,
                         ),
-                        using="sparse",
-                        limit=limit * 2,  # Get extra for deduplication
-                        filter=query_filter,
-                    ),
-                ],
-                # Fusion query (RRF or DBSF based on initialization)
-                query=models.FusionQuery(fusion=self.fusion),
-                limit=limit * 2,  # Get extra for deduplication
-                score_threshold=score_threshold,
-                with_payload=True,
-                with_vectors=False,  # Don't return vectors to save bandwidth
-            )
+                        # Sparse BM25 search
+                        models.Prefetch(
+                            query=models.SparseVector(
+                                indices=sparse_embedding["indices"],
+                                values=sparse_embedding["values"],
+                            ),
+                            using="sparse",
+                            limit=limit * 2,  # Get extra for deduplication
+                            filter=query_filter,
+                        ),
+                    ],
+                    # Fusion query (RRF or DBSF based on initialization)
+                    query=models.FusionQuery(fusion=self.fusion),
+                    limit=limit * 2,  # Get extra for deduplication
+                    score_threshold=score_threshold,
+                    with_payload=True,
+                    with_vectors=False,  # Don't return vectors to save bandwidth
+                )
             record_qdrant_operation("search", "success")
         except Exception:
             record_qdrant_operation("search", "error")
@@ -185,47 +196,66 @@ class BM25HybridSearchAlgorithm(SearchAlgorithm):
 
         # Deduplicate by (doc_id, doc_type, chunk_start, chunk_end)
         # This allows multiple chunks from same doc, but removes duplicate chunks
-        seen_chunks = set()
-        results = []
+        with trace_operation(
+            "search.deduplicate",
+            attributes={"dedupe.num_points": len(search_response.points)},
+        ):
+            seen_chunks = set()
+            results = []
 
-        for result in search_response.points:
-            # doc_id can be int (notes) or str (files - file paths)
-            doc_id = result.payload["doc_id"]
-            doc_type = result.payload.get("doc_type", "note")
-            chunk_start = result.payload.get("chunk_start_offset")
-            chunk_end = result.payload.get("chunk_end_offset")
-            chunk_key = (doc_id, doc_type, chunk_start, chunk_end)
+            for result in search_response.points:
+                if result.payload is None:
+                    continue
+                # doc_id can be int (notes) or str (files - file paths)
+                doc_id = result.payload["doc_id"]
+                doc_type = result.payload.get("doc_type", "note")
+                chunk_start = result.payload.get("chunk_start_offset")
+                chunk_end = result.payload.get("chunk_end_offset")
+                chunk_key = (doc_id, doc_type, chunk_start, chunk_end)
 
-            # Skip if we've already seen this exact chunk
-            if chunk_key in seen_chunks:
-                continue
+                # Skip if we've already seen this exact chunk
+                if chunk_key in seen_chunks:
+                    continue
 
-            seen_chunks.add(chunk_key)
+                seen_chunks.add(chunk_key)
 
-            # Return unverified results (verification happens at output stage)
-            results.append(
-                SearchResult(
-                    id=doc_id,
-                    doc_type=doc_type,
-                    title=result.payload.get("title", "Untitled"),
-                    excerpt=result.payload.get("excerpt", ""),
-                    score=result.score,  # Fusion score (RRF or DBSF)
-                    metadata={
-                        "chunk_index": result.payload.get("chunk_index"),
-                        "total_chunks": result.payload.get("total_chunks"),
-                        "search_method": f"bm25_hybrid_{self.fusion_name}",
-                    },
-                    chunk_start_offset=result.payload.get("chunk_start_offset"),
-                    chunk_end_offset=result.payload.get("chunk_end_offset"),
-                    page_number=result.payload.get("page_number"),
-                    chunk_index=result.payload.get("chunk_index", 0),
-                    total_chunks=result.payload.get("total_chunks", 1),
-                    point_id=str(result.id),  # Qdrant point ID for batch retrieval
+                # Build metadata dict with common fields
+                metadata = {
+                    "chunk_index": result.payload.get("chunk_index"),
+                    "total_chunks": result.payload.get("total_chunks"),
+                    "search_method": f"bm25_hybrid_{self.fusion_name}",
+                }
+
+                # Add file-specific metadata for PDF viewer
+                if doc_type == "file" and (path := result.payload.get("file_path")):
+                    metadata["path"] = path
+
+                # Add deck_card-specific metadata for frontend URL construction
+                if doc_type == "deck_card":
+                    if board_id := result.payload.get("board_id"):
+                        metadata["board_id"] = board_id
+
+                # Return unverified results (verification happens at output stage)
+                results.append(
+                    SearchResult(
+                        id=doc_id,
+                        doc_type=doc_type,
+                        title=result.payload.get("title", "Untitled"),
+                        excerpt=result.payload.get("excerpt", ""),
+                        score=result.score,  # Fusion score (RRF or DBSF)
+                        metadata=metadata,
+                        chunk_start_offset=result.payload.get("chunk_start_offset"),
+                        chunk_end_offset=result.payload.get("chunk_end_offset"),
+                        page_number=result.payload.get("page_number"),
+                        page_count=result.payload.get("page_count"),
+                        chunk_index=result.payload.get("chunk_index", 0),
+                        total_chunks=result.payload.get("total_chunks", 1),
+                        point_id=str(result.id),  # Qdrant point ID for batch retrieval
+                    )
                 )
-            )
 
-            if len(results) >= limit:
-                break
+                if len(results) >= limit:
+                    break
 
         logger.info(f"Returning {len(results)} unverified results after deduplication")
         if results:

nextcloud_mcp_server/search/context.py

@@ -209,6 +209,64 @@ async def _get_file_path_from_qdrant(
         return None
 
 
+async def _get_deck_metadata_from_qdrant(
+    user_id: str, card_id: int
+) -> dict[str, int] | None:
+    """Retrieve board_id and stack_id for a deck card from Qdrant payload.
+
+    Args:
+        user_id: User ID who owns the card
+        card_id: Card ID
+
+    Returns:
+        Dictionary with board_id and stack_id, or None if not found
+    """
+    try:
+        from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+        from nextcloud_mcp_server.config import get_settings
+        from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+        qdrant_client = await get_qdrant_client()
+        settings = get_settings()
+
+        # Query for any chunk of this card (we just need metadata)
+        scroll_result = await qdrant_client.scroll(
+            collection_name=settings.get_collection_name(),
+            scroll_filter=Filter(
+                must=[
+                    FieldCondition(key="user_id", match=MatchValue(value=user_id)),
+                    FieldCondition(key="doc_id", match=MatchValue(value=card_id)),
+                    FieldCondition(key="doc_type", match=MatchValue(value="deck_card")),
+                ]
+            ),
+            limit=1,
+            with_payload=["board_id", "stack_id"],
+            with_vectors=False,
+        )
+
+        if scroll_result[0]:
+            point = scroll_result[0][0]
+            board_id = point.payload.get("board_id")
+            stack_id = point.payload.get("stack_id")
+            if board_id is not None and stack_id is not None:
+                logger.debug(
+                    f"Retrieved deck metadata for card {card_id}: "
+                    f"board_id={board_id}, stack_id={stack_id}"
+                )
+                return {"board_id": int(board_id), "stack_id": int(stack_id)}
+
+        logger.debug(
+            f"Could not find deck metadata in Qdrant for card {card_id} "
+            f"(might be legacy data without board_id/stack_id)"
+        )
+        return None
+
+    except Exception as e:
+        logger.debug(f"Error querying Qdrant for deck metadata: {e}")
+        return None
+
+
 @dataclass
 class ChunkContext:
     """Expanded chunk with surrounding context and position markers.
@@ -394,7 +452,9 @@ async def get_chunk_with_context(
         logger.debug(f"Resolved file_id {doc_id} to file_path {file_path}")
 
     # Fetch full document text
-    full_text = await _fetch_document_text(nc_client, resolved_doc_id, doc_type)
+    full_text = await _fetch_document_text(
+        nc_client, resolved_doc_id, doc_type, user_id
+    )
     if full_text is None:
         logger.warning(
             f"Could not fetch document text for {doc_type} {doc_id}, "
@@ -453,7 +513,7 @@ async def get_chunk_with_context(
 
 
 async def _fetch_document_text(
-    nc_client: NextcloudClient, doc_id: str | int, doc_type: str
+    nc_client: NextcloudClient, doc_id: str | int, doc_type: str, user_id: str
 ) -> str | None:
     """Fetch full text content of a document.
 
@@ -524,6 +584,96 @@ async def _fetch_document_text(
                     f"Error fetching file content for {doc_id}: {e}", exc_info=True
                 )
                 return None
+        elif doc_type == "news_item":
+            # Fetch news item by ID
+            from nextcloud_mcp_server.vector.html_processor import html_to_markdown
+
+            item = await nc_client.news.get_item(int(doc_id))
+            # Reconstruct full content as indexed: title + source + URL + body
+            # This ensures chunk offsets align with indexed content structure
+            body_markdown = html_to_markdown(item.get("body", ""))
+            item_title = item.get("title", "")
+            item_url = item.get("url", "")
+            feed_title = item.get("feedTitle", "")
+
+            content_parts = [item_title]
+            if feed_title:
+                content_parts.append(f"Source: {feed_title}")
+            if item_url:
+                content_parts.append(f"URL: {item_url}")
+            content_parts.append("")  # Blank line
+            content_parts.append(body_markdown)
+            return "\n".join(content_parts)
+        elif doc_type == "deck_card":
+            # Fetch card from Deck API
+            # Try to get board_id/stack_id from Qdrant metadata (O(1) lookup)
+            # Otherwise fall back to iteration (legacy data)
+            card = None
+            deck_metadata = await _get_deck_metadata_from_qdrant(user_id, int(doc_id))
+
+            if deck_metadata:
+                # Fast path: Direct lookup with known board_id/stack_id
+                board_id = deck_metadata["board_id"]
+                stack_id = deck_metadata["stack_id"]
+                try:
+                    card = await nc_client.deck.get_card(
+                        board_id=board_id, stack_id=stack_id, card_id=int(doc_id)
+                    )
+                    logger.debug(
+                        f"Retrieved deck card {doc_id} using metadata "
+                        f"(board_id={board_id}, stack_id={stack_id})"
+                    )
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to fetch card with metadata (board_id={board_id}, "
+                        f"stack_id={stack_id}, card_id={doc_id}): {e}, falling back to iteration"
+                    )
+
+            # Fallback: Iterate through all boards/stacks (for legacy data or if fast path failed)
+            if card is None:
+                boards = await nc_client.deck.get_boards()
+                card_found = False
+
+                for board in boards:
+                    if card_found:
+                        break
+
+                    # Skip deleted boards (soft delete: deletedAt > 0)
+                    if board.deletedAt > 0:
+                        logger.debug(
+                            f"Skipping deleted board {board.id} while searching for card {doc_id}"
+                        )
+                        continue
+
+                    stacks = await nc_client.deck.get_stacks(board.id)
+
+                    for stack in stacks:
+                        if card_found:
+                            break
+                        if stack.cards:
+                            for c in stack.cards:
+                                if c.id == int(doc_id):
+                                    card = c
+                                    card_found = True
+                                    logger.debug(
+                                        f"Found deck card {doc_id} in board {board.id}, "
+                                        f"stack {stack.id} (fallback iteration)"
+                                    )
+                                    break
+
+                if not card_found:
+                    logger.warning(f"Deck card {doc_id} not found in any board/stack")
+                    return None
+
+            # Type narrowing: card is set if we reach here
+            assert card is not None
+
+            # Reconstruct full content as indexed: title + "\n\n" + description
+            # This ensures chunk offsets align with indexed content structure
+            content_parts = [card.title]
+            if card.description:
+                content_parts.append(card.description)
+            return "\n\n".join(content_parts)
         else:
             logger.warning(f"Unsupported doc_type for context expansion: {doc_type}")
             return None

nextcloud_mcp_server/search/semantic.py

@@ -136,6 +136,8 @@ class SemanticSearchAlgorithm(SearchAlgorithm):
         results = []
 
         for result in search_response.points:
+            if result.payload is None:
+                continue
             # doc_id can be int (notes) or str (files - file paths)
             doc_id = result.payload["doc_id"]
             doc_type = result.payload.get("doc_type", "note")
@@ -149,6 +151,21 @@ class SemanticSearchAlgorithm(SearchAlgorithm):
 
             seen_chunks.add(chunk_key)
 
+            # Build metadata dict with common fields
+            metadata = {
+                "chunk_index": result.payload.get("chunk_index"),
+                "total_chunks": result.payload.get("total_chunks"),
+            }
+
+            # Add file-specific metadata for PDF viewer
+            if doc_type == "file" and (path := result.payload.get("file_path")):
+                metadata["path"] = path
+
+            # Add deck_card-specific metadata for frontend URL construction
+            if doc_type == "deck_card":
+                if board_id := result.payload.get("board_id"):
+                    metadata["board_id"] = board_id
+
             # Return unverified results (verification happens at output stage)
             results.append(
                 SearchResult(
@@ -157,13 +174,11 @@ class SemanticSearchAlgorithm(SearchAlgorithm):
                     title=result.payload.get("title", "Untitled"),
                     excerpt=result.payload.get("excerpt", ""),
                     score=result.score,
-                    metadata={
-                        "chunk_index": result.payload.get("chunk_index"),
-                        "total_chunks": result.payload.get("total_chunks"),
-                    },
+                    metadata=metadata,
                     chunk_start_offset=result.payload.get("chunk_start_offset"),
                     chunk_end_offset=result.payload.get("chunk_end_offset"),
                     page_number=result.payload.get("page_number"),
+                    page_count=result.payload.get("page_count"),
                     chunk_index=result.payload.get("chunk_index", 0),
                     total_chunks=result.payload.get("total_chunks", 1),
                     point_id=str(result.id),  # Qdrant point ID for batch retrieval

nextcloud_mcp_server/server/__init__.py

@@ -2,6 +2,7 @@ from .calendar import configure_calendar_tools
 from .contacts import configure_contacts_tools
 from .cookbook import configure_cookbook_tools
 from .deck import configure_deck_tools
+from .news import configure_news_tools
 from .notes import configure_notes_tools
 from .semantic import configure_semantic_tools
 from .sharing import configure_sharing_tools
@@ -13,6 +14,7 @@ __all__ = [
     "configure_contacts_tools",
     "configure_cookbook_tools",
     "configure_deck_tools",
+    "configure_news_tools",
     "configure_notes_tools",
     "configure_semantic_tools",
     "configure_sharing_tools",

nextcloud_mcp_server/server/calendar.py

@@ -3,6 +3,7 @@ import logging
 from typing import Optional
 
 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -19,7 +20,10 @@ logger = logging.getLogger(__name__)
 
 def configure_calendar_tools(mcp: FastMCP):
     # Calendar tools
-    @mcp.tool()
+    @mcp.tool(
+        title="List Calendars",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("calendar:read")
     @instrument_tool
     async def nc_calendar_list_calendars(ctx: Context) -> ListCalendarsResponse:
@@ -30,7 +34,10 @@ def configure_calendar_tools(mcp: FastMCP):
         calendars = [Calendar(**cal_data) for cal_data in calendars_data]
         return ListCalendarsResponse(calendars=calendars, total_count=len(calendars))
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Calendar Event",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("calendar:write")
     @instrument_tool
     async def nc_calendar_create_event(
@@ -107,7 +114,10 @@ def configure_calendar_tools(mcp: FastMCP):
 
         return await client.calendar.create_event(calendar_name, event_data)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Calendar Events",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("calendar:read")
     @instrument_tool
     async def nc_calendar_list_events(
@@ -210,7 +220,10 @@ def configure_calendar_tools(mcp: FastMCP):
 
             return events
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Calendar Event",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("calendar:read")
     @instrument_tool
     async def nc_calendar_get_event(
@@ -223,7 +236,10 @@ def configure_calendar_tools(mcp: FastMCP):
         event_data, etag = await client.calendar.get_event(calendar_name, event_uid)
         return event_data
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Calendar Event",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("calendar:write")
     @instrument_tool
     async def nc_calendar_update_event(
@@ -297,7 +313,12 @@ def configure_calendar_tools(mcp: FastMCP):
             calendar_name, event_uid, event_data, etag
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Calendar Event",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("calendar:write")
     @instrument_tool
     async def nc_calendar_delete_event(
@@ -309,7 +330,10 @@ def configure_calendar_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.calendar.delete_event(calendar_name, event_uid)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Meeting",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("calendar:write")
     @instrument_tool
     async def nc_calendar_create_meeting(
@@ -376,7 +400,10 @@ def configure_calendar_tools(mcp: FastMCP):
 
         return await client.calendar.create_event(calendar_name, event_data)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Upcoming Events",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("calendar:read")
     @instrument_tool
     async def nc_calendar_get_upcoming_events(
@@ -427,7 +454,10 @@ def configure_calendar_tools(mcp: FastMCP):
             all_events.sort(key=lambda x: x.get("start_datetime", ""))
             return all_events[:limit]
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Find Availability",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("calendar:read")
     @instrument_tool
     async def nc_calendar_find_availability(
@@ -508,7 +538,10 @@ def configure_calendar_tools(mcp: FastMCP):
             constraints=constraints,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Bulk Calendar Operations",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("calendar:write")
     @instrument_tool
     async def nc_calendar_bulk_operations(
@@ -758,7 +791,10 @@ def configure_calendar_tools(mcp: FastMCP):
                 "results": results,
             }
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Manage Calendar",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("calendar:write")
     @instrument_tool
     async def nc_calendar_manage_calendar(
@@ -828,7 +864,10 @@ def configure_calendar_tools(mcp: FastMCP):
 
     # ============= Todo/Task Tools =============
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Todo Tasks",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("todo:read", "calendar:read")
     @instrument_tool
     async def nc_calendar_list_todos(
@@ -874,7 +913,10 @@ def configure_calendar_tools(mcp: FastMCP):
             todos=todos, calendar_name=calendar_name, total_count=len(todos)
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Todo Task",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("todo:write", "calendar:read")
     @instrument_tool
     async def nc_calendar_create_todo(
@@ -918,7 +960,10 @@ def configure_calendar_tools(mcp: FastMCP):
 
         return await client.calendar.create_todo(calendar_name, todo_data)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Todo Task",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("todo:write", "calendar:read")
     @instrument_tool
     async def nc_calendar_update_todo(
@@ -979,7 +1024,12 @@ def configure_calendar_tools(mcp: FastMCP):
 
         return await client.calendar.update_todo(calendar_name, todo_uid, todo_data)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Todo Task",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("todo:write", "calendar:read")
     @instrument_tool
     async def nc_calendar_delete_todo(
@@ -1000,7 +1050,10 @@ def configure_calendar_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.calendar.delete_todo(calendar_name, todo_uid)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Search Todo Tasks",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("todo:read", "calendar:read")
     @instrument_tool
     async def nc_calendar_search_todos(

nextcloud_mcp_server/server/contacts.py

@@ -1,6 +1,7 @@
 import logging
 
 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -11,7 +12,10 @@ logger = logging.getLogger(__name__)
 
 def configure_contacts_tools(mcp: FastMCP):
     # Contacts tools
-    @mcp.tool()
+    @mcp.tool(
+        title="List Address Books",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("contacts:read")
     @instrument_tool
     async def nc_contacts_list_addressbooks(ctx: Context):
@@ -19,7 +23,10 @@ def configure_contacts_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.contacts.list_addressbooks()
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Contacts",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("contacts:read")
     @instrument_tool
     async def nc_contacts_list_contacts(ctx: Context, *, addressbook: str):
@@ -27,7 +34,10 @@ def configure_contacts_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.contacts.list_contacts(addressbook=addressbook)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Address Book",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("contacts:write")
     @instrument_tool
     async def nc_contacts_create_addressbook(
@@ -44,7 +54,12 @@ def configure_contacts_tools(mcp: FastMCP):
             name=name, display_name=display_name
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Address Book",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("contacts:write")
     @instrument_tool
     async def nc_contacts_delete_addressbook(ctx: Context, *, name: str):
@@ -52,7 +67,10 @@ def configure_contacts_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.contacts.delete_addressbook(name=name)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Contact",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("contacts:write")
     @instrument_tool
     async def nc_contacts_create_contact(
@@ -70,7 +88,12 @@ def configure_contacts_tools(mcp: FastMCP):
             addressbook=addressbook, uid=uid, contact_data=contact_data
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Contact",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("contacts:write")
     @instrument_tool
     async def nc_contacts_delete_contact(ctx: Context, *, addressbook: str, uid: str):
@@ -78,7 +101,10 @@ def configure_contacts_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.contacts.delete_contact(addressbook=addressbook, uid=uid)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Contact",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("contacts:write")
     @instrument_tool
     async def nc_contacts_update_contact(

nextcloud_mcp_server/server/cookbook.py

@@ -3,7 +3,7 @@ import logging
 from httpx import HTTPStatusError, RequestError
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
-from mcp.types import ErrorData
+from mcp.types import ErrorData, ToolAnnotations
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -71,7 +71,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Import Recipe from URL",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("cookbook:write")
     @instrument_tool
     async def nc_cookbook_import_recipe(url: str, ctx: Context) -> ImportRecipeResponse:
@@ -129,7 +132,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Recipes",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("cookbook:read")
     @instrument_tool
     async def nc_cookbook_list_recipes(ctx: Context) -> ListRecipesResponse:
@@ -155,7 +161,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Recipe",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("cookbook:read")
     @instrument_tool
     async def nc_cookbook_get_recipe(recipe_id: int, ctx: Context) -> Recipe:
@@ -181,7 +190,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Recipe",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("cookbook:write")
     @instrument_tool
     async def nc_cookbook_create_recipe(
@@ -261,7 +273,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Recipe",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("cookbook:write")
     @instrument_tool
     async def nc_cookbook_update_recipe(
@@ -351,7 +366,12 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Recipe",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("cookbook:write")
     @instrument_tool
     async def nc_cookbook_delete_recipe(
@@ -387,7 +407,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Search Recipes",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("cookbook:read")
     @instrument_tool
     async def nc_cookbook_search_recipes(
@@ -424,7 +447,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Recipe Categories",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("cookbook:read")
     @instrument_tool
     async def nc_cookbook_list_categories(ctx: Context) -> ListCategoriesResponse:
@@ -452,7 +478,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Recipes in Category",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("cookbook:read")
     @instrument_tool
     async def nc_cookbook_get_recipes_in_category(
@@ -489,7 +518,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Recipe Keywords",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("cookbook:read")
     @instrument_tool
     async def nc_cookbook_list_keywords(ctx: Context) -> ListKeywordsResponse:
@@ -515,7 +547,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Recipes with Keywords",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("cookbook:read")
     @instrument_tool
     async def nc_cookbook_get_recipes_with_keywords(
@@ -550,7 +585,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Set Cookbook Configuration",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("cookbook:write")
     @instrument_tool
     async def nc_cookbook_set_config(
@@ -594,7 +632,10 @@ def configure_cookbook_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Reindex Recipes",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("cookbook:write")
     @instrument_tool
     async def nc_cookbook_reindex(ctx: Context) -> ReindexResponse:

nextcloud_mcp_server/server/deck.py

@@ -2,6 +2,7 @@ import logging
 from typing import Optional
 
 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -117,7 +118,10 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Read Tools (converted from resources)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Deck Boards",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("deck:read")
     @instrument_tool
     async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
@@ -126,7 +130,10 @@ def configure_deck_tools(mcp: FastMCP):
         boards = await client.deck.get_boards()
         return boards
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Deck Board",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("deck:read")
     @instrument_tool
     async def deck_get_board(ctx: Context, board_id: int) -> DeckBoard:
@@ -135,7 +142,10 @@ def configure_deck_tools(mcp: FastMCP):
         board = await client.deck.get_board(board_id)
         return board
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Deck Stacks",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("deck:read")
     @instrument_tool
     async def deck_get_stacks(ctx: Context, board_id: int) -> list[DeckStack]:
@@ -144,7 +154,10 @@ def configure_deck_tools(mcp: FastMCP):
         stacks = await client.deck.get_stacks(board_id)
         return stacks
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Deck Stack",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("deck:read")
     @instrument_tool
     async def deck_get_stack(ctx: Context, board_id: int, stack_id: int) -> DeckStack:
@@ -153,7 +166,10 @@ def configure_deck_tools(mcp: FastMCP):
         stack = await client.deck.get_stack(board_id, stack_id)
         return stack
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Deck Cards",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("deck:read")
     @instrument_tool
     async def deck_get_cards(
@@ -166,7 +182,10 @@ def configure_deck_tools(mcp: FastMCP):
             return stack.cards
         return []
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Deck Card",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("deck:read")
     @instrument_tool
     async def deck_get_card(
@@ -177,7 +196,10 @@ def configure_deck_tools(mcp: FastMCP):
         card = await client.deck.get_card(board_id, stack_id, card_id)
         return card
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Deck Labels",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("deck:read")
     @instrument_tool
     async def deck_get_labels(ctx: Context, board_id: int) -> list[DeckLabel]:
@@ -186,7 +208,10 @@ def configure_deck_tools(mcp: FastMCP):
         board = await client.deck.get_board(board_id)
         return board.labels
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Deck Label",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("deck:read")
     @instrument_tool
     async def deck_get_label(ctx: Context, board_id: int, label_id: int) -> DeckLabel:
@@ -197,7 +222,10 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Create/Update/Delete Tools
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Deck Board",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_create_board(
@@ -215,7 +243,10 @@ def configure_deck_tools(mcp: FastMCP):
 
     # Stack Tools
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Deck Stack",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_create_stack(
@@ -232,7 +263,10 @@ def configure_deck_tools(mcp: FastMCP):
         stack = await client.deck.create_stack(board_id, title, order)
         return CreateStackResponse(id=stack.id, title=stack.title, order=stack.order)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Deck Stack",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_update_stack(
@@ -259,7 +293,12 @@ def configure_deck_tools(mcp: FastMCP):
             board_id=board_id,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Deck Stack",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_delete_stack(
@@ -281,7 +320,10 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     # Card Tools
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_create_card(
@@ -316,7 +358,10 @@ def configure_deck_tools(mcp: FastMCP):
             stackId=card.stackId,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_update_card(
@@ -370,7 +415,12 @@ def configure_deck_tools(mcp: FastMCP):
             board_id=board_id,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Deck Card",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_delete_card(
@@ -393,7 +443,10 @@ def configure_deck_tools(mcp: FastMCP):
             board_id=board_id,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Archive Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_archive_card(
@@ -416,7 +469,10 @@ def configure_deck_tools(mcp: FastMCP):
             board_id=board_id,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Unarchive Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_unarchive_card(
@@ -439,7 +495,10 @@ def configure_deck_tools(mcp: FastMCP):
             board_id=board_id,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Reorder/Move Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_reorder_card(
@@ -472,7 +531,10 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     # Label Tools
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Deck Label",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_create_label(
@@ -489,7 +551,10 @@ def configure_deck_tools(mcp: FastMCP):
         label = await client.deck.create_label(board_id, title, color)
         return CreateLabelResponse(id=label.id, title=label.title, color=label.color)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Deck Label",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_update_label(
@@ -516,7 +581,12 @@ def configure_deck_tools(mcp: FastMCP):
             board_id=board_id,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Deck Label",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_delete_label(
@@ -538,7 +608,10 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     # Card-Label Assignment Tools
-    @mcp.tool()
+    @mcp.tool(
+        title="Assign Label to Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_assign_label_to_card(
@@ -562,7 +635,10 @@ def configure_deck_tools(mcp: FastMCP):
             board_id=board_id,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Remove Label from Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_remove_label_from_card(
@@ -587,7 +663,10 @@ def configure_deck_tools(mcp: FastMCP):
         )
 
     # Card-User Assignment Tools
-    @mcp.tool()
+    @mcp.tool(
+        title="Assign User to Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_assign_user_to_card(
@@ -611,7 +690,10 @@ def configure_deck_tools(mcp: FastMCP):
             board_id=board_id,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Unassign User from Deck Card",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("deck:write")
     @instrument_tool
     async def deck_unassign_user_from_card(

nextcloud_mcp_server/server/news.py

@@ -0,0 +1,384 @@
+"""MCP tools for Nextcloud News app."""
+
+import logging
+
+from httpx import HTTPStatusError, RequestError
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.shared.exceptions import McpError
+from mcp.types import ErrorData, ToolAnnotations
+
+from nextcloud_mcp_server.auth import require_scopes
+from nextcloud_mcp_server.client.news import NewsItemType
+from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.models.news import (
+    FeedHealthResponse,
+    GetItemResponse,
+    GetStatusResponse,
+    ListFeedsResponse,
+    ListFoldersResponse,
+    ListItemsResponse,
+    NewsFeed,
+    NewsFolder,
+    NewsItem,
+    NewsItemSummary,
+)
+from nextcloud_mcp_server.observability.metrics import instrument_tool
+
+logger = logging.getLogger(__name__)
+
+
+def configure_news_tools(mcp: FastMCP):
+    """Configure News app MCP tools."""
+
+    @mcp.tool(
+        title="List News Folders",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
+    @require_scopes("news:read")
+    @instrument_tool
+    async def nc_news_list_folders(ctx: Context) -> ListFoldersResponse:
+        """List all News folders (requires news:read scope)."""
+        client = await get_client(ctx)
+        try:
+            folders_data = await client.news.get_folders()
+            folders = [NewsFolder(**f) for f in folders_data]
+            return ListFoldersResponse(results=folders, total_count=len(folders))
+        except RequestError as e:
+            raise McpError(
+                ErrorData(code=-1, message=f"Network error listing folders: {str(e)}")
+            )
+        except HTTPStatusError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Failed to list folders: {e.response.status_code}",
+                )
+            )
+
+    @mcp.tool(
+        title="List News Feeds",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
+    @require_scopes("news:read")
+    @instrument_tool
+    async def nc_news_list_feeds(ctx: Context) -> ListFeedsResponse:
+        """List all News feeds with metadata (requires news:read scope).
+
+        Returns feeds with unread counts, error status, and overall starred count.
+        """
+        client = await get_client(ctx)
+        try:
+            data = await client.news.get_feeds()
+            feeds = [NewsFeed(**f) for f in data.get("feeds", [])]
+            return ListFeedsResponse(
+                results=feeds,
+                starred_count=data.get("starredCount", 0),
+                newest_item_id=data.get("newestItemId"),
+                total_count=len(feeds),
+            )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(code=-1, message=f"Network error listing feeds: {str(e)}")
+            )
+        except HTTPStatusError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Failed to list feeds: {e.response.status_code}",
+                )
+            )
+
+    @mcp.tool(
+        title="List News Items",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
+    @require_scopes("news:read")
+    @instrument_tool
+    async def nc_news_list_items(
+        ctx: Context,
+        feed_id: int | None = None,
+        folder_id: int | None = None,
+        starred_only: bool = False,
+        unread_only: bool = False,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> ListItemsResponse:
+        """List News items (articles) with optional filtering (requires news:read scope).
+
+        Args:
+            feed_id: Filter by specific feed ID
+            folder_id: Filter by specific folder ID
+            starred_only: Return only starred items
+            unread_only: Return only unread items
+            limit: Maximum number of items to return (default 50, -1 for all)
+            offset: Item ID to start after (for pagination)
+
+        Returns:
+            ListItemsResponse with items, count, and pagination info
+        """
+        client = await get_client(ctx)
+
+        # Determine item type filter
+        type_ = NewsItemType.ALL
+        id_ = 0
+        if starred_only:
+            type_ = NewsItemType.STARRED
+        elif feed_id is not None:
+            type_ = NewsItemType.FEED
+            id_ = feed_id
+        elif folder_id is not None:
+            type_ = NewsItemType.FOLDER
+            id_ = folder_id
+
+        try:
+            items_data = await client.news.get_items(
+                batch_size=limit,
+                offset=offset,
+                type_=type_,
+                id_=id_,
+                get_read=not unread_only,
+            )
+            items = [NewsItemSummary(**i) for i in items_data]
+
+            # Determine pagination info
+            oldest_id = min((i.id for i in items), default=None) if items else None
+            has_more = len(items) == limit and limit > 0
+
+            return ListItemsResponse(
+                results=items,
+                total_count=len(items),
+                has_more=has_more,
+                oldest_id=oldest_id,
+            )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(code=-1, message=f"Network error listing items: {str(e)}")
+            )
+        except HTTPStatusError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Failed to list items: {e.response.status_code}",
+                )
+            )
+
+    @mcp.tool(
+        title="Get News Item",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
+    @require_scopes("news:read")
+    @instrument_tool
+    async def nc_news_get_item(item_id: int, ctx: Context) -> GetItemResponse:
+        """Get a specific News item by ID with full content (requires news:read scope).
+
+        Args:
+            item_id: Item ID
+
+        Returns:
+            GetItemResponse with full item details including HTML body
+        """
+        client = await get_client(ctx)
+        try:
+            item_data = await client.news.get_item(item_id)
+            item = NewsItem(**item_data)
+            return GetItemResponse(item=item)
+        except ValueError as e:
+            raise McpError(ErrorData(code=-1, message=str(e)))
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1, message=f"Network error getting item {item_id}: {str(e)}"
+                )
+            )
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise McpError(ErrorData(code=-1, message=f"Item {item_id} not found"))
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Failed to get item {item_id}: {e.response.status_code}",
+                )
+            )
+
+    @mcp.tool(
+        title="Get Starred News Items",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
+    @require_scopes("news:read")
+    @instrument_tool
+    async def nc_news_get_starred_items(
+        ctx: Context, limit: int = 50, offset: int = 0
+    ) -> ListItemsResponse:
+        """Get starred (favorited) News items (requires news:read scope).
+
+        Convenience method for retrieving user's starred articles.
+
+        Args:
+            limit: Maximum number of items to return (default 50, -1 for all)
+            offset: Item ID to start after (for pagination)
+
+        Returns:
+            ListItemsResponse with starred items
+        """
+        client = await get_client(ctx)
+        try:
+            items_data = await client.news.get_items(
+                batch_size=limit,
+                offset=offset,
+                type_=NewsItemType.STARRED,
+                get_read=True,  # Include read starred items
+            )
+            items = [NewsItemSummary(**i) for i in items_data]
+
+            oldest_id = min((i.id for i in items), default=None) if items else None
+            has_more = len(items) == limit and limit > 0
+
+            return ListItemsResponse(
+                results=items,
+                total_count=len(items),
+                has_more=has_more,
+                oldest_id=oldest_id,
+            )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1, message=f"Network error getting starred items: {str(e)}"
+                )
+            )
+        except HTTPStatusError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Failed to get starred items: {e.response.status_code}",
+                )
+            )
+
+    @mcp.tool(
+        title="Get Unread News Items",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
+    @require_scopes("news:read")
+    @instrument_tool
+    async def nc_news_get_unread_items(
+        ctx: Context, limit: int = 50, offset: int = 0
+    ) -> ListItemsResponse:
+        """Get unread News items (requires news:read scope).
+
+        Convenience method for retrieving unread articles across all feeds.
+
+        Args:
+            limit: Maximum number of items to return (default 50, -1 for all)
+            offset: Item ID to start after (for pagination)
+
+        Returns:
+            ListItemsResponse with unread items
+        """
+        client = await get_client(ctx)
+        try:
+            items_data = await client.news.get_items(
+                batch_size=limit,
+                offset=offset,
+                type_=NewsItemType.ALL,
+                get_read=False,  # Only unread items
+            )
+            items = [NewsItemSummary(**i) for i in items_data]
+
+            oldest_id = min((i.id for i in items), default=None) if items else None
+            has_more = len(items) == limit and limit > 0
+
+            return ListItemsResponse(
+                results=items,
+                total_count=len(items),
+                has_more=has_more,
+                oldest_id=oldest_id,
+            )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1, message=f"Network error getting unread items: {str(e)}"
+                )
+            )
+        except HTTPStatusError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Failed to get unread items: {e.response.status_code}",
+                )
+            )
+
+    @mcp.tool(
+        title="Get News Feed Health",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
+    @require_scopes("news:read")
+    @instrument_tool
+    async def nc_news_get_feed_health(feed_id: int, ctx: Context) -> FeedHealthResponse:
+        """Get health status for a specific feed (requires news:read scope).
+
+        Returns error count and last error message if the feed has update issues.
+
+        Args:
+            feed_id: Feed ID to check
+
+        Returns:
+            FeedHealthResponse with error status
+        """
+        client = await get_client(ctx)
+        try:
+            data = await client.news.get_feeds()
+            for feed_data in data.get("feeds", []):
+                if feed_data.get("id") == feed_id:
+                    feed = NewsFeed(**feed_data)
+                    return FeedHealthResponse(
+                        feed_id=feed.id,
+                        title=feed.title,
+                        url=feed.url,
+                        has_errors=feed.has_errors,
+                        error_count=feed.update_error_count,
+                        last_error=feed.last_update_error,
+                    )
+            raise McpError(ErrorData(code=-1, message=f"Feed {feed_id} not found"))
+        except RequestError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Network error getting feed health: {str(e)}",
+                )
+            )
+        except HTTPStatusError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Failed to get feed health: {e.response.status_code}",
+                )
+            )
+
+    @mcp.tool(
+        title="Get News App Status",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
+    @require_scopes("news:read")
+    @instrument_tool
+    async def nc_news_get_status(ctx: Context) -> GetStatusResponse:
+        """Get News app status and version (requires news:read scope).
+
+        Returns version information and any configuration warnings.
+        """
+        client = await get_client(ctx)
+        try:
+            status_data = await client.news.get_status()
+            return GetStatusResponse(
+                version=status_data.get("version", "unknown"),
+                warnings=status_data.get("warnings", {}),
+            )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(code=-1, message=f"Network error getting status: {str(e)}")
+            )
+        except HTTPStatusError as e:
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Failed to get status: {e.response.status_code}",
+                )
+            )

nextcloud_mcp_server/server/notes.py

@@ -3,7 +3,7 @@ import logging
 from httpx import HTTPStatusError, RequestError
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
-from mcp.types import ErrorData
+from mcp.types import ErrorData, ToolAnnotations
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -85,7 +85,13 @@ def configure_notes_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Note",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Multiple calls create multiple notes
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("notes:write")
     @instrument_tool
     async def nc_notes_create_note(
@@ -132,7 +138,13 @@ def configure_notes_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Note",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Requires etag which changes = not idempotent
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("notes:write")
     @instrument_tool
     async def nc_notes_update_note(
@@ -198,7 +210,13 @@ def configure_notes_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Append to Note",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Each call adds content = not idempotent
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("notes:write")
     @instrument_tool
     async def nc_notes_append_content(
@@ -249,7 +267,13 @@ def configure_notes_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Search Notes",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Search doesn't modify data
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("notes:read")
     @instrument_tool
     async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
@@ -296,7 +320,13 @@ def configure_notes_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Note",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Read operation only
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("notes:read")
     @instrument_tool
     async def nc_notes_get_note(note_id: int, ctx: Context) -> Note:
@@ -326,7 +356,13 @@ def configure_notes_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Note Attachment",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Read operation only
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("notes:read")
     @instrument_tool
     async def nc_notes_get_attachment(
@@ -373,7 +409,14 @@ def configure_notes_tools(mcp: FastMCP):
                     )
                 )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Note",
+        annotations=ToolAnnotations(
+            destructiveHint=True,  # Permanently deletes data
+            idempotentHint=True,  # Deleting deleted note = same end state
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("notes:write")
     @instrument_tool
     async def nc_notes_delete_note(note_id: int, ctx: Context) -> DeleteNoteResponse:

nextcloud_mcp_server/server/oauth_tools.py

@@ -15,6 +15,7 @@ import httpx
 from mcp.server.auth.middleware.auth_context import get_access_token
 from mcp.server.auth.provider import AccessToken
 from mcp.server.fastmcp import Context
+from mcp.types import ToolAnnotations
 from pydantic import BaseModel, Field
 
 from nextcloud_mcp_server.auth import require_scopes
@@ -417,11 +418,12 @@ async def revoke_nextcloud_access(
         storage = RefreshTokenStorage.from_env()
         await storage.initialize()
 
-        encryption_key = os.getenv("TOKEN_ENCRYPTION_KEY")
-        if not encryption_key:
+        # Get OAuth client credentials from storage
+        client_creds = await storage.get_oauth_client()
+        if not client_creds:
             return RevocationResult(
                 success=False,
-                message="Token encryption key not configured.",
+                message="OAuth client credentials not found in storage.",
             )
 
         broker = TokenBrokerService(
@@ -431,7 +433,8 @@ async def revoke_nextcloud_access(
                 f"{os.getenv('NEXTCLOUD_HOST')}/.well-known/openid-configuration",
             ),
             nextcloud_host=os.getenv("NEXTCLOUD_HOST"),  # type: ignore
-            encryption_key=encryption_key,
+            client_id=client_creds["client_id"],
+            client_secret=client_creds["client_secret"],
         )
 
         # Revoke access
@@ -684,11 +687,16 @@ def register_oauth_tools(mcp):
 
     @mcp.tool(
         name="provision_nextcloud_access",
+        title="Grant Server Access to Nextcloud",
         description=(
             "Provision offline access to Nextcloud resources. "
             "This is required before using Nextcloud tools. "
             "You'll need to complete an OAuth authorization in your browser."
         ),
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Creates new OAuth session each time
+            openWorldHint=True,
+        ),
     )
     @require_scopes("openid")
     async def tool_provision_access(
@@ -699,7 +707,13 @@ def register_oauth_tools(mcp):
 
     @mcp.tool(
         name="revoke_nextcloud_access",
+        title="Revoke Server Access to Nextcloud",
         description="Revoke offline access to Nextcloud resources.",
+        annotations=ToolAnnotations(
+            destructiveHint=True,  # Removes stored access tokens
+            idempotentHint=True,  # Revoking revoked access = same end state
+            openWorldHint=True,
+        ),
     )
     @require_scopes("openid")
     async def tool_revoke_access(
@@ -709,7 +723,12 @@ def register_oauth_tools(mcp):
 
     @mcp.tool(
         name="check_provisioning_status",
+        title="Check Provisioning Status",
         description="Check whether Nextcloud access is provisioned.",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Only checks status, doesn't modify
+            openWorldHint=True,
+        ),
     )
     @require_scopes("openid")
     async def tool_check_status(
@@ -719,10 +738,15 @@ def register_oauth_tools(mcp):
 
     @mcp.tool(
         name="check_logged_in",
+        title="Check Server Login Status",
         description=(
             "Check if you are logged in to Nextcloud. "
             "If not logged in, this tool will prompt you to complete the login flow."
         ),
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Checking status doesn't modify state
+            openWorldHint=True,
+        ),
     )
     @require_scopes("openid")
     async def tool_check_logged_in(ctx: Context, user_id: Optional[str] = None) -> str:

nextcloud_mcp_server/server/semantic.py

@@ -12,6 +12,7 @@ from mcp.types import (
     ModelPreferences,
     SamplingMessage,
     TextContent,
+    ToolAnnotations,
 )
 
 from nextcloud_mcp_server.auth import require_scopes
@@ -34,7 +35,13 @@ logger = logging.getLogger(__name__)
 def configure_semantic_tools(mcp: FastMCP):
     """Configure semantic search tools for MCP server."""
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Semantic Search",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Search doesn't modify data
+            openWorldHint=True,  # Queries external Nextcloud service
+        ),
+    )
     @require_scopes("semantic:read")
     @instrument_tool
     async def nc_semantic_search(
@@ -58,13 +65,13 @@ def configure_semantic_tools(mcp: FastMCP):
         database for optimal relevance. This provides the best of both semantic
         understanding and keyword precision.
 
-        Requires VECTOR_SYNC_ENABLED=true. Currently only "note" documents are
-        fully supported for indexing.
+        Requires VECTOR_SYNC_ENABLED=true. Supports indexing of notes, files,
+        news items, and deck cards.
 
         Args:
             query: Natural language or keyword search query
             limit: Maximum number of results to return (default: 10)
-            doc_types: Document types to search (e.g., ["note", "file"]). None = search all indexed types (default)
+            doc_types: Document types to search (e.g., ["note", "file", "deck_card", "news_item"]). None = search all indexed types (default)
             score_threshold: Minimum fusion score (0-1, default: 0.0)
             fusion: Fusion algorithm: "rrf" (Reciprocal Rank Fusion, default) or "dbsf" (Distribution-Based Score Fusion)
                    RRF: Good general-purpose fusion using reciprocal ranks
@@ -285,7 +292,13 @@ def configure_semantic_tools(mcp: FastMCP):
             logger.error(f"Search error: {e}", exc_info=True)
             raise McpError(ErrorData(code=-1, message=f"Search failed: {str(e)}"))
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Search with AI-Generated Answer",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Search doesn't modify data
+            openWorldHint=False,  # Searches only indexed Nextcloud data
+        ),
+    )
     @require_scopes("semantic:read")
     @instrument_tool
     async def nc_semantic_search_answer(
@@ -499,9 +512,11 @@ def configure_semantic_tools(mcp: FastMCP):
         )
 
         # 6. Request LLM completion via MCP sampling with timeout
+        # Note: 5 minute timeout to accommodate slower local LLMs (e.g., Ollama)
+        sampling_timeout_seconds = 300
 
         try:
-            with anyio.fail_after(30):
+            with anyio.fail_after(sampling_timeout_seconds):
                 sampling_result = await ctx.session.create_message(
                     messages=[
                         SamplingMessage(
@@ -548,14 +563,14 @@ def configure_semantic_tools(mcp: FastMCP):
 
         except TimeoutError:
             logger.warning(
-                f"Sampling request timed out after 30 seconds for query: '{query}', "
+                f"Sampling request timed out after {sampling_timeout_seconds} seconds for query: '{query}', "
                 f"returning search results only"
             )
             return SamplingSearchResponse(
                 query=query,
                 generated_answer=(
                     f"[Sampling request timed out]\n\n"
-                    f"The answer generation took too long (>30s). "
+                    f"The answer generation took too long (>{sampling_timeout_seconds}s). "
                     f"Found {len(accessible_results)} relevant documents. "
                     f"Please review the sources below or try a simpler query."
                 ),
@@ -621,7 +636,13 @@ def configure_semantic_tools(mcp: FastMCP):
                 success=True,
             )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Check Indexing Status",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,  # Only checks status
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("semantic:read")
     @instrument_tool
     async def nc_get_vector_sync_status(ctx: Context) -> VectorSyncStatusResponse:
@@ -675,15 +696,22 @@ def configure_semantic_tools(mcp: FastMCP):
             # Get Qdrant client and query indexed count
             indexed_count = 0
             try:
+                from qdrant_client.models import Filter
+
                 from nextcloud_mcp_server.config import get_settings
+                from nextcloud_mcp_server.vector.placeholder import (
+                    get_placeholder_filter,
+                )
                 from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
 
                 settings = get_settings()
                 qdrant_client = await get_qdrant_client()
 
-                # Count documents in collection
+                # Count documents in collection, excluding placeholders
+                # Placeholders are zero-vector points used to track processing state
                 count_result = await qdrant_client.count(
-                    collection_name=settings.get_collection_name()
+                    collection_name=settings.get_collection_name(),
+                    count_filter=Filter(must=[get_placeholder_filter()]),
                 )
                 indexed_count = count_result.count
 

nextcloud_mcp_server/server/sharing.py

@@ -3,6 +3,7 @@
 import json
 
 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -16,7 +17,10 @@ def configure_sharing_tools(mcp: FastMCP):
         mcp: FastMCP server instance
     """
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Share",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("sharing:write")
     @instrument_tool
     async def nc_share_create(
@@ -56,7 +60,12 @@ def configure_sharing_tools(mcp: FastMCP):
         )
         return json.dumps(share_data, indent=2)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Share",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("sharing:write")
     @instrument_tool
     async def nc_share_delete(share_id: int, ctx: Context) -> str:
@@ -76,7 +85,10 @@ def configure_sharing_tools(mcp: FastMCP):
             {"success": True, "message": f"Share {share_id} deleted"}, indent=2
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Share Details",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("sharing:write")
     @instrument_tool
     async def nc_share_get(share_id: int, ctx: Context) -> str:
@@ -95,7 +107,10 @@ def configure_sharing_tools(mcp: FastMCP):
         share_data = await client.sharing.get_share(share_id)
         return json.dumps(share_data, indent=2)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Shares",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("sharing:write")
     @instrument_tool
     async def nc_share_list(
@@ -117,7 +132,10 @@ def configure_sharing_tools(mcp: FastMCP):
         )
         return json.dumps(shares, indent=2)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Share",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("sharing:write")
     @instrument_tool
     async def nc_share_update(share_id: int, permissions: int, ctx: Context) -> str:

nextcloud_mcp_server/server/tables.py

@@ -1,6 +1,7 @@
 import logging
 
 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -11,7 +12,10 @@ logger = logging.getLogger(__name__)
 
 def configure_tables_tools(mcp: FastMCP):
     # Tables tools
-    @mcp.tool()
+    @mcp.tool(
+        title="List Tables",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("tables:read")
     @instrument_tool
     async def nc_tables_list_tables(ctx: Context):
@@ -19,7 +23,10 @@ def configure_tables_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.tables.list_tables()
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Get Table Schema",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("tables:read")
     @instrument_tool
     async def nc_tables_get_schema(table_id: int, ctx: Context):
@@ -27,7 +34,10 @@ def configure_tables_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.tables.get_table_schema(table_id)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Read Table Rows",
+        annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
+    )
     @require_scopes("tables:read")
     @instrument_tool
     async def nc_tables_read_table(
@@ -40,7 +50,10 @@ def configure_tables_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.tables.get_table_rows(table_id, limit, offset)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Insert Table Row",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("tables:write")
     @instrument_tool
     async def nc_tables_insert_row(table_id: int, data: dict, ctx: Context):
@@ -51,7 +64,10 @@ def configure_tables_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.tables.create_row(table_id, data)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Update Table Row",
+        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+    )
     @require_scopes("tables:write")
     @instrument_tool
     async def nc_tables_update_row(row_id: int, data: dict, ctx: Context):
@@ -62,7 +78,12 @@ def configure_tables_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.tables.update_row(row_id, data)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete Table Row",
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
+    )
     @require_scopes("tables:write")
     @instrument_tool
     async def nc_tables_delete_row(row_id: int, ctx: Context):

nextcloud_mcp_server/server/webdav.py

@@ -1,6 +1,7 @@
 import logging
 
 from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
@@ -16,7 +17,13 @@ logger = logging.getLogger(__name__)
 
 def configure_webdav_tools(mcp: FastMCP):
     # WebDAV file system tools
-    @mcp.tool()
+    @mcp.tool(
+        title="List Files and Directories",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:read")
     @instrument_tool
     async def nc_webdav_list_directory(
@@ -50,7 +57,13 @@ def configure_webdav_tools(mcp: FastMCP):
             total_size=total_size,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Read File",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:read")
     @instrument_tool
     async def nc_webdav_read_file(path: str, ctx: Context):
@@ -117,7 +130,13 @@ def configure_webdav_tools(mcp: FastMCP):
             "encoding": "base64",
         }
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Write File",
+        annotations=ToolAnnotations(
+            idempotentHint=True,  # HTTP PUT without version control is idempotent
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:write")
     @instrument_tool
     async def nc_webdav_write_file(
@@ -146,7 +165,13 @@ def configure_webdav_tools(mcp: FastMCP):
 
         return await client.webdav.write_file(path, content_bytes, content_type)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Create Directory",
+        annotations=ToolAnnotations(
+            idempotentHint=True,  # Creating existing dir returns 405 = same end state
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:write")
     @instrument_tool
     async def nc_webdav_create_directory(path: str, ctx: Context):
@@ -161,7 +186,14 @@ def configure_webdav_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.webdav.create_directory(path)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Delete File or Directory",
+        annotations=ToolAnnotations(
+            destructiveHint=True,  # Permanently deletes data
+            idempotentHint=True,  # Deleting deleted resource = same end state
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:write")
     @instrument_tool
     async def nc_webdav_delete_resource(path: str, ctx: Context):
@@ -176,7 +208,13 @@ def configure_webdav_tools(mcp: FastMCP):
         client = await get_client(ctx)
         return await client.webdav.delete_resource(path)
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Move or Rename File",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Moving changes source and dest
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:write")
     @instrument_tool
     async def nc_webdav_move_resource(
@@ -197,7 +235,13 @@ def configure_webdav_tools(mcp: FastMCP):
             source_path, destination_path, overwrite
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Copy File or Directory",
+        annotations=ToolAnnotations(
+            idempotentHint=False,  # Creates new resource each time
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:write")
     @instrument_tool
     async def nc_webdav_copy_resource(
@@ -218,7 +262,13 @@ def configure_webdav_tools(mcp: FastMCP):
             source_path, destination_path, overwrite
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Search Files",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:read")
     @instrument_tool
     async def nc_webdav_search_files(
@@ -335,7 +385,13 @@ def configure_webdav_tools(mcp: FastMCP):
             filters_applied=filters if filters else None,
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Find Files by Name",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:read")
     @instrument_tool
     async def nc_webdav_find_by_name(
@@ -363,7 +419,13 @@ def configure_webdav_tools(mcp: FastMCP):
             filters_applied={"name_pattern": pattern},
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="Find Files by Type",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:read")
     @instrument_tool
     async def nc_webdav_find_by_type(
@@ -391,7 +453,13 @@ def configure_webdav_tools(mcp: FastMCP):
             filters_applied={"mime_type": mime_type},
         )
 
-    @mcp.tool()
+    @mcp.tool(
+        title="List Favorite Files",
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            openWorldHint=True,
+        ),
+    )
     @require_scopes("files:read")
     @instrument_tool
     async def nc_webdav_list_favorites(

nextcloud_mcp_server/vector/html_processor.py

@@ -0,0 +1,49 @@
+"""HTML to Markdown conversion utilities for vector sync."""
+
+import logging
+
+from markdownify import markdownify as md
+
+logger = logging.getLogger(__name__)
+
+
+def html_to_markdown(html_content: str | None) -> str:
+    """Convert HTML content to Markdown, preserving semantic structure.
+
+    This function converts HTML (typically from RSS/Atom feed items) to Markdown
+    for better text embedding. Markdown preserves:
+    - Heading hierarchy (important for document structure)
+    - Lists (bullet and numbered)
+    - Links (as [text](url))
+    - Bold/italic emphasis
+    - Paragraphs and line breaks
+
+    Args:
+        html_content: HTML string to convert (may be None or empty)
+
+    Returns:
+        Markdown string, or empty string if input is None/empty
+
+    Example:
+        >>> html_to_markdown("<h1>Title</h1><p>Content with <b>bold</b>.</p>")
+        '# Title\\n\\nContent with **bold**.\\n\\n'
+    """
+    if not html_content:
+        return ""
+
+    try:
+        markdown = md(
+            html_content,
+            heading_style="ATX",  # Use # style headings
+            strip=["script", "style", "iframe", "noscript"],  # Remove unsafe elements
+            bullets="-",  # Use - for unordered lists
+            code_language="",  # Don't add language hints to code blocks
+        )
+        return markdown.strip()
+    except Exception as e:
+        logger.warning(f"Failed to convert HTML to Markdown: {e}")
+        # Fallback: strip all HTML tags as a last resort
+        import re
+
+        text = re.sub(r"<[^>]+>", " ", html_content)
+        return " ".join(text.split())  # Normalize whitespace

nextcloud_mcp_server/vector/oauth_sync.py

@@ -0,0 +1,352 @@
+"""OAuth mode vector sync orchestration.
+
+Manages multi-user background vector sync when running in OAuth mode
+with ENABLE_OFFLINE_ACCESS=true:
+- User Manager: Monitors RefreshTokenStorage for user changes
+- Per-User Scanners: One scanner task per provisioned user
+- Shared Processor Pool: Processes documents from all users
+"""
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import anyio
+from anyio.abc import TaskGroup, TaskStatus
+from anyio.streams.memory import (
+    MemoryObjectReceiveStream,
+    MemoryObjectSendStream,
+)
+
+from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.vector.scanner import DocumentTask, scan_user_documents
+
+if TYPE_CHECKING:
+    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+    from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
+
+logger = logging.getLogger(__name__)
+
+# Scopes required for vector sync operations
+VECTOR_SYNC_SCOPES = [
+    "notes:read",
+    "files:read",
+    "deck:read",
+    # "news:read",  # News app may not be installed
+]
+
+
+class NotProvisionedError(Exception):
+    """User has not provisioned offline access or has revoked it."""
+
+    pass
+
+
+@dataclass
+class UserSyncState:
+    """State for a single user's scanner task."""
+
+    user_id: str
+    cancel_scope: anyio.CancelScope
+    started_at: float = field(default_factory=time.time)
+
+
+async def get_user_client(
+    user_id: str,
+    token_broker: "TokenBrokerService",
+    nextcloud_host: str,
+) -> NextcloudClient:
+    """Get an authenticated NextcloudClient for a user.
+
+    Args:
+        user_id: User identifier
+        token_broker: Token broker for obtaining access tokens
+        nextcloud_host: Nextcloud base URL
+
+    Returns:
+        Authenticated NextcloudClient
+
+    Raises:
+        NotProvisionedError: If user has not provisioned offline access
+    """
+    token = await token_broker.get_background_token(user_id, VECTOR_SYNC_SCOPES)
+    if not token:
+        raise NotProvisionedError(f"User {user_id} has not provisioned offline access")
+
+    return NextcloudClient.from_token(
+        base_url=nextcloud_host,
+        token=token,
+        username=user_id,
+    )
+
+
+async def user_scanner_task(
+    user_id: str,
+    send_stream: MemoryObjectSendStream[DocumentTask],
+    shutdown_event: anyio.Event,
+    wake_event: anyio.Event,
+    token_broker: "TokenBrokerService",
+    nextcloud_host: str,
+    *,
+    task_status: TaskStatus = anyio.TASK_STATUS_IGNORED,
+) -> None:
+    """Scanner task for a single user in OAuth mode.
+
+    Gets a fresh token at the start of each scan cycle.
+
+    Args:
+        user_id: User to scan
+        send_stream: Stream to send changed documents to processors
+        shutdown_event: Event signaling shutdown
+        wake_event: Event to trigger immediate scan
+        token_broker: Token broker for obtaining access tokens
+        nextcloud_host: Nextcloud base URL
+        task_status: Status object for signaling task readiness
+    """
+    logger.info(f"[OAuth] Scanner started for user: {user_id}")
+    settings = get_settings()
+
+    task_status.started()
+
+    while not shutdown_event.is_set():
+        nc_client = None
+        try:
+            # Get fresh token for this scan cycle
+            nc_client = await get_user_client(user_id, token_broker, nextcloud_host)
+
+            # Scan user's documents
+            await scan_user_documents(
+                user_id=user_id,
+                send_stream=send_stream,
+                nc_client=nc_client,
+            )
+
+        except NotProvisionedError:
+            logger.warning(
+                f"[OAuth] User {user_id} no longer provisioned, stopping scanner"
+            )
+            break
+
+        except Exception as e:
+            logger.error(f"[OAuth] Scanner error for {user_id}: {e}", exc_info=True)
+
+        finally:
+            if nc_client:
+                await nc_client.close()
+
+        # Sleep until next interval or wake event
+        try:
+            with anyio.move_on_after(settings.vector_sync_scan_interval):
+                await wake_event.wait()
+        except anyio.get_cancelled_exc_class():
+            break
+
+    logger.info(f"[OAuth] Scanner stopped for user: {user_id}")
+
+
+async def oauth_processor_task(
+    worker_id: int,
+    receive_stream: MemoryObjectReceiveStream[DocumentTask],
+    shutdown_event: anyio.Event,
+    token_broker: "TokenBrokerService",
+    nextcloud_host: str,
+    *,
+    task_status: TaskStatus = anyio.TASK_STATUS_IGNORED,
+) -> None:
+    """Processor task for OAuth mode.
+
+    Handles documents from any user by fetching tokens on-demand.
+
+    Args:
+        worker_id: Worker identifier for logging
+        receive_stream: Stream to receive documents from
+        shutdown_event: Event signaling shutdown
+        token_broker: Token broker for obtaining access tokens
+        nextcloud_host: Nextcloud base URL
+        task_status: Status object for signaling task readiness
+    """
+    from nextcloud_mcp_server.vector.processor import process_document
+
+    logger.info(f"[OAuth] Processor {worker_id} started")
+    task_status.started()
+
+    while not shutdown_event.is_set():
+        doc_task = None
+        nc_client = None
+        try:
+            # Get document with timeout
+            with anyio.fail_after(1.0):
+                doc_task = await receive_stream.receive()
+
+            # Get token for THIS document's user
+            nc_client = await get_user_client(
+                doc_task.user_id, token_broker, nextcloud_host
+            )
+
+            # Process the document
+            await process_document(doc_task, nc_client)
+
+        except TimeoutError:
+            continue
+
+        except anyio.EndOfStream:
+            logger.info(f"[OAuth] Processor {worker_id}: Stream closed, exiting")
+            break
+
+        except NotProvisionedError:
+            if doc_task:
+                logger.warning(
+                    f"[OAuth] User {doc_task.user_id} not provisioned, "
+                    f"skipping {doc_task.doc_type}_{doc_task.doc_id}"
+                )
+            continue
+
+        except Exception as e:
+            if doc_task:
+                logger.error(
+                    f"[OAuth] Processor {worker_id} error processing "
+                    f"{doc_task.doc_type}_{doc_task.doc_id}: {e}",
+                    exc_info=True,
+                )
+            else:
+                logger.error(f"[OAuth] Processor {worker_id} error: {e}", exc_info=True)
+
+        finally:
+            if nc_client:
+                await nc_client.close()
+
+    logger.info(f"[OAuth] Processor {worker_id} stopped")
+
+
+async def _run_user_scanner_with_scope(
+    user_id: str,
+    cancel_scope: anyio.CancelScope,
+    send_stream: MemoryObjectSendStream[DocumentTask],
+    shutdown_event: anyio.Event,
+    wake_event: anyio.Event,
+    token_broker: "TokenBrokerService",
+    nextcloud_host: str,
+    user_states: dict[str, UserSyncState],
+) -> None:
+    """Wrapper to run scanner with cancellation scope.
+
+    Cleans up user state on exit.
+    """
+    cloned_stream = send_stream.clone()
+    try:
+        with cancel_scope:
+            await user_scanner_task(
+                user_id=user_id,
+                send_stream=cloned_stream,
+                shutdown_event=shutdown_event,
+                wake_event=wake_event,
+                token_broker=token_broker,
+                nextcloud_host=nextcloud_host,
+            )
+    finally:
+        # Clean up on exit
+        if user_id in user_states:
+            del user_states[user_id]
+        await cloned_stream.aclose()
+
+
+async def user_manager_task(
+    send_stream: MemoryObjectSendStream[DocumentTask],
+    shutdown_event: anyio.Event,
+    wake_event: anyio.Event,
+    token_broker: "TokenBrokerService",
+    refresh_token_storage: "RefreshTokenStorage",
+    nextcloud_host: str,
+    user_states: dict[str, UserSyncState],
+    tg: TaskGroup,
+    *,
+    task_status: TaskStatus = anyio.TASK_STATUS_IGNORED,
+) -> None:
+    """Supervisor task that manages per-user scanners.
+
+    Periodically polls RefreshTokenStorage to detect:
+    - New users who have provisioned offline access -> start scanner
+    - Users who have revoked access -> cancel their scanner
+
+    Args:
+        send_stream: Stream to send documents to processors
+        shutdown_event: Event signaling shutdown
+        wake_event: Event to wake scanners for immediate scan
+        token_broker: Token broker for obtaining access tokens
+        refresh_token_storage: Storage for refresh tokens
+        nextcloud_host: Nextcloud base URL
+        user_states: Shared dict tracking active user scanners
+        tg: Task group for spawning scanner tasks
+        task_status: Status object for signaling task readiness
+    """
+    settings = get_settings()
+    poll_interval = settings.vector_sync_user_poll_interval
+
+    logger.info(f"[OAuth] User manager started (poll interval: {poll_interval}s)")
+    task_status.started()
+
+    while not shutdown_event.is_set():
+        try:
+            # Get current provisioned users
+            provisioned_users = set(await refresh_token_storage.get_all_user_ids())
+            active_users = set(user_states.keys())
+
+            # Start scanners for new users
+            new_users = provisioned_users - active_users
+            for user_id in new_users:
+                logger.info(
+                    f"[OAuth] Starting scanner for newly provisioned user: {user_id}"
+                )
+                cancel_scope = anyio.CancelScope()
+                user_states[user_id] = UserSyncState(
+                    user_id=user_id,
+                    cancel_scope=cancel_scope,
+                )
+
+                # Start scanner in task group
+                tg.start_soon(
+                    _run_user_scanner_with_scope,
+                    user_id,
+                    cancel_scope,
+                    send_stream,
+                    shutdown_event,
+                    wake_event,
+                    token_broker,
+                    nextcloud_host,
+                    user_states,
+                )
+
+            # Cancel scanners for revoked users
+            revoked_users = active_users - provisioned_users
+            for user_id in revoked_users:
+                logger.info(f"[OAuth] Stopping scanner for revoked user: {user_id}")
+                state = user_states.get(user_id)
+                if state:
+                    state.cancel_scope.cancel()
+                    # Note: state will be removed by _run_user_scanner_with_scope on exit
+
+            if new_users:
+                logger.info(f"[OAuth] Started {len(new_users)} new scanner(s)")
+            if revoked_users:
+                logger.info(f"[OAuth] Stopped {len(revoked_users)} scanner(s)")
+
+        except Exception as e:
+            logger.error(f"[OAuth] User manager error: {e}", exc_info=True)
+
+        # Sleep until next poll
+        try:
+            with anyio.move_on_after(poll_interval):
+                await shutdown_event.wait()
+        except anyio.get_cancelled_exc_class():
+            break
+
+    # Cancel all remaining scanners on shutdown
+    logger.info(
+        f"[OAuth] User manager shutting down, cancelling {len(user_states)} scanner(s)"
+    )
+    for state in list(user_states.values()):
+        state.cancel_scope.cancel()
+
+    logger.info("[OAuth] User manager stopped")

nextcloud_mcp_server/vector/processor.py

@@ -6,6 +6,7 @@ Processes documents from stream: fetches content, generates embeddings, stores i
 import logging
 import time
 import uuid
+from typing import Any, cast
 
 import anyio
 from anyio.abc import TaskStatus
@@ -272,6 +273,141 @@ async def _index_document(
             file_path = None  # Notes don't have file paths
             content_bytes = None  # Notes don't have binary content
             content_type = None
+        elif doc_task.doc_type == "news_item":
+            from nextcloud_mcp_server.vector.html_processor import html_to_markdown
+
+            item = await nc_client.news.get_item(int(doc_task.doc_id))
+            # Convert HTML body to Markdown for better embedding
+            body_markdown = html_to_markdown(item.get("body", ""))
+            # Build content: title + URL + body
+            item_title = item.get("title", "")
+            item_url = item.get("url", "")
+            feed_title = item.get("feedTitle", "")
+
+            # Structure content for embedding
+            content_parts = [item_title]
+            if feed_title:
+                content_parts.append(f"Source: {feed_title}")
+            if item_url:
+                content_parts.append(f"URL: {item_url}")
+            content_parts.append("")  # Blank line
+            content_parts.append(body_markdown)
+            content = "\n".join(content_parts)
+
+            title = item_title
+            etag = item.get("guidHash", "")
+            # Store news-specific metadata for later use in payload
+            file_metadata = {
+                "feed_id": item.get("feedId"),
+                "feed_title": feed_title,
+                "author": item.get("author"),
+                "pub_date": item.get("pubDate"),
+                "starred": item.get("starred", False),
+                "unread": item.get("unread", True),
+                "url": item_url,
+                "guid_hash": item.get("guidHash"),
+                "enclosure_link": item.get("enclosureLink"),
+                "enclosure_mime": item.get("enclosureMime"),
+            }
+            file_path = None
+            content_bytes = None
+            content_type = None
+        elif doc_task.doc_type == "deck_card":
+            # Fetch card from Deck API
+            # Use metadata from scanner if available (O(1) lookup)
+            # Otherwise fall back to iteration (legacy data)
+            card = None
+            board = None
+            stack = None
+
+            if (
+                doc_task.metadata
+                and "board_id" in doc_task.metadata
+                and "stack_id" in doc_task.metadata
+            ):
+                # Fast path: Direct lookup with known board_id/stack_id
+                board_id = doc_task.metadata["board_id"]
+                stack_id = doc_task.metadata["stack_id"]
+                try:
+                    card = await nc_client.deck.get_card(
+                        board_id=int(board_id),
+                        stack_id=int(stack_id),
+                        card_id=int(doc_task.doc_id),
+                    )
+                    # Fetch board and stack info for metadata
+                    boards = await nc_client.deck.get_boards()
+                    for b in boards:
+                        if b.id == int(board_id):
+                            board = b
+                            stacks = await nc_client.deck.get_stacks(b.id)
+                            for s in stacks:
+                                if s.id == int(stack_id):
+                                    stack = s
+                                    break
+                            break
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to fetch card with metadata (board_id={board_id}, stack_id={stack_id}, card_id={doc_task.doc_id}): {e}, falling back to iteration"
+                    )
+
+            # Fallback: Iterate through all boards/stacks (for legacy data or if fast path failed)
+            if card is None:
+                boards = await nc_client.deck.get_boards()
+                card_found = False
+
+                for b in boards:
+                    if card_found:
+                        break
+                    # Skip deleted boards (soft delete: deletedAt > 0)
+                    if b.deletedAt > 0:
+                        continue
+                    stacks = await nc_client.deck.get_stacks(b.id)
+                    for s in stacks:
+                        if card_found:
+                            break
+                        if s.cards:
+                            for c in s.cards:
+                                if c.id == int(doc_task.doc_id):
+                                    card = c
+                                    board = b
+                                    stack = s
+                                    card_found = True
+                                    break
+
+                if not card_found:
+                    raise ValueError(
+                        f"Deck card {doc_task.doc_id} not found in any board/stack"
+                    )
+
+            # Type narrowing: card, board, stack are all set if we reach here
+            assert card is not None
+            assert board is not None
+            assert stack is not None
+
+            # Build content from card title and description
+            content_parts = [card.title]
+            if card.description:
+                content_parts.append(card.description)
+            content = "\n\n".join(content_parts)
+            title = card.title
+
+            # Store deck-specific metadata
+            file_metadata = {
+                "board_id": board.id,
+                "board_title": board.title,
+                "stack_id": stack.id,
+                "stack_title": stack.title,
+                "card_type": card.type,
+                "duedate": (card.duedate.isoformat() if card.duedate else None),
+                "archived": card.archived,
+                "owner": (
+                    card.owner.uid if hasattr(card.owner, "uid") else str(card.owner)
+                ),
+            }
+            etag = card.etag or ""
+            file_path = None
+            content_bytes = None
+            content_type = None
         elif doc_task.doc_type == "file":
             # For files, doc_id is now the numeric file ID, file_path comes from DocumentTask
             if not doc_task.file_path:
@@ -358,15 +494,18 @@ async def _index_document(
         chunks = await chunker.chunk_text(content)
 
     # Assign page numbers to chunks if page boundaries are available (PDFs)
-    if doc_task.doc_type == "file" and "page_boundaries" in file_metadata:
+    page_boundaries = file_metadata.get("page_boundaries")
+    if doc_task.doc_type == "file" and page_boundaries is not None:
+        # Type narrowing: page_boundaries is guaranteed to be list[dict] here
+        page_boundaries_list = cast(list[dict[str, Any]], page_boundaries)
         with trace_operation(
             "vector_sync.assign_page_numbers",
             attributes={
                 "vector_sync.chunk_count": len(chunks),
-                "vector_sync.page_count": len(file_metadata["page_boundaries"]),
+                "vector_sync.page_count": len(page_boundaries_list),
             },
         ):
-            assign_page_numbers(chunks, file_metadata["page_boundaries"])
+            assign_page_numbers(chunks, page_boundaries_list)
 
             # Diagnostic: Verify page number assignment
             assigned_count = sum(1 for c in chunks if c.page_number is not None)
@@ -389,8 +528,8 @@ async def _index_document(
                     f"Text length: {len(content)}, "
                     f"Chunks: {len(chunks)}, "
                     f"Chunk offset range: [{chunks[0].start_offset}:{chunks[-1].end_offset}], "
-                    f"Page boundaries: {len(file_metadata['page_boundaries'])} pages, "
-                    f"First boundary: {file_metadata['page_boundaries'][0] if file_metadata['page_boundaries'] else 'None'}"
+                    f"Page boundaries: {len(page_boundaries_list)} pages, "
+                    f"First boundary: {page_boundaries_list[0] if page_boundaries_list else 'None'}"
                 )
 
     # Extract chunk texts for embedding
@@ -464,6 +603,9 @@ async def _index_document(
                 logger.warning("No page boundaries available, skipping highlighting")
                 return
 
+            # Type narrowing: page_boundaries is guaranteed to be list[dict] here
+            page_boundaries_list = cast(list[dict[str, Any]], page_boundaries)
+
             logger.info(
                 f"Batch generating highlighted page images for {len(chunk_data)} PDF chunks"
             )
@@ -474,7 +616,7 @@ async def _index_document(
                 lambda: PDFHighlighter.highlight_chunks_batch(
                     pdf_bytes=content_bytes,
                     chunks=chunk_data,
-                    page_boundaries=page_boundaries,
+                    page_boundaries=page_boundaries_list,
                     full_text=content,
                     color="yellow",
                     zoom=2.0,
@@ -566,6 +708,37 @@ async def _index_document(
                         if doc_task.doc_type == "file"
                         else {}
                     ),
+                    # News item-specific metadata
+                    **(
+                        {
+                            "feed_id": file_metadata.get("feed_id"),
+                            "feed_title": file_metadata.get("feed_title"),
+                            "author": file_metadata.get("author"),
+                            "pub_date": file_metadata.get("pub_date"),
+                            "starred": file_metadata.get("starred"),
+                            "unread": file_metadata.get("unread"),
+                            "url": file_metadata.get("url"),
+                            "guid_hash": file_metadata.get("guid_hash"),
+                            "enclosure_link": file_metadata.get("enclosure_link"),
+                            "enclosure_mime": file_metadata.get("enclosure_mime"),
+                        }
+                        if doc_task.doc_type == "news_item"
+                        else {}
+                    ),
+                    # Deck card-specific metadata
+                    **(
+                        {
+                            "board_id": file_metadata.get("board_id"),
+                            "board_title": file_metadata.get("board_title"),
+                            "stack_id": file_metadata.get("stack_id"),
+                            "stack_title": file_metadata.get("stack_title"),
+                            "card_type": file_metadata.get("card_type"),
+                            "duedate": file_metadata.get("duedate"),
+                            "owner": file_metadata.get("owner"),
+                        }
+                        if doc_task.doc_type == "deck_card"
+                        else {}
+                    ),
                     # Highlighted page image (PDF only)
                     **(
                         {

nextcloud_mcp_server/vector/qdrant_client.py

@@ -89,6 +89,8 @@ async def get_qdrant_client() -> AsyncQdrantClient:
             if isinstance(vectors, dict):
                 actual_dimension = vectors["dense"].size
             else:
+                # Type narrowing: vectors must be VectorParams if not dict
+                assert isinstance(vectors, VectorParams)
                 actual_dimension = vectors.size
 
             # Validate dimension matches

nextcloud_mcp_server/vector/scanner.py

@@ -36,6 +36,9 @@ class DocumentTask:
     operation: str  # "index" or "delete"
     modified_at: int
     file_path: str | None = None  # File path for files (when doc_id is file_id)
+    metadata: dict[str, int | str] | None = (
+        None  # Additional metadata (e.g., board_id/stack_id for deck_card)
+    )
 
 
 # Track documents potentially deleted (grace period before actual deletion)
@@ -79,9 +82,11 @@ async def get_last_indexed_timestamp(user_id: str) -> int | None:
 
         if scroll_result[0]:
             timestamps = [
-                point.payload.get("indexed_at", 0) for point in scroll_result[0]
+                point.payload.get("indexed_at", 0)
+                for point in scroll_result[0]
+                if point.payload is not None
             ]
-            max_timestamp = max(timestamps)
+            max_timestamp = max(timestamps) if timestamps else 0
             logger.info(
                 f"Max indexed_at: {max_timestamp}, timestamps sample: {timestamps[:3]}"
             )
@@ -206,7 +211,11 @@ async def scan_user_documents(
                 limit=10000,
             )
 
-            indexed_doc_ids = {point.payload["doc_id"] for point in scroll_result[0]}
+            indexed_doc_ids = {
+                point.payload["doc_id"]
+                for point in (scroll_result[0] or [])
+                if point.payload is not None
+            }
 
             logger.debug(f"Found {len(indexed_doc_ids)} indexed documents in Qdrant")
 
@@ -376,7 +385,9 @@ async def scan_user_documents(
             )
 
             indexed_file_ids = {
-                point.payload["doc_id"] for point in file_scroll_result[0]
+                point.payload["doc_id"]
+                for point in (file_scroll_result[0] or [])
+                if point.payload is not None
             }
 
             logger.debug(f"Found {len(indexed_file_ids)} indexed files in Qdrant")
@@ -544,9 +555,419 @@ async def scan_user_documents(
 
         queued += file_queued
 
+        # Scan News items (starred + unread)
+        news_queued = 0
+        try:
+            news_queued = await scan_news_items(
+                user_id=user_id,
+                send_stream=send_stream,
+                nc_client=nc_client,
+                initial_sync=initial_sync,
+                scan_id=scan_id,
+            )
+            queued += news_queued
+        except Exception as e:
+            logger.warning(f"Failed to scan news items for {user_id}: {e}")
+
+        # Scan Deck cards
+        deck_queued = 0
+        try:
+            deck_queued = await scan_deck_cards(
+                user_id=user_id,
+                send_stream=send_stream,
+                nc_client=nc_client,
+                initial_sync=initial_sync,
+                scan_id=scan_id,
+            )
+            queued += deck_queued
+        except Exception as e:
+            logger.warning(f"Failed to scan deck cards for {user_id}: {e}")
+
         if queued > 0:
             logger.info(
-                f"Sent {queued} documents ({file_queued} files) for incremental sync: {user_id}"
+                f"Sent {queued} documents ({file_queued} files, {news_queued} news items, {deck_queued} deck cards) for incremental sync: {user_id}"
             )
         else:
             logger.debug(f"No changes detected for {user_id}")
+
+
+async def scan_news_items(
+    user_id: str,
+    send_stream: MemoryObjectSendStream[DocumentTask],
+    nc_client: NextcloudClient,
+    initial_sync: bool,
+    scan_id: int,
+) -> int:
+    """
+    Scan user's News items and queue changed items for indexing.
+
+    Indexes all items from the user's feeds. The News app's auto-purge
+    feature (default: 200 items per feed) naturally limits the total
+    number of items, making explicit filtering unnecessary.
+
+    Args:
+        user_id: User to scan
+        send_stream: Stream to send changed documents to processors
+        nc_client: Authenticated Nextcloud client
+        initial_sync: If True, send all documents (first-time sync)
+        scan_id: Scan identifier for logging
+
+    Returns:
+        Number of items queued for processing
+    """
+    from nextcloud_mcp_server.client.news import NewsItemType
+
+    settings = get_settings()
+    queued = 0
+
+    # Get indexed news item IDs from Qdrant (for deletion tracking)
+    indexed_item_ids: set[str] = set()
+    if not initial_sync:
+        qdrant_client = await get_qdrant_client()
+        scroll_result = await qdrant_client.scroll(
+            collection_name=settings.get_collection_name(),
+            scroll_filter=Filter(
+                must=[
+                    FieldCondition(key="user_id", match=MatchValue(value=user_id)),
+                    FieldCondition(key="doc_type", match=MatchValue(value="news_item")),
+                ]
+            ),
+            with_payload=["doc_id"],
+            with_vectors=False,
+            limit=10000,
+        )
+        indexed_item_ids = {
+            point.payload["doc_id"]
+            for point in (scroll_result[0] or [])
+            if point.payload is not None
+        }
+        logger.debug(f"Found {len(indexed_item_ids)} indexed news items in Qdrant")
+
+    # Fetch all items (News app caps at ~200 per feed via auto-purge)
+    all_items = await nc_client.news.get_items(
+        batch_size=-1,
+        type_=NewsItemType.ALL,
+        get_read=True,
+    )
+    logger.debug(f"[SCAN-{scan_id}] Found {len(all_items)} news items")
+
+    item_count = len(all_items)
+    nextcloud_item_ids: set[str] = set()
+
+    for item in all_items:
+        doc_id = str(item["id"])
+        nextcloud_item_ids.add(doc_id)
+
+        # Use lastModified timestamp (microseconds in News API)
+        modified_at = item.get("lastModified", 0)
+        # Convert to seconds if needed (News API uses microseconds)
+        if modified_at > 10000000000:  # > year 2286 in seconds
+            modified_at = modified_at // 1000000
+
+        if initial_sync:
+            # Send everything on first sync - write placeholder first
+            await write_placeholder_point(
+                doc_id=doc_id,
+                doc_type="news_item",
+                user_id=user_id,
+                modified_at=modified_at,
+            )
+            await send_stream.send(
+                DocumentTask(
+                    user_id=user_id,
+                    doc_id=doc_id,
+                    doc_type="news_item",
+                    operation="index",
+                    modified_at=modified_at,
+                )
+            )
+            queued += 1
+        else:
+            # Incremental sync: check if item exists and compare modified_at
+            doc_key = (user_id, doc_id)
+            if doc_key in _potentially_deleted:
+                logger.debug(
+                    f"News item {doc_id} reappeared, removing from deletion grace period"
+                )
+                del _potentially_deleted[doc_key]
+
+            # Query Qdrant for existing entry
+            existing_metadata = await query_document_metadata(
+                doc_id=doc_id, doc_type="news_item", user_id=user_id
+            )
+
+            needs_indexing = False
+            if existing_metadata is None:
+                needs_indexing = True
+            elif existing_metadata.get("modified_at", 0) < modified_at:
+                needs_indexing = True
+            elif existing_metadata.get("is_placeholder", False):
+                queued_at = existing_metadata.get("queued_at", 0)
+                placeholder_age = time.time() - queued_at
+                stale_threshold = settings.vector_sync_scan_interval * 5
+                if placeholder_age > stale_threshold:
+                    logger.debug(
+                        f"Found stale placeholder for news item {doc_id} "
+                        f"(age={placeholder_age:.1f}s), requeuing"
+                    )
+                    needs_indexing = True
+
+            if needs_indexing:
+                await write_placeholder_point(
+                    doc_id=doc_id,
+                    doc_type="news_item",
+                    user_id=user_id,
+                    modified_at=modified_at,
+                )
+                await send_stream.send(
+                    DocumentTask(
+                        user_id=user_id,
+                        doc_id=doc_id,
+                        doc_type="news_item",
+                        operation="index",
+                        modified_at=modified_at,
+                    )
+                )
+                queued += 1
+
+    logger.info(
+        f"[SCAN-{scan_id}] Found {item_count} news items (starred+unread) for {user_id}"
+    )
+    record_vector_sync_scan(item_count)
+
+    # Check for deleted items (not initial sync)
+    # Items become "deleted" when they are no longer starred AND become read
+    if not initial_sync:
+        grace_period = settings.vector_sync_scan_interval * 1.5
+        current_time = time.time()
+
+        for doc_id in indexed_item_ids:
+            if doc_id not in nextcloud_item_ids:
+                doc_key = (user_id, doc_id)
+
+                if doc_key in _potentially_deleted:
+                    first_missing_time = _potentially_deleted[doc_key]
+                    time_missing = current_time - first_missing_time
+
+                    if time_missing >= grace_period:
+                        logger.info(
+                            f"News item {doc_id} missing for {time_missing:.1f}s "
+                            f"(>{grace_period:.1f}s grace period), sending deletion"
+                        )
+                        await send_stream.send(
+                            DocumentTask(
+                                user_id=user_id,
+                                doc_id=doc_id,
+                                doc_type="news_item",
+                                operation="delete",
+                                modified_at=0,
+                            )
+                        )
+                        queued += 1
+                        del _potentially_deleted[doc_key]
+                else:
+                    logger.debug(
+                        f"News item {doc_id} missing for first time, starting grace period"
+                    )
+                    _potentially_deleted[doc_key] = current_time
+
+    return queued
+
+
+async def scan_deck_cards(
+    user_id: str,
+    send_stream: MemoryObjectSendStream[DocumentTask],
+    nc_client: NextcloudClient,
+    initial_sync: bool,
+    scan_id: int,
+) -> int:
+    """
+    Scan user's Deck cards and queue changed cards for indexing.
+
+    Indexes cards from all non-archived boards and stacks.
+
+    Args:
+        user_id: User to scan
+        send_stream: Stream to send changed documents to processors
+        nc_client: Authenticated Nextcloud client
+        initial_sync: If True, send all documents (first-time sync)
+        scan_id: Scan identifier for logging
+
+    Returns:
+        Number of cards queued for processing
+    """
+    settings = get_settings()
+    queued = 0
+
+    # Get indexed deck card IDs from Qdrant (for deletion tracking)
+    indexed_card_ids: set[str] = set()
+    if not initial_sync:
+        qdrant_client = await get_qdrant_client()
+        scroll_result = await qdrant_client.scroll(
+            collection_name=settings.get_collection_name(),
+            scroll_filter=Filter(
+                must=[
+                    FieldCondition(key="user_id", match=MatchValue(value=user_id)),
+                    FieldCondition(key="doc_type", match=MatchValue(value="deck_card")),
+                ]
+            ),
+            with_payload=["doc_id"],
+            with_vectors=False,
+            limit=10000,
+        )
+        indexed_card_ids = {
+            point.payload["doc_id"]
+            for point in (scroll_result[0] or [])
+            if point.payload is not None
+        }
+        logger.debug(f"Found {len(indexed_card_ids)} indexed deck cards in Qdrant")
+
+    # Fetch all boards
+    boards = await nc_client.deck.get_boards()
+    logger.debug(f"[SCAN-{scan_id}] Found {len(boards)} deck boards")
+
+    card_count = 0
+    nextcloud_card_ids: set[str] = set()
+
+    # Iterate through boards
+    for board in boards:
+        # Skip archived boards
+        if board.archived:
+            continue
+
+        # Skip deleted boards (soft delete: deletedAt > 0)
+        if board.deletedAt > 0:
+            logger.debug(f"[SCAN-{scan_id}] Skipping deleted board {board.id}")
+            continue
+
+        # Get stacks for this board
+        stacks = await nc_client.deck.get_stacks(board.id)
+
+        # Iterate through stacks
+        for stack in stacks:
+            # Skip if stack has no cards
+            if not stack.cards:
+                continue
+
+            # Iterate through cards in stack
+            for card in stack.cards:
+                # Skip archived cards
+                if card.archived:
+                    continue
+
+                card_count += 1
+                doc_id = str(card.id)
+                nextcloud_card_ids.add(doc_id)
+
+                # Use lastModified timestamp if available
+                modified_at = card.lastModified or 0
+
+                if initial_sync:
+                    # Send everything on first sync - write placeholder first
+                    await write_placeholder_point(
+                        doc_id=doc_id,
+                        doc_type="deck_card",
+                        user_id=user_id,
+                        modified_at=modified_at,
+                    )
+                    await send_stream.send(
+                        DocumentTask(
+                            user_id=user_id,
+                            doc_id=doc_id,
+                            doc_type="deck_card",
+                            operation="index",
+                            modified_at=modified_at,
+                            metadata={"board_id": board.id, "stack_id": stack.id},
+                        )
+                    )
+                    queued += 1
+                else:
+                    # Incremental sync: check if card exists and compare modified_at
+                    doc_key = (user_id, doc_id)
+                    if doc_key in _potentially_deleted:
+                        logger.debug(
+                            f"Deck card {doc_id} reappeared, removing from deletion grace period"
+                        )
+                        del _potentially_deleted[doc_key]
+
+                    # Query Qdrant for existing entry
+                    existing_metadata = await query_document_metadata(
+                        doc_id=doc_id, doc_type="deck_card", user_id=user_id
+                    )
+
+                    needs_indexing = False
+                    if existing_metadata is None:
+                        needs_indexing = True
+                    elif existing_metadata.get("modified_at", 0) < modified_at:
+                        needs_indexing = True
+                    elif existing_metadata.get("is_placeholder", False):
+                        queued_at = existing_metadata.get("queued_at", 0)
+                        placeholder_age = time.time() - queued_at
+                        stale_threshold = settings.vector_sync_scan_interval * 5
+                        if placeholder_age > stale_threshold:
+                            logger.debug(
+                                f"Found stale placeholder for deck card {doc_id} "
+                                f"(age={placeholder_age:.1f}s), requeuing"
+                            )
+                            needs_indexing = True
+
+                    if needs_indexing:
+                        await write_placeholder_point(
+                            doc_id=doc_id,
+                            doc_type="deck_card",
+                            user_id=user_id,
+                            modified_at=modified_at,
+                        )
+                        await send_stream.send(
+                            DocumentTask(
+                                user_id=user_id,
+                                doc_id=doc_id,
+                                doc_type="deck_card",
+                                operation="index",
+                                modified_at=modified_at,
+                                metadata={"board_id": board.id, "stack_id": stack.id},
+                            )
+                        )
+                        queued += 1
+
+    logger.info(
+        f"[SCAN-{scan_id}] Found {card_count} deck cards (non-archived) for {user_id}"
+    )
+    record_vector_sync_scan(card_count)
+
+    # Check for deleted cards (not initial sync)
+    if not initial_sync:
+        grace_period = settings.vector_sync_scan_interval * 1.5
+        current_time = time.time()
+
+        for doc_id in indexed_card_ids:
+            if doc_id not in nextcloud_card_ids:
+                doc_key = (user_id, doc_id)
+
+                if doc_key in _potentially_deleted:
+                    first_missing_time = _potentially_deleted[doc_key]
+                    time_missing = current_time - first_missing_time
+
+                    if time_missing >= grace_period:
+                        logger.info(
+                            f"Deck card {doc_id} missing for {time_missing:.1f}s "
+                            f"(>{grace_period:.1f}s grace period), sending deletion"
+                        )
+                        await send_stream.send(
+                            DocumentTask(
+                                user_id=user_id,
+                                doc_id=doc_id,
+                                doc_type="deck_card",
+                                operation="delete",
+                                modified_at=0,
+                            )
+                        )
+                        queued += 1
+                        del _potentially_deleted[doc_key]
+                else:
+                    logger.debug(
+                        f"Deck card {doc_id} missing for first time, starting grace period"
+                    )
+                    _potentially_deleted[doc_key] = current_time
+
+    return queued

nextcloud_mcp_server/vector/visualization.py

@@ -0,0 +1,190 @@
+"""Shared visualization utilities for PCA coordinate computation.
+
+Extracts the PCA coordinate computation logic used by both:
+- viz_routes.py (session-based auth)
+- management.py (OAuth bearer token auth)
+
+Both endpoints need to compute 3D PCA coordinates for search results,
+so this module provides the shared implementation.
+"""
+
+import logging
+from typing import Any
+
+import anyio.to_thread
+import numpy as np
+
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.vector.pca import PCA
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+logger = logging.getLogger(__name__)
+
+
+async def compute_pca_coordinates(
+    search_results: list[Any],
+    query_embedding: np.ndarray | list[float],
+) -> dict[str, Any]:
+    """Compute PCA 3D coordinates for search results visualization.
+
+    This is the shared implementation used by both viz_routes.py and
+    the management API. It retrieves vectors from Qdrant and applies
+    PCA dimensionality reduction.
+
+    Args:
+        search_results: List of SearchResult objects with point_id
+        query_embedding: The query embedding vector
+
+    Returns:
+        Dict with:
+            - coordinates_3d: List of [x, y, z] for each result
+            - query_coords: [x, y, z] for the query point
+            - pca_variance: Dict with pc1, pc2, pc3 explained variance ratios
+    """
+    settings = get_settings()
+
+    # Collect point IDs from search results for batch retrieval
+    point_ids = [r.point_id for r in search_results if r.point_id]
+
+    if len(point_ids) < 2:
+        return {"coordinates_3d": [], "query_coords": []}
+
+    qdrant_client = await get_qdrant_client()
+
+    # Batch retrieve vectors from Qdrant
+    points_response = await qdrant_client.retrieve(
+        collection_name=settings.get_collection_name(),
+        ids=point_ids,
+        with_vectors=["dense"],
+        with_payload=["doc_id", "chunk_start_offset", "chunk_end_offset"],
+    )
+
+    # Build chunk_vectors_map from batch response
+    chunk_vectors_map: dict[tuple[Any, Any, Any], Any] = {}
+    for point in points_response:
+        if point.vector is not None:
+            # Extract dense vector (handle both named and unnamed vectors)
+            if isinstance(point.vector, dict):
+                vector = point.vector.get("dense")
+            else:
+                vector = point.vector
+
+            if vector is not None and point.payload:
+                doc_id = point.payload.get("doc_id")
+                chunk_start = point.payload.get("chunk_start_offset")
+                chunk_end = point.payload.get("chunk_end_offset")
+                chunk_key = (doc_id, chunk_start, chunk_end)
+                chunk_vectors_map[chunk_key] = vector
+
+    if len(chunk_vectors_map) < 2:
+        return {"coordinates_3d": [], "query_coords": []}
+
+    # Detect embedding dimension
+    embedding_dim = None
+    for vector in chunk_vectors_map.values():
+        if vector is not None:
+            embedding_dim = len(vector)
+            break
+
+    if embedding_dim is None:
+        return {"coordinates_3d": [], "query_coords": []}
+
+    logger.info(f"Detected embedding dimension: {embedding_dim}")
+
+    # Build chunk vectors array in search_results order (1:1 mapping)
+    chunk_vectors = []
+    for result in search_results:
+        chunk_key = (result.id, result.chunk_start_offset, result.chunk_end_offset)
+        if chunk_key in chunk_vectors_map:
+            chunk_vectors.append(chunk_vectors_map[chunk_key])
+        else:
+            # Chunk not found in vectors (shouldn't happen)
+            logger.warning(
+                f"Chunk {chunk_key} not found in fetched vectors, using zero vector"
+            )
+            chunk_vectors.append(np.zeros(embedding_dim))
+
+    chunk_vectors = np.array(chunk_vectors)
+
+    # Ensure query_embedding is a numpy array
+    if not isinstance(query_embedding, np.ndarray):
+        query_embedding = np.array(query_embedding)
+
+    # Combine query vector with chunk vectors for PCA
+    # Query will be the last point in the array
+    all_vectors = np.vstack([chunk_vectors, np.array([query_embedding])])
+
+    # Normalize vectors to unit length (L2 normalization)
+    # This is critical because Qdrant uses COSINE distance, which only measures
+    # vector direction (angle), not magnitude. PCA uses Euclidean distance which
+    # considers both direction and magnitude. By normalizing to unit length,
+    # Euclidean distances in PCA space will match cosine distances.
+    norms = np.linalg.norm(all_vectors, axis=1, keepdims=True)
+
+    # Check for zero-norm vectors (can happen with empty/corrupted embeddings)
+    zero_norm_mask = norms[:, 0] < 1e-10
+    if zero_norm_mask.any():
+        zero_indices = np.where(zero_norm_mask)[0]
+        logger.warning(
+            f"Found {zero_norm_mask.sum()} zero-norm vectors at indices "
+            f"{zero_indices.tolist()}. Replacing with small epsilon to avoid "
+            "division by zero."
+        )
+        # Replace zero norms with small epsilon to avoid NaN
+        norms[zero_norm_mask] = 1e-10
+
+    all_vectors_normalized = all_vectors / norms
+    logger.info(
+        f"Normalized vectors: query_norm={norms[-1][0]:.3f}, "
+        f"doc_norm_range=[{norms[:-1].min():.3f}, {norms[:-1].max():.3f}]"
+    )
+
+    # Apply PCA dimensionality reduction (768-dim → 3D)
+    # Run in thread pool to avoid blocking the event loop (CPU-bound)
+    def _compute_pca(vectors: np.ndarray) -> tuple[np.ndarray, PCA]:
+        pca = PCA(n_components=3)
+        coords = pca.fit_transform(vectors)
+        return coords, pca
+
+    coords_3d, pca = await anyio.to_thread.run_sync(
+        lambda: _compute_pca(all_vectors_normalized)
+    )
+
+    # After fit, these attributes are guaranteed to be set
+    assert pca.explained_variance_ratio_ is not None
+
+    # Check for NaN values in PCA output (numerical instability)
+    nan_mask = np.isnan(coords_3d)
+    if nan_mask.any():
+        nan_rows = np.where(nan_mask.any(axis=1))[0]
+        logger.error(
+            f"Found NaN values in PCA output at {len(nan_rows)} points: "
+            f"{nan_rows.tolist()[:10]}. Replacing NaN with 0.0 to prevent "
+            "JSON serialization error."
+        )
+        # Replace NaN with 0 to allow JSON serialization
+        coords_3d = np.nan_to_num(coords_3d, nan=0.0)
+
+    # Split query coords from chunk coords
+    # Round to 2 decimal places for cleaner display
+    query_coords_3d = [round(float(x), 2) for x in coords_3d[-1]]  # Last point is query
+    chunk_coords_3d = coords_3d[:-1]  # All but last are chunks
+
+    logger.info(
+        f"PCA explained variance: PC1={pca.explained_variance_ratio_[0]:.3f}, "
+        f"PC2={pca.explained_variance_ratio_[1]:.3f}, "
+        f"PC3={pca.explained_variance_ratio_[2]:.3f}"
+    )
+
+    # Coordinates already match search_results order (1:1 mapping)
+    result_coords = [[round(float(x), 2) for x in coord] for coord in chunk_coords_3d]
+
+    return {
+        "coordinates_3d": result_coords,
+        "query_coords": query_coords_3d,
+        "pca_variance": {
+            "pc1": float(pca.explained_variance_ratio_[0]),
+            "pc2": float(pca.explained_variance_ratio_[1]),
+            "pc3": float(pca.explained_variance_ratio_[2]),
+        },
+    }

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.48.0"
+version = "0.56.2"
 description = "Model Context Protocol (MCP) server for Nextcloud integration - enables AI assistants to interact with Nextcloud data"
 authors = [
     {name = "Chris Coutinho", email = "chris@coutinho.io"}
@@ -10,7 +10,7 @@ license = {text = "AGPL-3.0-only"}
 requires-python = ">=3.11"
 keywords = ["nextcloud", "mcp", "model-context-protocol", "llm", "ai", "claude", "webdav", "caldav", "carddav"]
 dependencies = [
-    "mcp[cli] (>=1.22,<1.23)",
+    "mcp[cli] (>=1.23,<1.24)",
     "httpx (>=0.28.1,<0.29.0)",
     "pillow (>=10.3.0,<12.0.0)", # Compatible with fastembed
     "icalendar (>=6.0.0,<7.0.0)",
@@ -20,6 +20,7 @@ dependencies = [
     "caldav",
     "pyjwt[crypto]>=2.8.0",
     "aiosqlite>=0.20.0", # Async SQLite for refresh token storage
+    "alembic>=1.14.0", # Database migrations
     "authlib>=1.6.5",
     "qdrant-client>=1.7.0",
     "fastembed>=0.7.3", # BM25 sparse vector embeddings for hybrid search
@@ -36,6 +37,7 @@ dependencies = [
     "python-json-logger>=3.2.0", # Structured JSON logging
     "jinja2>=3.1.6",
     "langchain-text-splitters>=1.0.0",
+    "markdownify>=0.14.1",  # HTML to Markdown conversion for News items
     "pymupdf>=1.26.6",
     "pymupdf4llm>=0.2.2",
     "pymupdf-layout>=1.26.6",
@@ -87,19 +89,29 @@ version_scheme = "pep440"
 version_provider = "uv"
 update_changelog_on_bump = true
 major_version_zero = true
+
+# MCP server version files + Helm appVersion
 version_files = [
-    "charts/nextcloud-mcp-server/Chart.yaml:appVersion",
-    "charts/nextcloud-mcp-server/Chart.yaml:version"
+    "charts/nextcloud-mcp-server/Chart.yaml:^appVersion:",
 ]
+
+# Ignore tags from other components
 ignored_tag_formats = [
-    "nextcloud-mcp-server-*"
+    "nextcloud-mcp-server-*",  # Helm chart tags
+    "astrolabe-v*",            # Astrolabe tags
 ]
 
+# Filter commits by scope (all scopes except helm and astrolabe)
+[tool.commitizen.customize]
+changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm|astrolabe)\\))(\\([^)]+\\))?(!)?:"
+schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm|astrolabe)\\))(\\([^)]+\\))?(!)?:\\s.+"
+
 [tool.ruff.lint]
 extend-select = ["I"]
 
 [tool.uv.sources]
 caldav = { git = "https://github.com/cbcoutinho/caldav", branch = "feature/httpx" }
+qdrant-client = { git = "https://github.com/cbcoutinho/qdrant-client", branch = "fix/fusion-score-threshold" }
 
 [build-system]
 requires = ["uv_build>=0.9.4,<0.10.0"]
@@ -126,7 +138,7 @@ dev = [
 ]
 
 [project.scripts]
-nextcloud-mcp-server = "nextcloud_mcp_server.cli:run"
+nextcloud-mcp-server = "nextcloud_mcp_server.cli:cli"
 smithery-main = "nextcloud_mcp_server.smithery_main:main"
 
 [[tool.uv.index]]

renovate.json

@@ -4,5 +4,11 @@
     "config:best-practices",
     "mergeConfidence:all-badges"
   ],
-  "dependencyDashboard": true
+  "dependencyDashboard": true,
+  "packageRules": [
+    {
+      "matchPackageNames": ["pillow"],
+      "allowedVersions": "<12.0.0"
+    }
+  ]
 }

scripts/bump-astrolabe.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# Bump Astrolabe app version
+set -euo pipefail
+
+# Parse optional --increment flag
+INCREMENT=""
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --increment)
+            INCREMENT="$2"
+            shift 2
+            ;;
+        *)
+            echo "❌ Error: Unknown option: $1" >&2
+            echo "Usage: $0 [--increment PATCH|MINOR|MAJOR]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Validate dependencies
+command -v uv >/dev/null 2>&1 || {
+    echo "❌ Error: uv not found" >&2
+    echo "   Install from https://docs.astral.sh/uv/" >&2
+    exit 1
+}
+
+# Validate Astrolabe directory exists
+if [ ! -d "third_party/astrolabe" ]; then
+    echo "❌ Error: Must run from repository root (third_party/astrolabe not found)" >&2
+    exit 1
+fi
+
+cd third_party/astrolabe
+
+# Validate required files exist
+if [ ! -f "appinfo/info.xml" ]; then
+    echo "❌ Error: appinfo/info.xml not found" >&2
+    exit 1
+fi
+
+if [ ! -f "package.json" ]; then
+    echo "❌ Error: package.json not found" >&2
+    exit 1
+fi
+
+echo "Bumping Astrolabe version..."
+if [ -n "$INCREMENT" ]; then
+    echo "  Forcing $INCREMENT bump"
+fi
+
+# Build commitizen command
+CZ_CMD="uv run cz --config .cz.toml bump --yes"
+if [ -n "$INCREMENT" ]; then
+    CZ_CMD="$CZ_CMD --increment $INCREMENT"
+fi
+
+# Run commitizen bump and capture output
+if ! output=$($CZ_CMD 2>&1); then
+    cd ../..
+    echo "❌ Error: Version bump failed" >&2
+    echo "$output" >&2
+    echo "" >&2
+    echo "Common causes:" >&2
+    echo "  - No commits with scope 'astrolabe' since last version" >&2
+    echo "  - No conventional commits found (use feat(astrolabe):, fix(astrolabe):, etc.)" >&2
+    echo "  - Git working directory not clean" >&2
+    exit 1
+fi
+
+echo "$output"
+echo ""
+echo "✓ Astrolabe version bumped successfully"
+echo "  Updated: appinfo/info.xml, package.json"
+echo "  Tag format: astrolabe-v\${version}"
+echo ""
+echo "Next steps:"
+echo "  cd ../.."
+echo "  git push --follow-tags"
+
+cd ../..

scripts/bump-helm.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Bump Helm chart version
+set -euo pipefail
+
+# Parse optional --increment flag
+INCREMENT=""
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --increment)
+            INCREMENT="$2"
+            shift 2
+            ;;
+        *)
+            echo "❌ Error: Unknown option: $1" >&2
+            echo "Usage: $0 [--increment PATCH|MINOR|MAJOR]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Validate dependencies
+command -v uv >/dev/null 2>&1 || {
+    echo "❌ Error: uv not found" >&2
+    echo "   Install from https://docs.astral.sh/uv/" >&2
+    exit 1
+}
+
+# Validate Helm chart directory exists
+if [ ! -d "charts/nextcloud-mcp-server" ]; then
+    echo "❌ Error: Must run from repository root (charts/ not found)" >&2
+    exit 1
+fi
+
+cd charts/nextcloud-mcp-server
+
+# Validate Chart.yaml exists
+if [ ! -f "Chart.yaml" ]; then
+    echo "❌ Error: Chart.yaml not found" >&2
+    exit 1
+fi
+
+echo "Bumping Helm chart version..."
+if [ -n "$INCREMENT" ]; then
+    echo "  Forcing $INCREMENT bump"
+fi
+
+# Build commitizen command
+CZ_CMD="uv run cz --config .cz.toml bump --yes"
+if [ -n "$INCREMENT" ]; then
+    CZ_CMD="$CZ_CMD --increment $INCREMENT"
+fi
+
+# Run commitizen bump and capture output
+if ! output=$($CZ_CMD 2>&1); then
+    cd ../..
+    echo "❌ Error: Version bump failed" >&2
+    echo "$output" >&2
+    echo "" >&2
+    echo "Common causes:" >&2
+    echo "  - No commits with scope 'helm' since last version" >&2
+    echo "  - No conventional commits found (use feat(helm):, fix(helm):, etc.)" >&2
+    echo "  - Git working directory not clean" >&2
+    exit 1
+fi
+
+echo "$output"
+echo ""
+echo "✓ Helm chart version bumped successfully"
+echo "  Updated: Chart.yaml:version"
+echo "  Tag format: nextcloud-mcp-server-\${version}"
+echo "  Note: appVersion stays at MCP server version"
+echo ""
+echo "Next steps:"
+echo "  cd ../.."
+echo "  git push --follow-tags"
+
+cd ../..

scripts/bump-mcp.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# Bump MCP server version
+set -euo pipefail
+
+# Parse optional --increment flag
+INCREMENT=""
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --increment)
+            INCREMENT="$2"
+            shift 2
+            ;;
+        *)
+            echo "❌ Error: Unknown option: $1" >&2
+            echo "Usage: $0 [--increment PATCH|MINOR|MAJOR]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Validate dependencies
+command -v uv >/dev/null 2>&1 || {
+    echo "❌ Error: uv not found" >&2
+    echo "   Install from https://docs.astral.sh/uv/" >&2
+    exit 1
+}
+
+# Validate we're in the repository root
+if [ ! -f "pyproject.toml" ]; then
+    echo "❌ Error: Must run from repository root (pyproject.toml not found)" >&2
+    exit 1
+fi
+
+echo "Bumping MCP server version..."
+if [ -n "$INCREMENT" ]; then
+    echo "  Forcing $INCREMENT bump"
+fi
+
+# Build commitizen command
+CZ_CMD="uv run cz bump --yes"
+if [ -n "$INCREMENT" ]; then
+    CZ_CMD="$CZ_CMD --increment $INCREMENT"
+fi
+
+# Run commitizen bump and capture output
+if ! output=$($CZ_CMD 2>&1); then
+    echo "❌ Error: Version bump failed" >&2
+    echo "$output" >&2
+    echo "" >&2
+    echo "Common causes:" >&2
+    echo "  - No commits since last version" >&2
+    echo "  - No conventional commits found (use feat:, fix:, etc.)" >&2
+    echo "  - Git working directory not clean" >&2
+    exit 1
+fi
+
+echo "$output"
+echo ""
+echo "✓ MCP server version bumped successfully"
+echo "  Updated: pyproject.toml, Chart.yaml:appVersion"
+echo "  Tag format: v\${version}"
+echo ""
+echo "Next steps:"
+echo "  git push --follow-tags"

scripts/test-commitizen-scopes.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# Test commitizen scope filtering patterns
+set -uo pipefail
+
+echo "Testing commitizen scope filtering patterns..."
+echo
+
+# Regex patterns from configs
+MCP_PATTERN='^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\((?:helm|astrolabe)\))(\([^)]+\))?(!)?:'
+HELM_PATTERN='^(feat|fix|docs|refactor|perf|test|build|ci|chore)\(helm\)(!)?:'
+ASTROLABE_PATTERN='^(feat|fix|docs|refactor|perf|test|build|ci|chore)\(astrolabe\)(!)?:'
+
+test_pattern() {
+    local message="$1"
+    local pattern="$2"
+
+    # Use grep -P for Perl-compatible regex (supports negative lookahead)
+    if echo "$message" | grep -qP "$pattern"; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+run_test() {
+    local message="$1"
+    local expected="$2"
+    local matched_components=()
+
+    # Check which components match
+    if test_pattern "$message" "$MCP_PATTERN"; then
+        matched_components+=("mcp")
+    fi
+    if test_pattern "$message" "$HELM_PATTERN"; then
+        matched_components+=("helm")
+    fi
+    if test_pattern "$message" "$ASTROLABE_PATTERN"; then
+        matched_components+=("astrolabe")
+    fi
+
+    # Convert array to space-separated string, or "none" if empty
+    local matched
+    if [ ${#matched_components[@]} -eq 0 ]; then
+        matched="none"
+    else
+        matched="${matched_components[*]}"
+    fi
+
+    # Validate expectation
+    if [ "$matched" = "$expected" ]; then
+        echo "✓ PASS: '$message'"
+        echo "  → Matched: $matched"
+        return 0
+    else
+        echo "✗ FAIL: '$message'"
+        echo "  → Matched: $matched (expected: $expected)"
+        return 1
+    fi
+}
+
+# Run all test cases
+failed=0
+passed=0
+
+# MCP server commits (any scope except helm/astrolabe)
+run_test "feat: add new feature" "mcp" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "feat(mcp): add API endpoint" "mcp" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "fix(mcp): resolve authentication bug" "mcp" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "docs: update README" "mcp" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "fix(ci): update workflow" "mcp" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "feat(api): add endpoint" "mcp" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "ci: configure GitHub Actions" "mcp" && passed=$((passed+1)) || failed=$((failed+1))
+
+# Helm chart commits
+run_test "feat(helm): add resource limits" "helm" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "fix(helm): correct values schema" "helm" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "docs(helm): update deployment guide" "helm" && passed=$((passed+1)) || failed=$((failed+1))
+
+# Astrolabe commits
+run_test "feat(astrolabe): add dark mode" "astrolabe" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "fix(astrolabe): resolve UI bug" "astrolabe" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "perf(astrolabe): optimize rendering" "astrolabe" && passed=$((passed+1)) || failed=$((failed+1))
+
+# Breaking changes
+run_test "feat(mcp)!: breaking API change" "mcp" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "feat(helm)!: rename values" "helm" && passed=$((passed+1)) || failed=$((failed+1))
+run_test "feat(astrolabe)!: remove deprecated feature" "astrolabe" && passed=$((passed+1)) || failed=$((failed+1))
+
+# Edge cases
+run_test "feat(invalid): test" "mcp" && passed=$((passed+1)) || failed=$((failed+1))  # Any scope except helm/astrolabe → MCP
+run_test "random commit message" "none" && passed=$((passed+1)) || failed=$((failed+1))  # Not conventional commit
+run_test "feat (mcp): space before scope" "none" && passed=$((passed+1)) || failed=$((failed+1))  # Invalid format
+
+# Summary
+echo
+echo "=========================================="
+echo "Results: $passed passed, $failed failed"
+echo "=========================================="
+
+if [ $failed -gt 0 ]; then
+    echo "❌ Some tests failed - scope patterns may need adjustment"
+    exit 1
+else
+    echo "✅ All tests passed - scope patterns working correctly"
+    exit 0
+fi

tests/client/conftest.py

@@ -480,3 +480,222 @@ def create_mock_table_row_ocs_response(
     ocs_response = {"ocs": {"meta": {"status": "ok"}, "data": row_data}}
 
     return create_mock_response(status_code=200, json_data=ocs_response)
+
+
+# ============================================================================
+# News Mock Response Helpers
+# ============================================================================
+
+
+def create_mock_news_folders_response(
+    folders: list[dict] | None = None,
+) -> httpx.Response:
+    """Create a mock response for News folders list.
+
+    Args:
+        folders: List of folder dictionaries. If None, returns empty list.
+
+    Returns:
+        Mock httpx.Response with folders data
+    """
+    if folders is None:
+        folders = []
+
+    return create_mock_response(status_code=200, json_data={"folders": folders})
+
+
+def create_mock_news_folder_response(
+    folder_id: int = 1,
+    name: str = "Test Folder",
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for a News folder.
+
+    Args:
+        folder_id: Folder ID
+        name: Folder name
+        **kwargs: Additional folder fields
+
+    Returns:
+        Mock httpx.Response with folder data
+    """
+    folder_data = {
+        "id": folder_id,
+        "name": name,
+        **kwargs,
+    }
+
+    return create_mock_response(status_code=200, json_data={"folders": [folder_data]})
+
+
+def create_mock_news_feeds_response(
+    feeds: list[dict] | None = None,
+    starred_count: int = 0,
+    newest_item_id: int | None = None,
+) -> httpx.Response:
+    """Create a mock response for News feeds list.
+
+    Args:
+        feeds: List of feed dictionaries. If None, returns empty list.
+        starred_count: Number of starred items
+        newest_item_id: ID of newest item
+
+    Returns:
+        Mock httpx.Response with feeds data
+    """
+    if feeds is None:
+        feeds = []
+
+    data = {
+        "feeds": feeds,
+        "starredCount": starred_count,
+    }
+    if newest_item_id is not None:
+        data["newestItemId"] = newest_item_id
+
+    return create_mock_response(status_code=200, json_data=data)
+
+
+def create_mock_news_feed_response(
+    feed_id: int = 1,
+    url: str = "https://example.com/feed",
+    title: str = "Test Feed",
+    favicon_link: str | None = None,
+    folder_id: int | None = None,
+    unread_count: int = 0,
+    **kwargs,
+) -> httpx.Response:
+    """Create a mock response for a News feed.
+
+    Args:
+        feed_id: Feed ID
+        url: Feed URL
+        title: Feed title
+        favicon_link: Favicon URL
+        folder_id: Parent folder ID
+        unread_count: Number of unread items
+        **kwargs: Additional feed fields
+
+    Returns:
+        Mock httpx.Response with feed data
+    """
+    feed_data = {
+        "id": feed_id,
+        "url": url,
+        "title": title,
+        "faviconLink": favicon_link,
+        "folderId": folder_id,
+        "unreadCount": unread_count,
+        "link": kwargs.get("link", "https://example.com"),
+        "added": kwargs.get("added", 1700000000),
+        "updateErrorCount": kwargs.get("updateErrorCount", 0),
+        "lastUpdateError": kwargs.get("lastUpdateError"),
+        **{
+            k: v
+            for k, v in kwargs.items()
+            if k not in ["link", "added", "updateErrorCount", "lastUpdateError"]
+        },
+    }
+
+    return create_mock_response(status_code=200, json_data={"feeds": [feed_data]})
+
+
+def create_mock_news_items_response(
+    items: list[dict] | None = None,
+) -> httpx.Response:
+    """Create a mock response for News items list.
+
+    Args:
+        items: List of item dictionaries. If None, returns empty list.
+
+    Returns:
+        Mock httpx.Response with items data
+    """
+    if items is None:
+        items = []
+
+    return create_mock_response(status_code=200, json_data={"items": items})
+
+
+def create_mock_news_item(
+    item_id: int = 1,
+    feed_id: int = 1,
+    title: str = "Test Article",
+    body: str = "<p>Test content</p>",
+    url: str = "https://example.com/article",
+    author: str | None = "Test Author",
+    pub_date: int = 1700000000,
+    unread: bool = True,
+    starred: bool = False,
+    **kwargs,
+) -> dict:
+    """Create a mock News item dictionary.
+
+    Args:
+        item_id: Item ID
+        feed_id: Parent feed ID
+        title: Article title
+        body: Article body (HTML)
+        url: Article URL
+        author: Article author
+        pub_date: Publication timestamp (Unix)
+        unread: Whether item is unread
+        starred: Whether item is starred
+        **kwargs: Additional item fields
+
+    Returns:
+        Item dictionary
+    """
+    return {
+        "id": item_id,
+        "feedId": feed_id,
+        "title": title,
+        "body": body,
+        "url": url,
+        "author": author,
+        "pubDate": pub_date,
+        "unread": unread,
+        "starred": starred,
+        "guid": kwargs.get("guid", f"guid-{item_id}"),
+        "guidHash": kwargs.get("guidHash", f"hash-{item_id}"),
+        "lastModified": kwargs.get("lastModified", pub_date * 1000000),
+        "enclosureLink": kwargs.get("enclosureLink"),
+        "enclosureMime": kwargs.get("enclosureMime"),
+        "fingerprint": kwargs.get("fingerprint", f"fp-{item_id}"),
+        "contentHash": kwargs.get("contentHash", f"ch-{item_id}"),
+        **{
+            k: v
+            for k, v in kwargs.items()
+            if k
+            not in [
+                "guid",
+                "guidHash",
+                "lastModified",
+                "enclosureLink",
+                "enclosureMime",
+                "fingerprint",
+                "contentHash",
+            ]
+        },
+    }
+
+
+def create_mock_news_status_response(
+    version: str = "25.0.0",
+    warnings: dict | None = None,
+) -> httpx.Response:
+    """Create a mock response for News status.
+
+    Args:
+        version: News app version
+        warnings: Warning messages
+
+    Returns:
+        Mock httpx.Response with status data
+    """
+    data = {
+        "version": version,
+        "warnings": warnings or {},
+    }
+
+    return create_mock_response(status_code=200, json_data=data)

tests/client/news/test_news_api.py

@@ -0,0 +1,580 @@
+"""Unit tests for NewsClient API methods."""
+
+import logging
+
+import httpx
+import pytest
+
+from nextcloud_mcp_server.client.news import NewsClient, NewsItemType
+from tests.client.conftest import (
+    create_mock_error_response,
+    create_mock_news_feed_response,
+    create_mock_news_feeds_response,
+    create_mock_news_folder_response,
+    create_mock_news_folders_response,
+    create_mock_news_item,
+    create_mock_news_items_response,
+    create_mock_news_status_response,
+    create_mock_response,
+)
+
+logger = logging.getLogger(__name__)
+
+# Mark all tests in this module as unit tests
+pytestmark = pytest.mark.unit
+
+
+# ============================================================================
+# Folder Tests
+# ============================================================================
+
+
+async def test_news_api_get_folders(mocker):
+    """Test that get_folders correctly parses the API response."""
+    mock_response = create_mock_news_folders_response(
+        folders=[
+            {"id": 1, "name": "Tech"},
+            {"id": 2, "name": "News"},
+        ]
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    folders = await client.get_folders()
+
+    assert len(folders) == 2
+    assert folders[0]["id"] == 1
+    assert folders[0]["name"] == "Tech"
+    assert folders[1]["name"] == "News"
+
+    mock_make_request.assert_called_once_with("GET", "/apps/news/api/v1-3/folders")
+
+
+async def test_news_api_create_folder(mocker):
+    """Test that create_folder correctly creates a folder."""
+    mock_response = create_mock_news_folder_response(folder_id=3, name="New Folder")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    folder = await client.create_folder(name="New Folder")
+
+    assert folder["id"] == 3
+    assert folder["name"] == "New Folder"
+
+    mock_make_request.assert_called_once_with(
+        "POST", "/apps/news/api/v1-3/folders", json={"name": "New Folder"}
+    )
+
+
+async def test_news_api_rename_folder(mocker):
+    """Test that rename_folder makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.rename_folder(folder_id=1, name="Renamed")
+
+    mock_make_request.assert_called_once_with(
+        "PUT", "/apps/news/api/v1-3/folders/1", json={"name": "Renamed"}
+    )
+
+
+async def test_news_api_delete_folder(mocker):
+    """Test that delete_folder makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.delete_folder(folder_id=1)
+
+    mock_make_request.assert_called_once_with("DELETE", "/apps/news/api/v1-3/folders/1")
+
+
+# ============================================================================
+# Feed Tests
+# ============================================================================
+
+
+async def test_news_api_get_feeds(mocker):
+    """Test that get_feeds correctly parses the API response."""
+    mock_response = create_mock_news_feeds_response(
+        feeds=[
+            {"id": 1, "url": "https://example.com/feed1", "title": "Feed 1"},
+            {"id": 2, "url": "https://example.com/feed2", "title": "Feed 2"},
+        ],
+        starred_count=5,
+        newest_item_id=100,
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    result = await client.get_feeds()
+
+    assert len(result["feeds"]) == 2
+    assert result["starredCount"] == 5
+    assert result["newestItemId"] == 100
+
+    mock_make_request.assert_called_once_with("GET", "/apps/news/api/v1-3/feeds")
+
+
+async def test_news_api_create_feed(mocker):
+    """Test that create_feed correctly creates a feed."""
+    mock_response = create_mock_news_feed_response(
+        feed_id=10, url="https://example.com/new-feed", title="New Feed"
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    feed = await client.create_feed(url="https://example.com/new-feed")
+
+    assert feed["id"] == 10
+    assert feed["url"] == "https://example.com/new-feed"
+
+    mock_make_request.assert_called_once_with(
+        "POST",
+        "/apps/news/api/v1-3/feeds",
+        json={"url": "https://example.com/new-feed"},
+    )
+
+
+async def test_news_api_create_feed_with_folder(mocker):
+    """Test that create_feed correctly creates a feed in a folder."""
+    mock_response = create_mock_news_feed_response(
+        feed_id=10, url="https://example.com/feed", folder_id=5
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    feed = await client.create_feed(url="https://example.com/feed", folder_id=5)
+
+    assert feed["folderId"] == 5
+
+    mock_make_request.assert_called_once_with(
+        "POST",
+        "/apps/news/api/v1-3/feeds",
+        json={"url": "https://example.com/feed", "folderId": 5},
+    )
+
+
+async def test_news_api_delete_feed(mocker):
+    """Test that delete_feed makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.delete_feed(feed_id=10)
+
+    mock_make_request.assert_called_once_with("DELETE", "/apps/news/api/v1-3/feeds/10")
+
+
+async def test_news_api_move_feed(mocker):
+    """Test that move_feed makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.move_feed(feed_id=10, folder_id=5)
+
+    mock_make_request.assert_called_once_with(
+        "POST", "/apps/news/api/v1-3/feeds/10/move", json={"folderId": 5}
+    )
+
+
+async def test_news_api_rename_feed(mocker):
+    """Test that rename_feed makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.rename_feed(feed_id=10, title="Renamed Feed")
+
+    mock_make_request.assert_called_once_with(
+        "POST",
+        "/apps/news/api/v1-3/feeds/10/rename",
+        json={"feedTitle": "Renamed Feed"},
+    )
+
+
+# ============================================================================
+# Item Tests
+# ============================================================================
+
+
+async def test_news_api_get_items(mocker):
+    """Test that get_items correctly parses the API response."""
+    items = [
+        create_mock_news_item(item_id=1, title="Article 1"),
+        create_mock_news_item(item_id=2, title="Article 2"),
+    ]
+    mock_response = create_mock_news_items_response(items=items)
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    result = await client.get_items()
+
+    assert len(result) == 2
+    assert result[0]["title"] == "Article 1"
+    assert result[1]["title"] == "Article 2"
+
+    # Verify default parameters
+    call_args = mock_make_request.call_args
+    assert call_args[0] == ("GET", "/apps/news/api/v1-3/items")
+    params = call_args[1]["params"]
+    assert params["batchSize"] == 50
+    assert params["type"] == NewsItemType.ALL
+
+
+async def test_news_api_get_items_starred(mocker):
+    """Test that get_items with STARRED type filters correctly."""
+    items = [create_mock_news_item(item_id=1, starred=True)]
+    mock_response = create_mock_news_items_response(items=items)
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    result = await client.get_items(type_=NewsItemType.STARRED)
+
+    assert len(result) == 1
+    assert result[0]["starred"] is True
+
+    call_args = mock_make_request.call_args
+    params = call_args[1]["params"]
+    assert params["type"] == NewsItemType.STARRED
+
+
+async def test_news_api_get_items_unread_only(mocker):
+    """Test that get_items with get_read=False filters correctly."""
+    items = [create_mock_news_item(item_id=1, unread=True)]
+    mock_response = create_mock_news_items_response(items=items)
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    result = await client.get_items(get_read=False)
+
+    assert len(result) == 1
+
+    call_args = mock_make_request.call_args
+    params = call_args[1]["params"]
+    assert params["getRead"] == "false"
+
+
+async def test_news_api_get_item(mocker):
+    """Test that get_item fetches all items and filters for the requested ID."""
+    # Create multiple items, only one should be returned
+    items = [
+        create_mock_news_item(item_id=100, title="Other Item 1"),
+        create_mock_news_item(item_id=123, title="Single Item"),
+        create_mock_news_item(item_id=200, title="Other Item 2"),
+    ]
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_get_items = mocker.patch.object(NewsClient, "get_items", return_value=items)
+
+    client = NewsClient(mock_client, "testuser")
+    result = await client.get_item(item_id=123)
+
+    assert result["id"] == 123
+    assert result["title"] == "Single Item"
+
+    # Verify it fetched all items with correct params
+    mock_get_items.assert_called_once_with(batch_size=-1, get_read=True)
+
+
+async def test_news_api_get_item_not_found(mocker):
+    """Test that get_item raises ValueError when item not found."""
+    items = [
+        create_mock_news_item(item_id=100, title="Item 1"),
+        create_mock_news_item(item_id=200, title="Item 2"),
+    ]
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mocker.patch.object(NewsClient, "get_items", return_value=items)
+
+    client = NewsClient(mock_client, "testuser")
+
+    with pytest.raises(ValueError, match="Item 999 not found"):
+        await client.get_item(item_id=999)
+
+
+async def test_news_api_get_updated_items(mocker):
+    """Test that get_updated_items correctly calls the updated endpoint."""
+    items = [create_mock_news_item(item_id=1)]
+    mock_response = create_mock_news_items_response(items=items)
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    result = await client.get_updated_items(last_modified=1700000000)
+
+    assert len(result) == 1
+
+    call_args = mock_make_request.call_args
+    assert call_args[0] == ("GET", "/apps/news/api/v1-3/items/updated")
+    params = call_args[1]["params"]
+    assert params["lastModified"] == 1700000000
+
+
+async def test_news_api_mark_item_read(mocker):
+    """Test that mark_item_read makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.mark_item_read(item_id=123)
+
+    mock_make_request.assert_called_once_with(
+        "POST", "/apps/news/api/v1-3/items/123/read"
+    )
+
+
+async def test_news_api_mark_item_unread(mocker):
+    """Test that mark_item_unread makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.mark_item_unread(item_id=123)
+
+    mock_make_request.assert_called_once_with(
+        "POST", "/apps/news/api/v1-3/items/123/unread"
+    )
+
+
+async def test_news_api_star_item(mocker):
+    """Test that star_item makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.star_item(item_id=123)
+
+    mock_make_request.assert_called_once_with(
+        "POST", "/apps/news/api/v1-3/items/123/star"
+    )
+
+
+async def test_news_api_unstar_item(mocker):
+    """Test that unstar_item makes the correct API call."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.unstar_item(item_id=123)
+
+    mock_make_request.assert_called_once_with(
+        "POST", "/apps/news/api/v1-3/items/123/unstar"
+    )
+
+
+async def test_news_api_mark_items_read_multiple(mocker):
+    """Test that mark_items_read makes the correct API call for multiple items."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.mark_items_read(item_ids=[1, 2, 3])
+
+    mock_make_request.assert_called_once_with(
+        "POST", "/apps/news/api/v1-3/items/read/multiple", json={"itemIds": [1, 2, 3]}
+    )
+
+
+async def test_news_api_star_items_multiple(mocker):
+    """Test that star_items makes the correct API call for multiple items."""
+    mock_response = create_mock_response(status_code=200, json_data={})
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    await client.star_items(item_ids=[1, 2, 3])
+
+    mock_make_request.assert_called_once_with(
+        "POST", "/apps/news/api/v1-3/items/star/multiple", json={"itemIds": [1, 2, 3]}
+    )
+
+
+# ============================================================================
+# Status Tests
+# ============================================================================
+
+
+async def test_news_api_get_status(mocker):
+    """Test that get_status correctly parses the API response."""
+    mock_response = create_mock_news_status_response(
+        version="25.0.0",
+        warnings={"improperlyConfiguredCron": False},
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    status = await client.get_status()
+
+    assert status["version"] == "25.0.0"
+    assert "warnings" in status
+
+    mock_make_request.assert_called_once_with("GET", "/apps/news/api/v1-3/status")
+
+
+async def test_news_api_get_version(mocker):
+    """Test that get_version correctly parses the API response."""
+    mock_response = create_mock_response(
+        status_code=200, json_data={"version": "25.0.0"}
+    )
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(
+        NewsClient, "_make_request", return_value=mock_response
+    )
+
+    client = NewsClient(mock_client, "testuser")
+    version = await client.get_version()
+
+    assert version == "25.0.0"
+
+    mock_make_request.assert_called_once_with("GET", "/apps/news/api/v1-3/version")
+
+
+# ============================================================================
+# Error Handling Tests
+# ============================================================================
+
+
+async def test_news_api_create_folder_conflict(mocker):
+    """Test that create_folder raises HTTPStatusError on 409 conflict."""
+    error_response = create_mock_error_response(409, "Folder name already exists")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(NewsClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "409 Conflict",
+        request=httpx.Request("POST", "http://test.local"),
+        response=error_response,
+    )
+
+    client = NewsClient(mock_client, "testuser")
+
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.create_folder(name="Existing Folder")
+
+    assert excinfo.value.response.status_code == 409
+
+
+async def test_news_api_delete_feed_not_found(mocker):
+    """Test that delete_feed raises HTTPStatusError on 404."""
+    error_response = create_mock_error_response(404, "Feed not found")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(NewsClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "404 Not Found",
+        request=httpx.Request("DELETE", "http://test.local"),
+        response=error_response,
+    )
+
+    client = NewsClient(mock_client, "testuser")
+
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.delete_feed(feed_id=999999)
+
+    assert excinfo.value.response.status_code == 404
+
+
+async def test_news_api_create_feed_invalid_url(mocker):
+    """Test that create_feed raises HTTPStatusError on 422 for invalid URL."""
+    error_response = create_mock_error_response(422, "Invalid feed URL")
+
+    mock_client = mocker.AsyncMock(spec=httpx.AsyncClient)
+    mock_make_request = mocker.patch.object(NewsClient, "_make_request")
+    mock_make_request.side_effect = httpx.HTTPStatusError(
+        "422 Unprocessable Entity",
+        request=httpx.Request("POST", "http://test.local"),
+        response=error_response,
+    )
+
+    client = NewsClient(mock_client, "testuser")
+
+    with pytest.raises(httpx.HTTPStatusError) as excinfo:
+        await client.create_feed(url="not-a-valid-url")
+
+    assert excinfo.value.response.status_code == 422

tests/conftest.py

@@ -9,7 +9,6 @@ import pytest
 from httpx import HTTPStatusError
 from mcp import ClientSession
 from mcp.client.session import RequestContext
-from mcp.client.sse import sse_client
 from mcp.client.streamable_http import streamablehttp_client
 from mcp.types import ElicitRequestParams, ElicitResult, ErrorData
 
@@ -172,51 +171,6 @@ async def create_mcp_client_session(
     logger.debug(f"{client_name} client session cleaned up successfully")
 
 
-async def create_mcp_client_session_sse(
-    url: str,
-    token: str | None = None,
-    client_name: str = "MCP",
-    elicitation_callback: Any = None,
-) -> AsyncGenerator[ClientSession, Any]:
-    """
-    Factory function to create an MCP client session using SSE transport.
-
-    Similar to create_mcp_client_session but uses SSE transport instead of streamable-http.
-    Uses native async context managers to ensure correct LIFO cleanup order.
-
-    Args:
-        url: MCP server URL (e.g., "http://localhost:8000/sse")
-        token: Optional OAuth access token for Bearer authentication
-        client_name: Client name for logging (e.g., "Basic MCP (SSE)")
-        elicitation_callback: Optional callback for handling elicitation requests
-
-    Yields:
-        Initialized MCP ClientSession
-
-    Note:
-        SSE transport is being deprecated in favor of streamable-http.
-        This function exists for compatibility testing only.
-    """
-    logger.info(f"Creating SSE client for {client_name}")
-
-    # Prepare headers with OAuth token if provided
-    headers = {"Authorization": f"Bearer {token}"} if token else None
-
-    # Use native async with - Python ensures LIFO cleanup
-    # Cleanup order will be: ClientSession.__aexit__ -> sse_client.__aexit__
-    # Note: sse_client yields only (read_stream, write_stream), not 3 values like streamablehttp_client
-    async with sse_client(url, headers=headers) as (read_stream, write_stream):
-        async with ClientSession(
-            read_stream, write_stream, elicitation_callback=elicitation_callback
-        ) as session:
-            await session.initialize()
-            logger.info(f"{client_name} client session initialized successfully")
-            yield session
-
-    # Cleanup happens automatically in LIFO order - no exception suppression needed
-    logger.debug(f"{client_name} client session cleaned up successfully")
-
-
 @pytest.fixture(scope="session")
 async def nc_client(anyio_backend) -> AsyncGenerator[NextcloudClient, Any]:
     """
@@ -255,18 +209,10 @@ async def nc_client(anyio_backend) -> AsyncGenerator[NextcloudClient, Any]:
 @pytest.fixture(scope="session")
 async def nc_mcp_client(anyio_backend) -> AsyncGenerator[ClientSession, Any]:
     """
-    Fixture to create an MCP client session for integration tests using SSE transport.
+    Fixture to create an MCP client session for integration tests using streamable-http.
 
     Uses anyio pytest plugin for proper async fixture handling.
-
-    Note: SSE transport is being deprecated. This fixture uses SSE for compatibility testing.
     """
-
-    # async for session in create_mcp_client_session_sse(
-    # url="http://localhost:8000/sse", client_name="Basic MCP (SSE)"
-    # ):
-    # yield session
-
     async for session in create_mcp_client_session(
         url="http://localhost:8000/mcp",
         client_name="Basic MCP (HTTP)",

tests/integration/conftest.py

@@ -0,0 +1,26 @@
+"""Pytest configuration for integration tests.
+
+This conftest.py provides hooks and fixtures specific to integration tests,
+including the --provider flag for RAG tests.
+"""
+
+# Valid provider names
+VALID_PROVIDERS = ["openai", "ollama", "anthropic", "bedrock"]
+
+
+def pytest_addoption(parser):
+    """Add --provider command line option for RAG tests."""
+    parser.addoption(
+        "--provider",
+        action="store",
+        default=None,
+        choices=VALID_PROVIDERS,
+        help="LLM provider for RAG tests: openai, ollama, anthropic, bedrock",
+    )
+
+
+def pytest_configure(config):
+    """Configure custom markers."""
+    config.addinivalue_line(
+        "markers", "rag: mark test as RAG integration test (requires --provider flag)"
+    )

tests/integration/provider_fixtures.py

@@ -0,0 +1,264 @@
+"""Provider fixtures for integration tests.
+
+This module provides pytest fixtures that configure LLM providers based on
+an explicit --provider flag. Supports OpenAI, Ollama, Anthropic, and Bedrock.
+
+Usage:
+    pytest tests/integration/test_rag.py --provider=openai
+    pytest tests/integration/test_rag.py --provider=ollama
+    pytest tests/integration/test_rag.py --provider=anthropic
+    pytest tests/integration/test_rag.py --provider=bedrock
+
+Environment Variables by Provider:
+
+OpenAI:
+    OPENAI_API_KEY: API key (required)
+    OPENAI_BASE_URL: Base URL override (e.g., "https://models.github.ai/inference")
+    OPENAI_EMBEDDING_MODEL: Embedding model (default: "text-embedding-3-small")
+    OPENAI_GENERATION_MODEL: Generation model (default: "gpt-4o-mini")
+
+Ollama:
+    OLLAMA_BASE_URL: API URL (required, e.g., "http://localhost:11434")
+    OLLAMA_EMBEDDING_MODEL: Embedding model (default: "nomic-embed-text")
+    OLLAMA_GENERATION_MODEL: Generation model (default: "llama3.2:1b")
+
+Anthropic:
+    ANTHROPIC_API_KEY: API key (required)
+    ANTHROPIC_GENERATION_MODEL: Model (default: "claude-3-haiku-20240307")
+
+Bedrock:
+    AWS_REGION: AWS region (required)
+    BEDROCK_EMBEDDING_MODEL: Embedding model ID
+    BEDROCK_GENERATION_MODEL: Generation model ID
+"""
+
+import logging
+import os
+from typing import AsyncGenerator
+
+import pytest
+
+from nextcloud_mcp_server.providers.base import Provider
+
+logger = logging.getLogger(__name__)
+
+# Valid provider names (must match conftest.py)
+VALID_PROVIDERS = ["openai", "ollama", "anthropic", "bedrock"]
+
+
+async def create_generation_provider(provider_name: str) -> Provider:
+    """Create a provider configured for text generation.
+
+    Args:
+        provider_name: One of "openai", "ollama", "anthropic", "bedrock"
+
+    Returns:
+        Provider instance configured for generation
+
+    Raises:
+        ValueError: If provider_name is invalid or required env vars missing
+    """
+    if provider_name == "openai":
+        from nextcloud_mcp_server.providers.openai import OpenAIProvider
+
+        api_key = os.getenv("OPENAI_API_KEY")
+        if not api_key:
+            raise ValueError("OPENAI_API_KEY environment variable required")
+
+        base_url = os.getenv("OPENAI_BASE_URL")
+        generation_model = os.getenv("OPENAI_GENERATION_MODEL", "gpt-4o-mini")
+
+        # GitHub Models API requires model name prefix
+        if base_url and "models.github.ai" in base_url:
+            if not generation_model.startswith("openai/"):
+                generation_model = f"openai/{generation_model}"
+
+        provider = OpenAIProvider(
+            api_key=api_key,
+            base_url=base_url,
+            embedding_model=None,  # Generation only
+            generation_model=generation_model,
+        )
+        logger.info(f"Created OpenAI generation provider: model={generation_model}")
+        return provider
+
+    elif provider_name == "ollama":
+        from nextcloud_mcp_server.providers.ollama import OllamaProvider
+
+        base_url = os.getenv("OLLAMA_BASE_URL")
+        if not base_url:
+            raise ValueError("OLLAMA_BASE_URL environment variable required")
+
+        generation_model = os.getenv("OLLAMA_GENERATION_MODEL", "llama3.2:1b")
+
+        provider = OllamaProvider(
+            base_url=base_url,
+            embedding_model=None,  # Generation only
+            generation_model=generation_model,
+        )
+        logger.info(f"Created Ollama generation provider: model={generation_model}")
+        return provider
+
+    elif provider_name == "anthropic":
+        from nextcloud_mcp_server.providers.anthropic import AnthropicProvider
+
+        api_key = os.getenv("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise ValueError("ANTHROPIC_API_KEY environment variable required")
+
+        generation_model = os.getenv(
+            "ANTHROPIC_GENERATION_MODEL", "claude-3-haiku-20240307"
+        )
+
+        provider = AnthropicProvider(
+            api_key=api_key,
+            generation_model=generation_model,
+        )
+        logger.info(f"Created Anthropic generation provider: model={generation_model}")
+        return provider
+
+    elif provider_name == "bedrock":
+        from nextcloud_mcp_server.providers.bedrock import BedrockProvider
+
+        region = os.getenv("AWS_REGION")
+        if not region:
+            raise ValueError("AWS_REGION environment variable required")
+
+        generation_model = os.getenv("BEDROCK_GENERATION_MODEL")
+        if not generation_model:
+            raise ValueError("BEDROCK_GENERATION_MODEL environment variable required")
+
+        provider = BedrockProvider(
+            region=region,
+            embedding_model=None,  # Generation only
+            generation_model=generation_model,
+        )
+        logger.info(f"Created Bedrock generation provider: model={generation_model}")
+        return provider
+
+    else:
+        raise ValueError(f"Unknown provider: {provider_name}. Valid: {VALID_PROVIDERS}")
+
+
+async def create_embedding_provider(provider_name: str) -> Provider:
+    """Create a provider configured for embeddings.
+
+    Args:
+        provider_name: One of "openai", "ollama", "bedrock"
+                      (Anthropic does not support embeddings)
+
+    Returns:
+        Provider instance configured for embeddings
+
+    Raises:
+        ValueError: If provider_name is invalid, doesn't support embeddings,
+                   or required env vars missing
+    """
+    if provider_name == "anthropic":
+        raise ValueError("Anthropic does not support embeddings")
+
+    if provider_name == "openai":
+        from nextcloud_mcp_server.providers.openai import OpenAIProvider
+
+        api_key = os.getenv("OPENAI_API_KEY")
+        if not api_key:
+            raise ValueError("OPENAI_API_KEY environment variable required")
+
+        base_url = os.getenv("OPENAI_BASE_URL")
+        embedding_model = os.getenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
+
+        # GitHub Models API requires model name prefix
+        if base_url and "models.github.ai" in base_url:
+            if not embedding_model.startswith("openai/"):
+                embedding_model = f"openai/{embedding_model}"
+
+        provider = OpenAIProvider(
+            api_key=api_key,
+            base_url=base_url,
+            embedding_model=embedding_model,
+            generation_model=None,  # Embeddings only
+        )
+        logger.info(f"Created OpenAI embedding provider: model={embedding_model}")
+        return provider
+
+    elif provider_name == "ollama":
+        from nextcloud_mcp_server.providers.ollama import OllamaProvider
+
+        base_url = os.getenv("OLLAMA_BASE_URL")
+        if not base_url:
+            raise ValueError("OLLAMA_BASE_URL environment variable required")
+
+        embedding_model = os.getenv("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text")
+
+        provider = OllamaProvider(
+            base_url=base_url,
+            embedding_model=embedding_model,
+            generation_model=None,  # Embeddings only
+        )
+        logger.info(f"Created Ollama embedding provider: model={embedding_model}")
+        return provider
+
+    elif provider_name == "bedrock":
+        from nextcloud_mcp_server.providers.bedrock import BedrockProvider
+
+        region = os.getenv("AWS_REGION")
+        if not region:
+            raise ValueError("AWS_REGION environment variable required")
+
+        embedding_model = os.getenv("BEDROCK_EMBEDDING_MODEL")
+        if not embedding_model:
+            raise ValueError("BEDROCK_EMBEDDING_MODEL environment variable required")
+
+        provider = BedrockProvider(
+            region=region,
+            embedding_model=embedding_model,
+            generation_model=None,  # Embeddings only
+        )
+        logger.info(f"Created Bedrock embedding provider: model={embedding_model}")
+        return provider
+
+    else:
+        raise ValueError(f"Unknown provider: {provider_name}. Valid: {VALID_PROVIDERS}")
+
+
+# =============================================================================
+# Pytest Fixtures
+# =============================================================================
+
+
+@pytest.fixture(scope="module")
+def provider_name(request) -> str:
+    """Get the provider name from --provider flag.
+
+    Raises pytest.skip if --provider not specified.
+    """
+    name = request.config.getoption("--provider")
+    if not name:
+        pytest.skip("--provider flag required (openai, ollama, anthropic, bedrock)")
+    return name
+
+
+@pytest.fixture(scope="module")
+async def generation_provider(provider_name: str) -> AsyncGenerator[Provider, None]:
+    """Fixture providing a generation-capable provider.
+
+    Requires --provider flag to be set.
+    """
+    provider = await create_generation_provider(provider_name)
+    yield provider
+    await provider.close()
+
+
+@pytest.fixture(scope="module")
+async def embedding_provider(provider_name: str) -> AsyncGenerator[Provider, None]:
+    """Fixture providing an embedding-capable provider.
+
+    Requires --provider flag to be set.
+    Note: Anthropic does not support embeddings - test will fail if used.
+    """
+    if provider_name == "anthropic":
+        pytest.skip("Anthropic does not support embeddings")
+
+    provider = await create_embedding_provider(provider_name)
+    yield provider
+    await provider.close()

tests/integration/sampling_support.py

@@ -1,7 +1,7 @@
 """MCP sampling support for integration tests.
 
 This module provides utilities to enable real LLM-based sampling in integration tests
-using OpenAI or GitHub Models API.
+using any provider that supports text generation (OpenAI, Ollama, Anthropic, Bedrock).
 """
 
 import logging
@@ -10,46 +10,58 @@ from typing import Any
 from mcp import types
 from mcp.client.session import ClientSession, RequestContext
 
-from nextcloud_mcp_server.providers.openai import OpenAIProvider
+from nextcloud_mcp_server.providers.base import Provider
 
 logger = logging.getLogger(__name__)
 
 
-def create_openai_sampling_callback(provider: OpenAIProvider):
-    """Factory to create a sampling callback using OpenAI provider.
+def create_sampling_callback(provider: Provider):
+    """Factory to create a sampling callback using any generation-capable provider.
 
     The callback conforms to MCP's SamplingFnT protocol and can be passed
     to ClientSession for handling sampling requests from the server.
 
     Args:
-        provider: OpenAIProvider instance configured with a generation model
+        provider: Any Provider instance that supports generation
+                  (supports_generation=True)
 
     Returns:
         Async callback function for MCP sampling
 
+    Raises:
+        ValueError: If provider doesn't support generation
+
     Example:
         ```python
-        provider = OpenAIProvider(
-            api_key=os.getenv("OPENAI_API_KEY"),
-            base_url=os.getenv("OPENAI_BASE_URL"),
-            generation_model="gpt-4o-mini",
-        )
-        callback = create_openai_sampling_callback(provider)
+        from nextcloud_mcp_server.providers import get_provider
 
-        async for session in create_mcp_client_session(
-            url="http://localhost:8000/mcp",
-            sampling_callback=callback,
-        ):
-            # Session now supports sampling
-            pass
+        provider = get_provider()  # Auto-detect from environment
+        if provider.supports_generation:
+            callback = create_sampling_callback(provider)
+
+            async for session in create_mcp_client_session(
+                url="http://localhost:8000/mcp",
+                sampling_callback=callback,
+            ):
+                # Session now supports sampling
+                pass
         ```
     """
+    if not provider.supports_generation:
+        raise ValueError(
+            f"Provider {provider.__class__.__name__} does not support generation"
+        )
+
+    # Get model name for logging (provider-specific attribute)
+    model_name = (
+        getattr(provider, "generation_model", None) or provider.__class__.__name__
+    )
 
     async def sampling_callback(
         context: RequestContext[ClientSession, Any],
         params: types.CreateMessageRequestParams,
     ) -> types.CreateMessageResult | types.ErrorData:
-        """Handle sampling requests using OpenAI provider."""
+        """Handle sampling requests using the configured provider."""
         logger.debug(f"Sampling callback invoked with {len(params.messages)} messages")
 
         # Extract messages and build prompt
@@ -68,14 +80,13 @@ def create_openai_sampling_callback(provider: OpenAIProvider):
         logger.debug(f"Generating response for prompt ({len(prompt)} chars)")
 
         try:
-            # Generate response using OpenAI provider
-            # Note: temperature is hardcoded in the provider at 0.7
+            # Generate response using provider
+            # Note: temperature is typically hardcoded in providers at 0.7
             response = await provider.generate(
                 prompt=prompt,
                 max_tokens=params.maxTokens,
             )
 
-            model_name = provider.generation_model or "unknown"
             logger.info(f"Sampling completed: {len(response)} chars from {model_name}")
 
             return types.CreateMessageResult(
@@ -85,10 +96,25 @@ def create_openai_sampling_callback(provider: OpenAIProvider):
                 stopReason="endTurn",
             )
         except Exception as e:
-            logger.error(f"OpenAI generation failed: {e}")
+            logger.error(f"Generation failed ({provider.__class__.__name__}): {e}")
             return types.ErrorData(
                 code=types.INTERNAL_ERROR,
-                message=f"OpenAI generation failed: {e!s}",
+                message=f"Generation failed: {e!s}",
             )
 
     return sampling_callback
+
+
+def create_openai_sampling_callback(provider: "Provider"):
+    """Factory to create a sampling callback using OpenAI provider.
+
+    This is a backward-compatible wrapper around create_sampling_callback().
+    Prefer using create_sampling_callback() directly for new code.
+
+    Args:
+        provider: OpenAIProvider instance configured with a generation model
+
+    Returns:
+        Async callback function for MCP sampling
+    """
+    return create_sampling_callback(provider)

tests/integration/test_deck_vector_search.py

@@ -0,0 +1,238 @@
+"""Integration tests for Deck card vector search.
+
+These tests validate that Deck cards are properly indexed and searchable
+via semantic search.
+"""
+
+import pytest
+
+pytestmark = [pytest.mark.integration, pytest.mark.smoke]
+
+
+async def test_deck_card_semantic_search(nc_mcp_client, nc_client, mocker):
+    """Test that Deck cards can be indexed and searched via semantic search.
+
+    This test:
+    1. Creates a Deck board with a card
+    2. Manually triggers indexing (simulates vector sync)
+    3. Performs semantic search filtering by deck_card doc_type
+    4. Verifies the card is found in results
+    """
+    # Skip if vector sync is not enabled
+    settings_response = await nc_mcp_client.call_tool("nc_get_vector_sync_status", {})
+    if settings_response.isError:
+        pytest.skip("Vector sync not enabled")
+
+    # Create a test board
+    board_title = "Test Board for Vector Search"
+    board = await nc_client.deck.create_board(title=board_title, color="ff0000")
+
+    try:
+        # Create a stack for the board
+        stack = await nc_client.deck.create_stack(
+            board_id=board.id, title="Test Stack", order=0
+        )
+
+        # Create a test card with searchable content
+        card_title = "Machine Learning Project Plan"
+        card_description = """
+        # ML Project Outline
+
+        ## Phase 1: Data Collection
+        - Gather training data from multiple sources
+        - Clean and preprocess the dataset
+
+        ## Phase 2: Model Training
+        - Experiment with different neural network architectures
+        - Use gradient descent optimization
+
+        ## Phase 3: Deployment
+        - Deploy model to production environment
+        - Monitor performance metrics
+        """
+        card = await nc_client.deck.create_card(
+            board_id=board.id,
+            stack_id=stack.id,
+            title=card_title,
+            description=card_description,
+        )
+
+        # Note: In a real integration test with vector sync enabled,
+        # we would wait for the background scanner to index the card.
+        # For now, we'll test the scanning function directly if needed.
+
+        # TODO: Once vector sync is running in test environment,
+        # add actual semantic search test here
+        # For now, just verify the card was created successfully
+        assert card.id is not None
+        assert card.title == card_title
+        assert card.description == card_description
+
+        # Test semantic search with deck_card filter
+        # Note: This will only work if vector sync is actually running
+        # and the card has been indexed
+        try:
+            search_result = await nc_mcp_client.call_tool(
+                "nc_semantic_search",
+                {
+                    "query": "machine learning neural networks",
+                    "doc_types": ["deck_card"],
+                    "limit": 10,
+                },
+            )
+
+            # If vector sync is working, we should find the card
+            if not search_result.isError:
+                data = search_result.structuredContent
+                results = data.get("results", [])
+
+                # Check if our card is in the results
+                found_card = any(
+                    r.get("doc_type") == "deck_card" and r.get("title") == card_title
+                    for r in results
+                )
+
+                # Log result for debugging
+                if found_card:
+                    print("✓ Successfully found Deck card in vector search")
+                else:
+                    print(
+                        "⚠ Deck card not found in search (may need time for indexing)"
+                    )
+        except Exception as e:
+            # If search fails, it might be because indexing hasn't happened yet
+            print(f"⚠ Semantic search failed (indexing may not be complete): {e}")
+
+    finally:
+        # Cleanup: delete the board
+        try:
+            await nc_client.deck.delete_board(board.id)
+        except Exception as e:
+            print(f"Warning: Failed to cleanup test board: {e}")
+
+
+async def test_deck_card_appears_in_cross_app_search(nc_mcp_client, nc_client):
+    """Test that Deck cards appear in cross-app semantic search (no doc_type filter).
+
+    This verifies that when searching without specifying doc_types,
+    Deck cards are included in the results alongside notes, files, etc.
+    """
+    # Skip if vector sync is not enabled
+    settings_response = await nc_mcp_client.call_tool("nc_get_vector_sync_status", {})
+    if settings_response.isError:
+        pytest.skip("Vector sync not enabled")
+
+    # Create a test board with a distinctive card
+    board_title = "Cross-App Search Test Board"
+    board = await nc_client.deck.create_board(title=board_title, color="00ff00")
+
+    try:
+        # Create a stack for the board
+        stack = await nc_client.deck.create_stack(
+            board_id=board.id, title="Test Stack", order=0
+        )
+
+        # Use a very distinctive term to make it easy to find
+        unique_term = "xylophone_banana_unicorn_test"
+        _card = await nc_client.deck.create_card(
+            board_id=board.id,
+            stack_id=stack.id,
+            title=f"Test Card with {unique_term}",
+            description=f"This card contains the unique search term: {unique_term}",
+        )
+
+        # Test cross-app search (no doc_type filter)
+        try:
+            search_result = await nc_mcp_client.call_tool(
+                "nc_semantic_search",
+                {
+                    "query": unique_term,
+                    "limit": 20,
+                },
+            )
+
+            if not search_result.isError:
+                data = search_result.structuredContent
+                results = data.get("results", [])
+
+                # Check if deck_card appears in cross-app results
+                deck_cards_found = [
+                    r for r in results if r.get("doc_type") == "deck_card"
+                ]
+
+                if deck_cards_found:
+                    print(
+                        f"✓ Found {len(deck_cards_found)} Deck card(s) in cross-app search"
+                    )
+                else:
+                    print(
+                        "⚠ No Deck cards in cross-app search (may need time for indexing)"
+                    )
+        except Exception as e:
+            print(f"⚠ Cross-app search failed: {e}")
+
+    finally:
+        # Cleanup
+        try:
+            await nc_client.deck.delete_board(board.id)
+        except Exception as e:
+            print(f"Warning: Failed to cleanup test board: {e}")
+
+
+async def test_deck_card_chunk_context(nc_client):
+    """Test that Deck card chunk context can be fetched for visualization.
+
+    This test validates that the vector viz UI can display Deck card previews
+    by fetching the chunk context via the context expansion module.
+    """
+    from nextcloud_mcp_server.search.context import get_chunk_with_context
+
+    # Create board, stack, and card
+    board = await nc_client.deck.create_board(title="Test Board", color="ff0000")
+
+    try:
+        stack = await nc_client.deck.create_stack(
+            board_id=board.id, title="Test Stack", order=0
+        )
+
+        card_title = "Test Card for Context Expansion"
+        card_description = "This is a test description that should be fetched by the context expansion module when displaying chunk previews in the vector visualization UI."
+
+        card = await nc_client.deck.create_card(
+            board_id=board.id,
+            stack_id=stack.id,
+            title=card_title,
+            description=card_description,
+        )
+
+        # Fetch chunk context (simulates viz UI request)
+        # The chunk spans the title, so start=0 and end=len(card_title)
+        context = await get_chunk_with_context(
+            nc_client=nc_client,
+            user_id=nc_client.username,
+            doc_id=card.id,
+            doc_type="deck_card",
+            chunk_start=0,
+            chunk_end=len(card_title),
+            context_chars=100,
+        )
+
+        # Verify context was fetched successfully
+        assert context is not None, "Chunk context should not be None"
+        assert card_title in context.chunk_text, (
+            f"Card title '{card_title}' should be in chunk_text"
+        )
+
+        # Verify context includes description
+        assert card_description[:50] in context.after_context, (
+            "Card description should be in after_context"
+        )
+
+        print(f"✓ Successfully fetched chunk context for Deck card {card.id}")
+
+    finally:
+        # Cleanup
+        try:
+            await nc_client.deck.delete_board(board.id)
+        except Exception as e:
+            print(f"Warning: Failed to cleanup test board: {e}")

tests/integration/test_rag.py

@@ -1,26 +1,33 @@
-"""Integration tests for RAG pipeline with OpenAI/GitHub Models API.
+"""Integration tests for RAG pipeline with multiple LLM providers.
 
 These tests validate the complete semantic search and MCP sampling flow using:
-1. OpenAI embeddings for semantic search
-2. MCP sampling for answer generation
+1. MCP server's built-in semantic search (embeddings handled server-side)
+2. MCP sampling for answer generation (any generation-capable provider)
 3. Pre-indexed Nextcloud User Manual as the knowledge base
 
-Environment Variables:
-    OPENAI_API_KEY: OpenAI API key or GitHub token for models.github.ai
-    OPENAI_BASE_URL: Base URL override (e.g., "https://models.github.ai/inference")
-    OPENAI_EMBEDDING_MODEL: Embedding model (default: "text-embedding-3-small")
-    OPENAI_GENERATION_MODEL: Generation model for sampling (default: "gpt-4o-mini")
-    RAG_MANUAL_PATH: Path to manual PDF in Nextcloud (default: "Nextcloud_User_Manual.pdf")
+Usage:
+    # Run with OpenAI (including GitHub Models API)
+    OPENAI_API_KEY=... pytest tests/integration/test_rag.py --provider=openai -v
 
-For GitHub CI, set:
-    OPENAI_API_KEY: ${{ secrets.GITHUB_TOKEN }}
-    OPENAI_BASE_URL: https://models.github.ai/inference
-    OPENAI_EMBEDDING_MODEL: openai/text-embedding-3-small
-    OPENAI_GENERATION_MODEL: openai/gpt-4o-mini
+    # Run with Ollama
+    OLLAMA_BASE_URL=http://localhost:11434 OLLAMA_GENERATION_MODEL=llama3.2:1b \\
+        pytest tests/integration/test_rag.py --provider=ollama -v
+
+    # Run with Anthropic
+    ANTHROPIC_API_KEY=... pytest tests/integration/test_rag.py --provider=anthropic -v
+
+    # Run with AWS Bedrock
+    AWS_REGION=us-east-1 BEDROCK_GENERATION_MODEL=... \\
+        pytest tests/integration/test_rag.py --provider=bedrock -v
+
+Environment Variables:
+    See tests/integration/provider_fixtures.py for provider-specific configuration.
+    RAG_MANUAL_PATH: Path to manual PDF in Nextcloud (default: "Nextcloud Manual.pdf")
 
 Prerequisites:
     - Nextcloud User Manual PDF uploaded to Nextcloud
     - VECTOR_SYNC_ENABLED=true on the MCP server
+    - Provider-specific environment variables set
 """
 
 import json
@@ -33,22 +40,52 @@ import anyio
 import pytest
 from mcp import ClientSession
 
-from nextcloud_mcp_server.providers.openai import OpenAIProvider
+from nextcloud_mcp_server.providers.base import Provider
 from tests.conftest import create_mcp_client_session
-from tests.integration.sampling_support import create_openai_sampling_callback
+from tests.integration.provider_fixtures import create_generation_provider
+from tests.integration.sampling_support import create_sampling_callback
 
 logger = logging.getLogger(__name__)
 
 # Default path to the Nextcloud User Manual PDF
 DEFAULT_MANUAL_PATH = "Nextcloud Manual.pdf"
 
-# Skip all tests if OpenAI API key not configured
+
+async def llm_judge(
+    provider: Provider,
+    ground_truth: str,
+    system_output: str,
+) -> bool:
+    """Use LLM to judge if system output aligns with ground truth.
+
+    Args:
+        provider: Any provider with generation capability
+        ground_truth: The expected/reference answer
+        system_output: The system's actual output to evaluate
+
+    Returns:
+        True if output aligns with ground truth, False otherwise
+    """
+    prompt = f"""GROUND TRUTH: {ground_truth}
+
+SYSTEM OUTPUT: {system_output}
+
+Does the system output contain the key facts from the ground truth?
+
+Answer: TRUE or FALSE"""
+
+    logger.info("Received ground truth: %s", ground_truth)
+    logger.info("Received system output: %s", system_output)
+
+    response = await provider.generate(prompt, max_tokens=10)
+    logger.info("LLM Judge response: %s", response)
+    return "TRUE" in response.upper()
+
+
+# Mark all tests as integration tests
 pytestmark = [
     pytest.mark.integration,
-    pytest.mark.skipif(
-        not os.getenv("OPENAI_API_KEY"),
-        reason="OPENAI_API_KEY not set - skipping OpenAI RAG tests",
-    ),
+    pytest.mark.rag,
 ]
 
 # Ground truth fixture path
@@ -147,78 +184,49 @@ async def indexed_manual_pdf(nc_client, nc_mcp_client):
 
 
 @pytest.fixture(scope="module")
-async def openai_provider():
-    """OpenAI provider configured from environment (embeddings only)."""
-    api_key = os.getenv("OPENAI_API_KEY")
-    base_url = os.getenv("OPENAI_BASE_URL")
-    embedding_model = os.getenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
+def provider_name(request) -> str:
+    """Get the provider name from --provider flag.
 
-    provider = OpenAIProvider(
-        api_key=api_key,
-        base_url=base_url,
-        embedding_model=embedding_model,
-        generation_model=None,  # Embeddings only
-    )
-
-    yield provider
-    await provider.close()
+    Raises pytest.skip if --provider not specified.
+    """
+    name = request.config.getoption("--provider")
+    if not name:
+        pytest.skip("--provider flag required (openai, ollama, anthropic, bedrock)")
+    return name
 
 
 @pytest.fixture(scope="module")
-async def openai_generation_provider():
-    """OpenAI provider configured for text generation (for sampling callback)."""
-    api_key = os.getenv("OPENAI_API_KEY")
-    base_url = os.getenv("OPENAI_BASE_URL")
-    generation_model = os.getenv("OPENAI_GENERATION_MODEL", "gpt-4o-mini")
-
-    # For GitHub Models API, use the prefixed model name
-    if base_url and "models.github.ai" in base_url:
-        if not generation_model.startswith("openai/"):
-            generation_model = f"openai/{generation_model}"
-
-    provider = OpenAIProvider(
-        api_key=api_key,
-        base_url=base_url,
-        embedding_model=None,  # Generation only
-        generation_model=generation_model,
-    )
+async def generation_provider(provider_name: str) -> AsyncGenerator[Provider, None]:
+    """Provider configured for text generation.
 
+    Requires --provider flag to be set.
+    """
+    provider = await create_generation_provider(provider_name)
     yield provider
     await provider.close()
 
 
 @pytest.fixture(scope="module")
 async def nc_mcp_client_with_sampling(
-    anyio_backend, openai_generation_provider
+    anyio_backend, generation_provider, provider_name
 ) -> AsyncGenerator[ClientSession, Any]:
-    """MCP client with OpenAI-based sampling support.
+    """MCP client with sampling support using the specified provider.
 
     This fixture creates an MCP client that can handle sampling requests
-    from the server using OpenAI for text generation.
+    from the server using the configured generation provider.
     """
-    sampling_callback = create_openai_sampling_callback(openai_generation_provider)
+    sampling_callback = create_sampling_callback(generation_provider)
 
     async for session in create_mcp_client_session(
         url="http://localhost:8000/mcp",
-        client_name="OpenAI Sampling MCP",
+        client_name=f"Sampling MCP ({provider_name})",
         sampling_callback=sampling_callback,
     ):
         yield session
 
 
-async def test_openai_embeddings_work(openai_provider: OpenAIProvider):
-    """Test that OpenAI embeddings can be generated."""
-    embedding = await openai_provider.embed("test query about Nextcloud")
-
-    assert isinstance(embedding, list)
-    assert len(embedding) > 0
-    assert all(isinstance(x, float) for x in embedding)
-    # OpenAI embedding dimensions: 1536 (small) or 3072 (large)
-    assert len(embedding) in [1536, 3072]
-
-
 async def test_semantic_search_retrieval(
-    nc_mcp_client, ground_truth_qa, indexed_manual_pdf
+    nc_mcp_client, ground_truth_qa, indexed_manual_pdf, generation_provider
 ):
     """Test that semantic search retrieves relevant documents from the manual.
 
@@ -228,7 +236,6 @@ async def test_semantic_search_retrieval(
     # Use first query from ground truth
     test_case = ground_truth_qa[0]  # 2FA question
     query = test_case["query"]
-    expected_topics = test_case["expected_topics"]
 
     # Perform semantic search via MCP tool
     result = await nc_mcp_client.call_tool(
@@ -248,25 +255,30 @@ async def test_semantic_search_retrieval(
     assert data["total_found"] > 0, f"No results for query: {query}"
     assert len(data["results"]) > 0
 
-    # Check that at least one result contains expected topic keywords
-    all_excerpts = " ".join([r["excerpt"].lower() for r in data["results"]])
-    topic_found = any(topic.lower() in all_excerpts for topic in expected_topics)
-    assert topic_found, (
-        f"Expected topics {expected_topics} not found in results for query: {query}"
+    # Use LLM judge to evaluate if excerpts are relevant to ground truth
+    all_excerpts = " ".join([r["excerpt"] for r in data["results"]])
+    is_relevant = await llm_judge(
+        generation_provider,
+        test_case["ground_truth"],
+        all_excerpts,
     )
+    assert is_relevant, f"LLM judge: excerpts not relevant to query: {query}"
 
 
 async def test_semantic_search_answer_with_sampling(
-    nc_mcp_client_with_sampling, ground_truth_qa, indexed_manual_pdf
+    nc_mcp_client_with_sampling,
+    ground_truth_qa,
+    indexed_manual_pdf,
+    generation_provider,
 ):
     """Test semantic search with MCP sampling for answer generation.
 
     This tests the full RAG pipeline:
     1. Semantic search retrieves relevant documents
     2. MCP sampling generates an answer from the retrieved context
-    3. OpenAI generates the answer via the sampling callback
+    3. Provider generates the answer via the sampling callback
 
-    Uses nc_mcp_client_with_sampling which has OpenAI-based sampling enabled.
+    Uses nc_mcp_client_with_sampling which has sampling enabled.
     """
     # Use the 2FA question - has clear expected answer
     test_case = ground_truth_qa[0]
@@ -314,12 +326,13 @@ async def test_semantic_search_answer_with_sampling(
         assert data["generated_answer"] is not None
         assert len(data["generated_answer"]) > 50  # Non-trivial answer
 
-        # Check answer contains relevant content
-        answer_lower = data["generated_answer"].lower()
-        assert any(
-            keyword in answer_lower
-            for keyword in ["two-factor", "2fa", "authentication", "password"]
-        ), f"Answer doesn't seem relevant to query: {data['generated_answer'][:200]}"
+        # Use LLM judge to evaluate answer relevance
+        is_relevant = await llm_judge(
+            generation_provider,
+            test_case["ground_truth"],
+            data["generated_answer"],
+        )
+        assert is_relevant, f"LLM judge: answer not relevant to query: {query}"
 
 
 @pytest.mark.parametrize(