bump: version 0.29.1 → 0.29.2

2025-11-09 18:28:34 +00:00
25 changed files with 356 additions and 1906 deletions
@@ -52,7 +52,6 @@ jobs:
        uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
        with:
          compose-file: "./docker-compose.yml"
-          #compose-flags: "--profile qdrant"
          up-flags: "--build"

      - name: Install the latest version of uv
@@ -1,3 +1,9 @@
+## v0.29.2 (2025-11-09)
+
+### Fix
+
+- **helm**: Set default strategy to Recreate
+
 ## v0.29.1 (2025-11-09)

 ### Fix
@@ -391,7 +391,3 @@ docker compose exec app php occ user_oidc:provider keycloak
 - `docs/configuration.md` - Configuration options
 - `docs/authentication.md` - Authentication modes
 - `docs/running.md` - Running the server
-
-**For additional information regarding MCP during development, see**:
- `../../Software/modelcontextprotocol/` - MCP spec
- `../../Software/python-sdk/` - Python MCP SDK
@@ -2,134 +2,286 @@

 [![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)

-**A production-ready MCP server that connects AI assistants to your Nextcloud instance.**
+**Enable AI assistants to interact with your Nextcloud instance.**

-Enable Large Language Models like Claude, GPT, and Gemini to interact with your Nextcloud data through a secure API. Create notes, manage calendars, organize contacts, work with files, and more - all through natural language conversations.
-
-This is a **dedicated standalone MCP server** designed for external MCP clients like Claude Code and IDEs. It runs independently of Nextcloud (Docker, VM, Kubernetes, or local) and provides deep CRUD operations across Nextcloud apps.
+The Nextcloud MCP (Model Context Protocol) server allows Large Language Models like Claude, GPT, and Gemini to interact with your Nextcloud data through a secure API. Create notes, manage calendars, organize contacts, work with files, and more - all through natural language.

 > [!NOTE]
-> **Looking for AI features inside Nextcloud?** Nextcloud also provides [Context Agent](https://github.com/nextcloud/context_agent), which powers the Assistant app and runs as an ExApp inside Nextcloud. See [docs/comparison-context-agent.md](docs/comparison-context-agent.md) for a detailed comparison of use cases.
+> **Nextcloud has two ways to enable AI access:** Nextcloud provides [Context Agent](https://github.com/nextcloud/context_agent), an AI agent backend that powers the [Assistant](https://github.com/nextcloud/assistant) app and allows AI to interact with Nextcloud apps like Calendar, Talk, and Contacts. Context Agent runs as an ExApp inside Nextcloud and also _[exposes an MCP server](https://docs.nextcloud.com/server/stable/admin_manual/ai/app_context_agent.html#using-nextcloud-mcp-server)_ for external MCP clients.
+>
+> This project (Nextcloud MCP Server) is a **dedicated standalone MCP server** designed specifically for external MCP clients like Claude Code and IDEs, with deep CRUD operations and OAuth support. It does not require any additional AI-features to be enabled in Nextcloud beyond the apps that you intend to interact with.

-## Quick Start
+### High-level Comparison: Nextcloud MCP Server vs. Nextcloud AI Stack

-Get up and running in 60 seconds using Docker:
+| Aspect | **Nextcloud MCP Server**<br/>(This Project) | **Nextcloud AI Stack**<br/>(Assistant + Context Agent) |
+|--------|---------------------------------------------|--------------------------------------------------------|
+| **Purpose** | External MCP client access to Nextcloud | AI assistance within Nextcloud UI |
+| **Deployment** | Standalone (Docker, VM, K8s) | Inside Nextcloud (ExApp via AppAPI) |
+| **Primary Users** | Claude Code, IDEs, external developers | Nextcloud end users via Assistant app |
+| **Authentication** | OAuth2/OIDC or Basic Auth | Session-based (integrated) |
+| **Notes Support** | ✅ Full CRUD + keyword search (7 tools) | ❌ Not implemented |
+| **Semantic Search** | ✅ Multi-app vector search (2+ tools) | ❌ Not implemented |
+| **Calendar** | ✅ Full CalDAV + tasks (20+ tools) | ✅ Events, free/busy, tasks (4 tools) |
+| **Contacts** | ✅ Full CardDAV (8 tools) | ✅ Find person, current user (2 tools) |
+| **Files (WebDAV)** | ✅ Full filesystem access (12 tools) | ✅ Read, folder tree, sharing (3 tools) |
+| **Document Processing** | ✅ OCR with progress (PDF, DOCX, images) | ❌ Not implemented |
+| **Deck** | ✅ Full project management (15 tools) | ✅ Basic board/card ops (2 tools) |
+| **Tables** | ✅ Row operations (5 tools) | ❌ Not implemented |
+| **Cookbook** | ✅ Full recipe management (13 tools) | ❌ Not implemented |
+| **Talk** | ❌ Not implemented | ✅ Messages, conversations (4 tools) |
+| **Mail** | ❌ Not implemented | ✅ Send email (2 tools) |
+| **AI Features** | ❌ Not implemented | ✅ Image gen, transcription, doc gen (4 tools) |
+| **Web/Maps** | ❌ Not implemented | ✅ Search, weather, transit (5 tools) |
+| **MCP Resources** | ✅ Structured data URIs | ❌ Not supported |
+| **External MCP** | ❌ Pure server | ✅ Consumes external MCP servers |
+| **Safety Model** | Client-controlled | Built-in safe/dangerous distinction |
+| **Best For** | • Deep CRUD operations<br/>• External integrations<br/>• OAuth security<br/>• IDE/editor integration | • AI-driven actions in Nextcloud UI<br/>• Multi-service orchestration<br/>• User task automation<br/>• MCP aggregation hub |

-```bash
-# 1. Create a minimal configuration
-cat > .env << EOF
-NEXTCLOUD_HOST=https://your.nextcloud.instance.com
-NEXTCLOUD_USERNAME=your_username
-NEXTCLOUD_PASSWORD=your_app_password
-EOF
-
-# 2. Start the server
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
-
-# 3. Test the connection
-curl http://127.0.0.1:8000/health/ready
-```
-
-**Next Steps:**
- Create an app password in Nextcloud: Settings → Security → Devices & sessions
- Connect your MCP client (Claude Desktop, IDEs, `mcp dev`, etc.)
- See [docs/installation.md](docs/installation.md) for other deployment options (local, Kubernetes)
-
-## Key Features
-
- **90+ MCP Tools** - Comprehensive API coverage across 8 Nextcloud apps
- **MCP Resources** - Structured data URIs for browsing Nextcloud data
- **Semantic Search (Experimental)** - Optional vector-powered search for Notes (requires Qdrant + Ollama)
- **Document Processing** - OCR and text extraction from PDFs, DOCX, images with progress notifications
- **Flexible Deployment** - Docker, Kubernetes (Helm), VM, or local installation
- **Production-Ready Auth** - Basic Auth with app passwords (recommended) or OAuth2/OIDC (experimental)
- **Multiple Transports** - SSE, HTTP, and streamable-http support
-
-## Supported Apps
-
-| App | Tools | Capabilities |
-|-----|-------|--------------|
-| **Notes** | 7 | Full CRUD, keyword search, semantic search |
-| **Calendar** | 20+ | Events, todos (tasks), recurring events, attendees, availability |
-| **Contacts** | 8 | Full CardDAV support, address books |
-| **Files (WebDAV)** | 12 | Filesystem access, OCR/document processing |
-| **Deck** | 15 | Boards, stacks, cards, labels, assignments |
-| **Cookbook** | 13 | Recipe management, URL import (schema.org) |
-| **Tables** | 5 | Row operations on Nextcloud Tables |
-| **Sharing** | 10+ | Create and manage shares |
-| **Semantic Search** | 2+ | Vector search for Notes (experimental, opt-in, requires infrastructure) |
+See our [detailed comparison](docs/comparison-context-agent.md) for architecture diagrams, workflow examples, and guidance on when to use each approach.

 Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request!

-## Authentication
+### Authentication
+
+| Mode | Security | Best For |
+|------|----------|----------|
+| **OAuth2/OIDC** ⚠️ **Experimental** | 🔒 High | Testing, evaluation (requires patch for app-specific APIs) |
+| **Basic Auth** ✅ | Lower | Development, testing, production |

 > [!IMPORTANT]
-> **OAuth2/OIDC is experimental** and requires a manual patch to the `user_oidc` app:
-> - **Required patch**: Bearer token support ([issue #1221](https://github.com/nextcloud/user_oidc/issues/1221))
-> - **Impact**: Without the patch, most app-specific APIs fail with 401 errors
-> - **Recommendation**: Use Basic Auth for production until upstream patches are merged
+> **OAuth is experimental** and requires a manual patch to the `user_oidc` app for full functionality:
+> - **Required patch**: `user_oidc` app needs modifications for Bearer token support ([issue #1221](https://github.com/nextcloud/user_oidc/issues/1221))
+> - **Impact**: Without the patch, most app-specific APIs (Notes, Calendar, Contacts, Deck, etc.) will fail with 401 errors
+> - **What works without patches**: OAuth flow, PKCE support (with `oidc` v1.10.0+), OCS APIs
+> - **Production use**: Wait for upstream patch to be merged into official releases
 >
-> See [docs/oauth-upstream-status.md](docs/oauth-upstream-status.md) for patch status and workarounds.
+> See [OAuth Upstream Status](docs/oauth-upstream-status.md) for detailed information on required patches and workarounds.

-**Recommended:** Basic Auth with app-specific passwords provides secure, production-ready authentication. See [docs/authentication.md](docs/authentication.md) for setup details and OAuth configuration.
+OAuth2/OIDC provides secure, per-user authentication with access tokens. See [Authentication Guide](docs/authentication.md) for details.

-### Authentication Modes
+## Quick Start

-The server supports two authentication modes:
+### 1. Install

-**Single-User Mode (BasicAuth):**
- One set of credentials shared by all MCP clients
- Simple setup: username + app password in environment variables
- All clients access Nextcloud as the same user
- Best for: Personal use, development, single-user deployments
+```bash
+# Clone the repository
+git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
+cd nextcloud-mcp-server

-**Multi-User Mode (OAuth):**
- Each MCP client authenticates separately with their own Nextcloud account
- Per-user scopes and permissions (clients only see tools they're authorized for)
- More secure: tokens expire, credentials never shared with server
- Best for: Teams, multi-user deployments, production environments with multiple users
+# Install with uv (recommended)
+uv sync

-See [docs/authentication.md](docs/authentication.md) for detailed setup instructions.
+# Or using Docker
+docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest

-## Semantic Search
+# Or deploy to Kubernetes with Helm
+helm repo add nextcloud-mcp https://cbcoutinho.github.io/nextcloud-mcp-server
+helm repo update
+helm install nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server \
+  --set nextcloud.host=https://cloud.example.com \
+  --set auth.basic.username=myuser \
+  --set auth.basic.password=mypassword
+```

-The server provides an experimental RAG pipeline to enable _Semantic Search_ that enables MCP clients to find information in Nextcloud based on **meaning** rather than just keywords. Instead of matching "machine learning" only when those exact words appear, it understands that "neural networks," "AI models," and "deep learning" are semantically related concepts.
+See [Installation Guide](docs/installation.md) for detailed instructions, or [Helm Chart README](charts/nextcloud-mcp-server/README.md) for Kubernetes deployment.

-**Example:**
- **Keyword search**: Query "car" only finds notes containing "car"
- **Semantic search**: Query "car" also finds notes about "automobile," "vehicle," "sedan," "transportation"
+### 2. Configure

-This enables natural language queries and helps discover related content across your Nextcloud notes.
+Create a `.env` file:

-> [!NOTE]
-> **Semantic Search is experimental and opt-in:**
-> - Disabled by default (`VECTOR_SYNC_ENABLED=false`)
-> - Currently supports Notes app only (multi-app support planned)
-> - Requires additional infrastructure: vector database + embedding service
-> - Answer generation (`nc_semantic_search_answer`) requires MCP client sampling support
->
-> See [docs/semantic-search-architecture.md](docs/semantic-search-architecture.md) for architecture details and [docs/configuration.md](docs/configuration.md) for setup instructions.
+```bash
+# Copy the sample
+cp env.sample .env
+```
+
+**For Basic Auth (recommended for most users):**
+```dotenv
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+NEXTCLOUD_USERNAME=your_username
+NEXTCLOUD_PASSWORD=your_app_password
+```
+
+**For OAuth (experimental - requires patches):**
+```dotenv
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+```
+
+See [Configuration Guide](docs/configuration.md) for all options.
+
+### 3. Set Up Authentication
+
+**Basic Auth Setup (recommended):**
+1. Create an app password in Nextcloud (Settings → Security → Devices & sessions)
+2. Add credentials to `.env` file
+3. Start the server
+
+**OAuth Setup (experimental):**
+1. Install Nextcloud OIDC apps (`oidc` v1.10.0+ + `user_oidc`)
+2. **Apply required patch** to `user_oidc` app for Bearer token support (see [OAuth Upstream Status](docs/oauth-upstream-status.md))
+3. Enable dynamic client registration or create an OIDC client with id & secret
+4. Configure Bearer token validation in `user_oidc`
+5. Start the server
+
+See [OAuth Quick Start](docs/quickstart-oauth.md) for 5-minute setup or [OAuth Setup Guide](docs/oauth-setup.md) for detailed instructions.
+
+### 4. Run the Server
+
+```bash
+# Load environment variables
+export $(grep -v '^#' .env | xargs)
+
+# Start with Basic Auth (default)
+uv run nextcloud-mcp-server
+
+# Or start with OAuth (experimental - requires patches)
+uv run nextcloud-mcp-server --oauth
+
+# Or with Docker
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+The server starts on `http://127.0.0.1:8000` by default.
+
+See [Running the Server](docs/running.md) for more options.
+
+### 5. Connect an MCP Client
+
+Test with MCP Inspector:
+
+```bash
+uv run mcp dev
+```
+
+Or connect from:
+- Claude Desktop
+- Any MCP-compatible client

 ## Documentation

 ### Getting Started
- **[Installation](docs/installation.md)** - Docker, Kubernetes, local, or VM deployment
- **[Configuration](docs/configuration.md)** - Environment variables and advanced options
- **[Authentication](docs/authentication.md)** - Basic Auth vs OAuth2/OIDC setup
- **[Running the Server](docs/running.md)** - Start, manage, and troubleshoot
+- **[Installation](docs/installation.md)** - Install the server
+- **[Configuration](docs/configuration.md)** - Environment variables and settings
+- **[Authentication](docs/authentication.md)** - OAuth vs BasicAuth
+- **[Running the Server](docs/running.md)** - Start and manage the server

-### 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)
+### Architecture
+- **[Comparison with Context Agent](docs/comparison-context-agent.md)** - How this MCP server differs from Nextcloud's Context Agent

-### Advanced Topics
- **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works (experimental)
- **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute OAuth setup
- **[OAuth Setup Guide](docs/oauth-setup.md)** - Detailed OAuth configuration
+### OAuth Documentation (Experimental)
+- **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute setup guide
+- **[OAuth Setup Guide](docs/oauth-setup.md)** - Detailed setup instructions
+- **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works
+- **[OAuth Troubleshooting](docs/oauth-troubleshooting.md)** - OAuth-specific issues
+- **[Upstream Status](docs/oauth-upstream-status.md)** - **Required patches and PRs** ⚠️
+
+### Reference
 - **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
- **[Comparison with Context Agent](docs/comparison-context-agent.md)** - When to use each approach
+
+### App-Specific Documentation
+- [Notes API](docs/notes.md)
+- [Calendar (CalDAV)](docs/calendar.md)
+- [Contacts (CardDAV)](docs/contacts.md)
+- [Cookbook](docs/cookbook.md)
+- [Deck](docs/deck.md)
+- [Tables](docs/table.md)
+- [WebDAV](docs/webdav.md)
+
+## MCP Tools & Resources
+
+The server exposes Nextcloud functionality through MCP tools (for actions) and resources (for data browsing).
+
+### Tools
+
+The server provides 90+ tools across 8 Nextcloud apps. When using OAuth, tools are dynamically filtered based on your granted scopes.
+
+For a complete list of all supported OAuth scopes and their descriptions, see [OAuth Scopes Documentation](docs/oauth-architecture.md#oauth-scopes).
+
+#### Available Tool Categories
+
+| App | Tools | Read Scope | Write Scope | Operations |
+|-----|-------|-----------|-------------|------------|
+| **Notes** | 7 | `notes:read` | `notes:write` | Create, read, update, delete, search notes (keyword search) |
+| **Calendar** | 20+ | `calendar:read` `todo:read`  | `calendar:write` `todo:write`   | Events, todos (tasks), calendars, recurring events, attendees |
+| **Contacts** | 8 | `contacts:read` | `contacts:write` | Create, read, update, delete contacts and address books |
+| **Files (WebDAV)** | 12 | `files:read` | `files:write` | List, read, upload, delete, move files; **OCR/document processing** |
+| **Deck** | 15 | `deck:read` | `deck:write` | Boards, stacks, cards, labels, assignments |
+| **Cookbook** | 13 | `cookbook:read` | `cookbook:write` | Recipes, import from URLs, search, categories |
+| **Tables** | 5 | `tables:read` | `tables:write` | Row operations on Nextcloud Tables |
+| **Sharing** | 10+ | `sharing:read` | `sharing:write` | Create, manage, delete shares |
+| **Semantic Search** | 2+ | `semantic:read` | `semantic:write` | Vector-powered semantic search across **all apps** (notes, calendar, deck, files, contacts), background indexing |
+
+#### Document Processing (Optional)
+
+The WebDAV file reading tool (`nc_webdav_read_file`) supports **automatic text extraction** from documents and images:
+
+**Supported Formats:**
+- **Documents**: PDF, DOCX, PPTX, XLSX, RTF, ODT, EPUB
+- **Images**: PNG, JPEG, TIFF, BMP (with OCR)
+- **Email**: EML, MSG files
+
+**Features:**
+- **Progress Notifications**: Long-running OCR operations (up to 120s) send progress updates every 10 seconds to prevent client timeouts
+- **Pluggable Architecture**: Multiple processor backends (Unstructured.io, Tesseract, custom HTTP APIs)
+- **Automatic Detection**: Files are processed based on MIME type
+- **Graceful Fallback**: Returns base64-encoded content if processing fails
+
+**Configuration:**
+```dotenv
+# Enable document processing (optional)
+ENABLE_DOCUMENT_PROCESSING=true
+
+# Unstructured.io processor (cloud/API-based, supports many formats)
+ENABLE_UNSTRUCTURED=true
+UNSTRUCTURED_API_URL=http://localhost:8002
+UNSTRUCTURED_STRATEGY=auto  # auto, fast, or hi_res
+UNSTRUCTURED_LANGUAGES=eng,deu
+PROGRESS_INTERVAL=10  # Progress update interval in seconds
+
+# Tesseract processor (local OCR, images only)
+ENABLE_TESSERACT=false
+TESSERACT_LANG=eng
+
+# Custom HTTP processor
+ENABLE_CUSTOM_PROCESSOR=false
+CUSTOM_PROCESSOR_URL=http://localhost:9000/process
+CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg
+```
+
+**Example Usage:**
+```
+AI: "Read the contents of Documents/report.pdf"
+→ Uses nc_webdav_read_file tool with automatic OCR processing
+→ Returns extracted text with parsing metadata
+→ Sends progress updates during long operations
+```
+
+See [env.sample](env.sample) for complete configuration options.
+
+**Example Tools:**
+- `nc_notes_create_note` - Create a new note
+- `nc_cookbook_import_recipe` - Import recipes from URLs with schema.org metadata
+- `deck_create_card` - Create a Deck card
+- `nc_calendar_create_event` - Create a calendar event
+- `nc_calendar_create_todo` - Create a CalDAV task/todo
+- `nc_contacts_create_contact` - Create a contact
+- `nc_webdav_upload_file` - Upload a file to Nextcloud
+- And 80+ more...
+
+> [!TIP]
+> **OAuth Scope Filtering**: When connecting via OAuth, MCP clients will only see tools for which you've granted access. For example, granting only `notes:read` and `notes:write` will show 7 Notes tools instead of all 90+ tools. See [OAuth Scopes Documentation](docs/oauth-architecture.md#oauth-scopes) for the complete scope reference, or [OAuth Troubleshooting - Limited Scopes](docs/oauth-troubleshooting.md#limited-scopes---only-seeing-notes-tools) if you're only seeing a subset of tools.
+>
+> **Known Issue**: Claude Code and some other MCP clients may only request/grant Notes scopes during initial connection. Track progress at [#234](https://github.com/cbcoutinho/nextcloud-mcp-server/issues/234).
+
+### Resources
+Resources provide read-only access to Nextcloud data:
+- `nc://capabilities` - Server capabilities
+- `cookbook://version` - Cookbook app version info
+- `nc://Deck/boards/{board_id}` - Deck board data
+- `notes://settings` - Notes app settings
+- And more...
+
+Run `uv run nextcloud-mcp-server --help` to see all available options.

 ## Examples

@@ -139,31 +291,45 @@ AI: "Create a note called 'Meeting Notes' with today's agenda"
 → Uses nc_notes_create_note tool
 ```

-### Import Recipes
+### Manage Recipes
 ```
-AI: "Import the recipe from https://www.example.com/recipe/chocolate-cake"
-→ Uses nc_cookbook_import_recipe tool with schema.org metadata extraction
+AI: "Import the recipe from this URL: https://www.example.com/recipe/chocolate-cake"
+→ Uses nc_cookbook_import_recipe tool to extract schema.org metadata
 ```

-### Schedule Meetings
+### Manage Calendar
 ```
 AI: "Schedule a team meeting for next Tuesday at 2pm"
 → Uses nc_calendar_create_event tool
 ```

-### Manage Files
+### Organize Files
 ```
 AI: "Create a folder called 'Project X' and move all PDFs there"
-→ Uses nc_webdav_create_directory and nc_webdav_move tools
+→ Uses WebDAV tools (nc_webdav_create_directory, nc_webdav_move)
 ```

-### Semantic Search (Experimental, Opt-in)
+### Project Management
 ```
-AI: "Find notes related to machine learning concepts"
-→ Uses nc_semantic_search to find semantically similar notes (requires Qdrant + Ollama setup)
+AI: "Create a new Deck board for Q1 planning with Todo, In Progress, and Done stacks"
+→ Uses deck_create_board and deck_create_stack tools
 ```

-**Note:** For AI-generated answers with citations, use `nc_semantic_search_answer` (requires MCP client with sampling support).
+## Transport Protocols
+
+The server supports multiple MCP transport protocols:
+
+- **streamable-http** (recommended) - Modern streaming protocol
+- **sse** (default, deprecated) - Server-Sent Events for backward compatibility
+- **http** - Standard HTTP protocol
+
+```bash
+# Use streamable-http (recommended)
+uv run nextcloud-mcp-server --transport streamable-http
+```
+
+> [!WARNING]
+> SSE transport is deprecated and will be removed in a future MCP specification version. Please migrate to `streamable-http`.

 ## Contributing

@@ -171,17 +337,17 @@ Contributions are welcome!

 - Report bugs or request features: [GitHub Issues](https://github.com/cbcoutinho/nextcloud-mcp-server/issues)
 - Submit improvements: [Pull Requests](https://github.com/cbcoutinho/nextcloud-mcp-server/pulls)
- Development guidelines: [CLAUDE.md](CLAUDE.md)
+- Read [CLAUDE.md](CLAUDE.md) for development guidelines

 ## Security

 [![MseeP.ai Security Assessment](https://mseep.net/pr/cbcoutinho-nextcloud-mcp-server-badge.png)](https://mseep.ai/app/cbcoutinho-nextcloud-mcp-server)

 This project takes security seriously:
- Production-ready Basic Auth with app-specific passwords
- OAuth2/OIDC support (experimental, requires upstream patches)
+- OAuth2/OIDC support (experimental - requires upstream patches)
+- Basic Auth with app-specific passwords (recommended)
+- No credential storage with OAuth mode
 - Per-user access tokens
- No credential storage in OAuth mode
 - Regular security assessments

 Found a security issue? Please report it privately to the maintainers.
@@ -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.29.1
-appVersion: "0.29.1"
+version: 0.29.2
+appVersion: "0.29.2"
 keywords:
  - nextcloud
  - mcp
@@ -219,19 +219,6 @@ Enable semantic search capabilities by deploying a vector database (Qdrant) and
 | `vectorSync.processorWorkers` | Number of concurrent processor workers | `3` |
 | `vectorSync.queueMaxSize` | Maximum queue size for pending documents | `10000` |

-**Document Chunking Configuration:**
-
-| Parameter | Description | Default |
-|-----------|-------------|---------|
-| `documentChunking.chunkSize` | Number of words per chunk for embedding | `512` |
-| `documentChunking.chunkOverlap` | Number of overlapping words between chunks | `50` |
-
-**Chunking Strategy:**
- **Small chunks (256-384)**: Better precision for searches, more storage overhead
- **Medium chunks (512-768)**: Balanced approach (recommended for most use cases)
- **Large chunks (1024+)**: Better context preservation, less precise matching
- **Overlap**: Should be 10-20% of chunk size to preserve context across boundaries
-
 **Qdrant Vector Database:**

 Qdrant is deployed as a subchart when `qdrant.enabled` is `true`. All configuration values are passed through to the [qdrant/qdrant](https://github.com/qdrant/qdrant-helm) chart.
@@ -158,11 +158,6 @@ spec:
            - name: VECTOR_SYNC_QUEUE_MAX_SIZE
              value: {{ .Values.vectorSync.queueMaxSize | quote }}
            {{- end }}
-            # Document Chunking (always set, used by vector sync processor)
-            - name: DOCUMENT_CHUNK_SIZE
-              value: {{ .Values.documentChunking.chunkSize | quote }}
-            - name: DOCUMENT_CHUNK_OVERLAP
-              value: {{ .Values.documentChunking.chunkOverlap | quote }}
            # Qdrant Vector Database
            {{- if eq .Values.qdrant.mode "network" }}
            # Network mode: Use dedicated Qdrant service
@@ -314,20 +314,6 @@ vectorSync:
  # Maximum queue size for documents pending indexing
  queueMaxSize: 10000

-# Document Chunking Configuration
-# Controls how documents are split into chunks before embedding
-# Only relevant when vectorSync.enabled is true
-documentChunking:
-  # Number of words per chunk (default: 512)
-  # Smaller chunks (256-384): Better for precise searches, more chunks to store
-  # Medium chunks (512-768): Balanced approach (recommended for most use cases)
-  # Larger chunks (1024+): Better for context, less precise matching
-  chunkSize: 512
-  # Number of overlapping words between chunks (default: 50)
-  # Recommended: 10-20% of chunkSize for context preservation across boundaries
-  # Must be less than chunkSize
-  chunkOverlap: 50
-
 # Qdrant Vector Database Configuration
 # Three deployment modes available:
 # 1. Local In-Memory: Fast, ephemeral, zero-config (mode: "memory")
@@ -88,34 +88,22 @@ services:
      - VECTOR_SYNC_SCAN_INTERVAL=10
      - VECTOR_SYNC_PROCESSOR_WORKERS=1

-      - LOG_FORMAT=text
+      - LOG_FORMAT=json

      # Qdrant configuration (three modes):
      # 1. Network mode: Set QDRANT_URL=http://qdrant:6333 (requires qdrant service)
      # 2. In-memory mode: Set QDRANT_LOCATION=:memory: (default if nothing set)
      # 3. Persistent local: Set QDRANT_LOCATION=/app/data/qdrant (stored in mcp-data volume)
-      - QDRANT_LOCATION=":memory:"  # In-memory mode for CI/testing (no external service required)
-      #- QDRANT_URL=http://qdrant:6333  # Uncomment for network mode
-      #- QDRANT_API_KEY=${QDRANT_API_KEY:-my_secret_api_key}  # Only for network mode
-
-      # Collection naming: Auto-generated as {deployment-id}-{model-name}
-      # - Deployment ID: OTEL_SERVICE_NAME (if set) or hostname (fallback)
-      # - Model name: OLLAMA_EMBEDDING_MODEL
-      # - Example: "nextcloud-mcp-server-nomic-embed-text"
-      # - Changing models creates new collection (requires re-embedding)
-      # - Set QDRANT_COLLECTION to override auto-generation:
+      - QDRANT_LOCATION=/app/data/qdrant
+      # - QDRANT_URL=http://qdrant:6333  # Uncomment for network mode
+      # - QDRANT_API_KEY=${QDRANT_API_KEY:-my_secret_api_key}  # Only for network mode
      - QDRANT_COLLECTION=nextcloud_content

      # Ollama configuration (optional - uses SimpleEmbeddingProvider if not set)
-      # - OLLAMA_BASE_URL=https://ollama.internal.coutinho.io:443
-      # - OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Changing this creates new collection
+      # - OLLAMA_BASE_URL=http://your-ollama-endpoint:port
+      # - OLLAMA_EMBEDDING_MODEL=nomic-embed-text
      # - OLLAMA_VERIFY_SSL=false

-      # Document chunking configuration (for vector embeddings)
-      # Tune these based on your embedding model and content type
-      # - DOCUMENT_CHUNK_SIZE=512      # Words per chunk (default: 512)
-      # - DOCUMENT_CHUNK_OVERLAP=50    # Overlapping words (default: 50, recommended: 10-20% of chunk size)
-
  mcp-oauth:
    build: .
    command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
@@ -219,7 +207,7 @@ services:
      - keycloak-oauth-storage:/app/.oauth

  qdrant:
-    image: qdrant/qdrant:v1.15.5
+    image: qdrant/qdrant:latest
    restart: always
    ports:
      - 127.0.0.1:6333:6333  # REST API
@@ -178,111 +178,6 @@ VECTOR_SYNC_ENABLED=true
 - Requires separate Qdrant service
 - More complex deployment

-### Qdrant Collection Naming
-
-Collection names are automatically generated to include the embedding model, ensuring safe model switching and preventing dimension mismatches.
-
-#### Auto-Generated Naming (Default)
-
-**Format:** `{deployment-id}-{model-name}`
-
-**Components:**
- **Deployment ID:** `OTEL_SERVICE_NAME` (if configured) or `hostname` (fallback)
- **Model name:** `OLLAMA_EMBEDDING_MODEL`
-
-**Examples:**
-
-```bash
-# With OTEL service name configured
-OTEL_SERVICE_NAME=my-mcp-server
-OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-# → Collection: "my-mcp-server-nomic-embed-text"
-
-# Simple Docker deployment (OTEL not configured)
-# hostname=mcp-container
-OLLAMA_EMBEDDING_MODEL=all-minilm
-# → Collection: "mcp-container-all-minilm"
-```
-
-#### Switching Embedding Models
-
-When you change `OLLAMA_EMBEDDING_MODEL`, a new collection is automatically created:
-
-```bash
-# Initial setup
-OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-# Collection: "my-server-nomic-embed-text" (768 dimensions)
-
-# Change model
-OLLAMA_EMBEDDING_MODEL=all-minilm
-# Collection: "my-server-all-minilm" (384 dimensions)
-# → New collection created, full re-embedding occurs
-```
-
-**Important:**
- **Collections are mutually exclusive** - vectors cannot be shared between different embedding models
- **Switching models requires re-embedding** all documents (may take time for large note collections)
- **Old collection remains** in Qdrant and can be deleted manually if no longer needed
-
-#### Explicit Override
-
-Set `QDRANT_COLLECTION` to use a specific collection name:
-
-```bash
-QDRANT_COLLECTION=my-custom-collection  # Bypasses auto-generation
-```
-
-**Use cases:**
- Backward compatibility with existing deployments
- Custom naming schemes
- Sharing a collection across deployments (advanced)
-
-#### Multi-Server Deployments
-
-Each server should have a unique deployment ID to avoid collection collisions:
-
-```bash
-# Server 1 (Production)
-OTEL_SERVICE_NAME=mcp-prod
-OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-# → Collection: "mcp-prod-nomic-embed-text"
-
-# Server 2 (Staging)
-OTEL_SERVICE_NAME=mcp-staging
-OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-# → Collection: "mcp-staging-nomic-embed-text"
-
-# Server 3 (Different model)
-OTEL_SERVICE_NAME=mcp-experimental
-OLLAMA_EMBEDDING_MODEL=bge-large
-# → Collection: "mcp-experimental-bge-large"
-```
-
-**Benefits:**
- Multiple MCP servers can share one Qdrant instance safely
- No naming collisions between deployments
- Clear collection ownership (can see which deployment and model)
-
-#### Dimension Validation
-
-The server validates collection dimensions on startup:
-
-```
-Dimension mismatch for collection 'my-server-nomic-embed-text':
-  Expected: 384 (from embedding model 'all-minilm')
-  Found: 768
-This usually means you changed the embedding model.
-Solutions:
-  1. Delete the old collection: Collection will be recreated with new dimensions
-  2. Set QDRANT_COLLECTION to use a different collection name
-  3. Revert OLLAMA_EMBEDDING_MODEL to the original model
-```
-
-**What this prevents:**
- Runtime errors from dimension mismatches
- Data corruption in Qdrant
- Confusing error messages during indexing
-
 ### Vector Sync Configuration

 Control background indexing behavior:
@@ -293,10 +188,6 @@ VECTOR_SYNC_ENABLED=true              # Enable background indexing
 VECTOR_SYNC_SCAN_INTERVAL=300         # Scan interval in seconds (default: 5 minutes)
 VECTOR_SYNC_PROCESSOR_WORKERS=3       # Concurrent indexing workers (default: 3)
 VECTOR_SYNC_QUEUE_MAX_SIZE=10000      # Max queued documents (default: 10000)
-
-# Document chunking settings (for vector embeddings)
-DOCUMENT_CHUNK_SIZE=512               # Words per chunk (default: 512)
-DOCUMENT_CHUNK_OVERLAP=50             # Overlapping words between chunks (default: 50)
 ```

 ### Embedding Service Configuration
@@ -317,54 +208,6 @@ OLLAMA_VERIFY_SSL=true                   # Verify SSL certificates

 If `OLLAMA_BASE_URL` is not set, the server uses a simple random embedding provider for testing. This is **not suitable for production** as it generates random embeddings with no semantic meaning.

-### Document Chunking Configuration
-
-The server chunks documents before embedding to handle documents larger than the embedding model's context window. Chunk size and overlap can be tuned based on your embedding model and content type.
-
-#### Choosing Chunk Size
-
-**Smaller chunks (256-384 words)**:
- More precise matching
- Less context per chunk
- Better for finding specific information
- Higher storage requirements (more vectors)
-
-**Larger chunks (768-1024 words)**:
- More context per chunk
- Less precise matching
- Better for understanding broader topics
- Lower storage requirements (fewer vectors)
-
-**Default (512 words)**:
- Balanced approach suitable for most use cases
- Works well with typical note lengths
- Good compromise between precision and context
-
-#### Choosing Overlap
-
-Overlap preserves context across chunk boundaries. Recommended settings:
-
- **10-20% of chunk size** (e.g., 50-100 words for 512-word chunks)
- **Too small** (<10%): May lose context at boundaries
- **Too large** (>20%): Redundant storage, diminishing returns
-
-**Examples**:
-```dotenv
-# Precise matching for short notes
-DOCUMENT_CHUNK_SIZE=256
-DOCUMENT_CHUNK_OVERLAP=25
-
-# Default balanced configuration
-DOCUMENT_CHUNK_SIZE=512
-DOCUMENT_CHUNK_OVERLAP=50
-
-# More context for long documents
-DOCUMENT_CHUNK_SIZE=1024
-DOCUMENT_CHUNK_OVERLAP=100
-```
-
-**Important**: Changing chunk size requires re-embedding all documents. The collection naming strategy (see "Qdrant Collection Naming" above) helps manage this by creating separate collections for different configurations.
-
 ### Environment Variables Reference

 | Variable | Required | Default | Description |
@@ -380,8 +223,6 @@ DOCUMENT_CHUNK_OVERLAP=100
 | `OLLAMA_BASE_URL` | ⚠️ Optional | - | Ollama API endpoint for embeddings |
 | `OLLAMA_EMBEDDING_MODEL` | ⚠️ Optional | `nomic-embed-text` | Embedding model to use |
 | `OLLAMA_VERIFY_SSL` | ⚠️ Optional | `true` | Verify SSL certificates |
-| `DOCUMENT_CHUNK_SIZE` | ⚠️ Optional | `512` | Words per chunk for document embedding |
-| `DOCUMENT_CHUNK_OVERLAP` | ⚠️ Optional | `50` | Overlapping words between chunks (must be < chunk size) |

 ### Docker Compose Example

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

 # Comma-separated MIME types your processor supports
 #CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg,image/png
-
-# ============================================
-# Semantic Search & Vector Sync Configuration
-# ============================================
-# EXPERIMENTAL: Semantic search for Notes app (multi-app support planned)
-# Requires: Qdrant vector database + Ollama embedding service
-# Disabled by default
-
-# Enable background vector indexing
-VECTOR_SYNC_ENABLED=false
-
-# Document scan interval in seconds (default: 300 = 5 minutes)
-# How often to check for new/updated documents
-#VECTOR_SYNC_SCAN_INTERVAL=300
-
-# Concurrent indexing workers (default: 3)
-# Number of parallel workers for embedding generation
-#VECTOR_SYNC_PROCESSOR_WORKERS=3
-
-# Max queued documents (default: 10000)
-# Maximum documents waiting to be processed
-#VECTOR_SYNC_QUEUE_MAX_SIZE=10000
-
-# ============================================
-# Qdrant Vector Database Configuration
-# ============================================
-# Choose ONE of three modes:
-# 1. In-memory mode (default): Set neither QDRANT_URL nor QDRANT_LOCATION
-# 2. Persistent local: Set QDRANT_LOCATION=/path/to/data
-# 3. Network mode: Set QDRANT_URL=http://qdrant:6333
-
-# Network mode: URL to Qdrant service
-#QDRANT_URL=http://qdrant:6333
-
-# Local mode: Path to store vectors (use :memory: for in-memory)
-#QDRANT_LOCATION=:memory:
-
-# API key for network mode (optional)
-#QDRANT_API_KEY=
-
-# Collection name (optional - auto-generated if not set)
-# Auto-generation format: {deployment-id}-{model-name}
-# Allows safe model switching and multi-server deployments
-#QDRANT_COLLECTION=nextcloud_content
-
-# ============================================
-# Ollama Embedding Service Configuration
-# ============================================
-# Ollama endpoint for embeddings (if not set, uses SimpleEmbeddingProvider fallback)
-#OLLAMA_BASE_URL=http://ollama:11434
-
-# Embedding model to use (default: nomic-embed-text, 768 dimensions)
-# Changing this creates a new collection (requires re-embedding all documents)
-#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-
-# Verify SSL certificates (default: true)
-#OLLAMA_VERIFY_SSL=true
-
-# ============================================
-# Document Chunking Configuration
-# ============================================
-# Configure how documents are split before embedding
-
-# Words per chunk (default: 512)
-# Smaller chunks (256-384): More precise, less context, more storage
-# Larger chunks (768-1024): More context, less precise, less storage
-#DOCUMENT_CHUNK_SIZE=512
-
-# Overlapping words between chunks (default: 50)
-# Recommended: 10-20% of chunk size
-# Preserves context across chunk boundaries
-#DOCUMENT_CHUNK_OVERLAP=50
@@ -1379,7 +1379,7 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
        "Routes: /user/* with SessionAuth, /mcp with FastMCP OAuth Bearer tokens"
    )

-    # Add debugging middleware to log Authorization headers and client capabilities
+    # Add debugging middleware to log Authorization headers
    @app.middleware("http")
    async def log_auth_headers(request, call_next):
        auth_header = request.headers.get("authorization")
@@ -1394,52 +1394,6 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                logger.warning(
                    f"⚠️  /mcp request WITHOUT Authorization header from {request.client}"
                )
-
-            # Log client capabilities on initialize request
-            if request.method == "POST":
-                # Read body to check for initialize request
-                # Starlette caches the body internally, so it's safe to read here
-                body = await request.body()
-                try:
-                    import json
-
-                    data = json.loads(body)
-                    # Check if this is an initialize request
-                    if data.get("method") == "initialize":
-                        params = data.get("params", {})
-                        capabilities = params.get("capabilities", {})
-                        client_info = params.get("clientInfo", {})
-
-                        logger.info(
-                            f"🔌 MCP client connected: {client_info.get('name', 'unknown')} "
-                            f"v{client_info.get('version', 'unknown')}"
-                        )
-
-                        # Log capabilities in a structured way
-                        cap_summary = []
-                        # Check for presence using 'in' not truthiness (empty dict {} counts as having capability)
-                        if "roots" in capabilities:
-                            cap_summary.append("roots")
-                        if "sampling" in capabilities:
-                            cap_summary.append("sampling")
-                        if "experimental" in capabilities:
-                            cap_summary.append(
-                                f"experimental({len(capabilities['experimental'])} features)"
-                            )
-
-                        logger.info(
-                            f"📋 Client capabilities: {', '.join(cap_summary) if cap_summary else 'none'}"
-                        )
-                        # Log full capabilities at INFO level to diagnose capability issues
-                        logger.info(
-                            f"Full capabilities JSON: {json.dumps(capabilities)}"
-                        )
-                except Exception as e:
-                    # Don't fail the request if logging fails
-                    logger.debug(
-                        f"Failed to parse MCP request for capability logging: {e}"
-                    )
-
        response = await call_next(request)
        return response

@@ -43,17 +43,14 @@ async def _get_processing_status(request: Request) -> dict[str, Any] | None:
        return None

    try:
-        # Get document receive stream from app state
-        document_receive_stream = getattr(
-            request.app.state, "document_receive_stream", None
-        )
-        if document_receive_stream is None:
-            logger.debug("document_receive_stream not available in app state")
+        # Get document queue from app state
+        document_queue = getattr(request.app.state, "document_queue", None)
+        if document_queue is None:
+            logger.debug("document_queue not available in app state")
            return None

-        # Get pending count from stream statistics
-        stats = document_receive_stream.statistics()
-        pending_count = stats.current_buffer_used
+        # Get pending count from queue
+        pending_count = document_queue.qsize()

        # Get Qdrant client and query indexed count
        indexed_count = 0
@@ -66,7 +63,7 @@ async def _get_processing_status(request: Request) -> dict[str, Any] | None:

            # Count documents in collection
            count_result = await qdrant_client.count(
-                collection_name=settings.get_collection_name()
+                collection_name=settings.qdrant_collection
            )
            indexed_count = count_result.count

@@ -174,10 +174,6 @@ class Settings:
    ollama_embedding_model: str = "nomic-embed-text"
    ollama_verify_ssl: bool = True

-    # Document chunking settings (for vector embeddings)
-    document_chunk_size: int = 512  # Words per chunk
-    document_chunk_overlap: int = 50  # Overlapping words between chunks
-
    # Observability settings
    metrics_enabled: bool = True
    metrics_port: int = 9090
@@ -213,65 +209,6 @@ class Settings:
                "API key is only relevant for network mode and will be ignored."
            )

-        # Validate chunking configuration
-        if self.document_chunk_overlap >= self.document_chunk_size:
-            raise ValueError(
-                f"DOCUMENT_CHUNK_OVERLAP ({self.document_chunk_overlap}) must be less than "
-                f"DOCUMENT_CHUNK_SIZE ({self.document_chunk_size}). "
-                f"Overlap should be 10-20% of chunk size for optimal results."
-            )
-
-        if self.document_chunk_size < 100:
-            logger.warning(
-                f"DOCUMENT_CHUNK_SIZE is set to {self.document_chunk_size} words, which is quite small. "
-                f"Smaller chunks may lose context. Consider using at least 256 words."
-            )
-
-        if self.document_chunk_overlap < 0:
-            raise ValueError(
-                f"DOCUMENT_CHUNK_OVERLAP ({self.document_chunk_overlap}) cannot be negative."
-            )
-
-    def get_collection_name(self) -> str:
-        """
-        Get Qdrant collection name.
-
-        Auto-generates from deployment ID + model name unless explicitly set.
-        Deployment ID uses OTEL_SERVICE_NAME if configured, otherwise hostname.
-
-        This enables:
-        - Safe embedding model switching (new model → new collection)
-        - Multi-server deployments (unique deployment IDs)
-        - Clear collection naming (shows deployment and model)
-
-        Format: {deployment-id}-{model-name}
-
-        Examples:
-            - "my-deployment-nomic-embed-text" (OTEL_SERVICE_NAME set)
-            - "mcp-container-all-minilm" (hostname fallback)
-
-        Returns:
-            Collection name string
-        """
-        import socket
-
-        # Use explicit override if user configured non-default value
-        if self.qdrant_collection != "nextcloud_content":
-            return self.qdrant_collection
-
-        # Determine deployment ID (OTEL service name or hostname fallback)
-        if self.otel_service_name != "nextcloud-mcp-server":  # Non-default
-            deployment_id = self.otel_service_name
-        else:
-            # Fallback to hostname for simple Docker deployments without OTEL config
-            deployment_id = socket.gethostname()
-
-        # Sanitize deployment ID and model name
-        deployment_id = deployment_id.lower().replace(" ", "-").replace("_", "-")
-        model_name = self.ollama_embedding_model.replace("/", "-").replace(":", "-")
-
-        return f"{deployment_id}-{model_name}"
-

 def get_settings() -> Settings:
    """Get application settings from environment variables.
@@ -328,9 +265,6 @@ def get_settings() -> Settings:
        ollama_base_url=os.getenv("OLLAMA_BASE_URL"),
        ollama_embedding_model=os.getenv("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text"),
        ollama_verify_ssl=os.getenv("OLLAMA_VERIFY_SSL", "true").lower() == "true",
-        # Document chunking settings
-        document_chunk_size=int(os.getenv("DOCUMENT_CHUNK_SIZE", "512")),
-        document_chunk_overlap=int(os.getenv("DOCUMENT_CHUNK_OVERLAP", "50")),
        # Observability settings
        metrics_enabled=os.getenv("METRICS_ENABLED", "true").lower() == "true",
        metrics_port=int(os.getenv("METRICS_PORT", "9090")),
@@ -17,32 +17,6 @@ from pythonjsonlogger import jsonlogger
 from nextcloud_mcp_server.observability.tracing import get_trace_context


-class HealthCheckFilter(logging.Filter):
-    """
-    Logging filter that excludes health check endpoint requests.
-
-    This prevents health check polls from cluttering logs while keeping
-    access logs for all other endpoints.
-    """
-
-    def filter(self, record: logging.LogRecord) -> bool:
-        """
-        Filter out health check requests from uvicorn access logs.
-
-        Args:
-            record: LogRecord instance
-
-        Returns:
-            False if this is a health check request, True otherwise
-        """
-        # Check if the log message contains health check endpoints
-        message = record.getMessage()
-        return not any(
-            endpoint in message
-            for endpoint in ["/health/live", "/health/ready", "/metrics"]
-        )
-
-
 class TraceContextFormatter(jsonlogger.JsonFormatter):
    """
    JSON formatter that injects OpenTelemetry trace context into log records.
@@ -270,23 +244,12 @@ def get_uvicorn_logging_config(
                "datefmt": "%Y-%m-%d %H:%M:%S",
            },
        },
-        "filters": {
-            "health_check_filter": {
-                "()": "nextcloud_mcp_server.observability.logging_config.HealthCheckFilter",
-            },
-        },
        "handlers": {
            "default": {
                "formatter": "default",
                "class": "logging.StreamHandler",
                "stream": "ext://sys.stdout",
            },
-            "access": {
-                "formatter": "default",
-                "class": "logging.StreamHandler",
-                "stream": "ext://sys.stdout",
-                "filters": ["health_check_filter"],
-            },
        },
        "loggers": {
            "": {
@@ -299,7 +262,7 @@ def get_uvicorn_logging_config(
                "propagate": False,
            },
            "uvicorn.access": {
-                "handlers": ["access"],
+                "handlers": ["default"],
                "level": "INFO",
                "propagate": False,
            },
@@ -68,25 +68,17 @@ def configure_semantic_tools(mcp: FastMCP):
        client = await get_client(ctx)
        username = client.username

-        logger.info(
-            f"Semantic search: query='{query}', user={username}, "
-            f"limit={limit}, score_threshold={score_threshold}"
-        )
-
        try:
            # Generate embedding for query
            embedding_service = get_embedding_service()
            query_embedding = await embedding_service.embed(query)
-            logger.debug(
-                f"Generated embedding for query (dimension={len(query_embedding)})"
-            )

            # Search Qdrant with user filtering
            # Note: Currently only searching notes (doc_type="note")
            # Future: Remove doc_type filter to search all apps
            qdrant_client = await get_qdrant_client()
            search_response = await qdrant_client.query_points(
-                collection_name=settings.get_collection_name(),
+                collection_name=settings.qdrant_collection,
                query=query_embedding,
                query_filter=Filter(
                    must=[
@@ -106,15 +98,6 @@ def configure_semantic_tools(mcp: FastMCP):
                with_vectors=False,  # Don't return vectors to save bandwidth
            )

-            logger.info(
-                f"Qdrant returned {len(search_response.points)} results "
-                f"(before deduplication and access verification)"
-            )
-            if search_response.points:
-                # Log top 3 scores to help with threshold tuning
-                top_scores = [p.score for p in search_response.points[:3]]
-                logger.debug(f"Top 3 similarity scores: {top_scores}")
-
            # Deduplicate by document ID (multiple chunks per document)
            seen_doc_ids = set()
            results = []
@@ -154,14 +137,9 @@ def configure_semantic_tools(mcp: FastMCP):
                    except HTTPStatusError as e:
                        if e.response.status_code == 403:
                            # User lost access, skip this document
-                            logger.debug(f"Skipping note {doc_id}: access denied (403)")
                            continue
                        elif e.response.status_code == 404:
                            # Document was deleted but not yet removed from vector DB
-                            logger.debug(
-                                f"Skipping note {doc_id}: not found (404), "
-                                f"likely deleted after indexing"
-                            )
                            continue
                        else:
                            # Log other errors but continue processing
@@ -170,16 +148,6 @@ def configure_semantic_tools(mcp: FastMCP):
                            )
                            continue

-            logger.info(
-                f"Returning {len(results)} results after deduplication and access verification"
-            )
-            if results:
-                result_details = [
-                    f"note_{r.id} (score={r.score:.3f}, title='{r.title}')"
-                    for r in results[:5]  # Show top 5
-                ]
-                logger.debug(f"Top results: {', '.join(result_details)}")
-
            return SemanticSearchResponse(
                results=results,
                query=query,
@@ -291,47 +259,7 @@ def configure_semantic_tools(mcp: FastMCP):
                success=True,
            )

-        # 3. Check if client supports sampling
-        from mcp.types import ClientCapabilities, SamplingCapability
-
-        client_has_sampling = ctx.session.check_client_capability(
-            ClientCapabilities(sampling=SamplingCapability())
-        )
-
-        # Log capability check result for debugging
-        logger.info(
-            f"Sampling capability check: client_has_sampling={client_has_sampling}, "
-            f"query='{query}'"
-        )
-        if hasattr(ctx.session, "_client_params") and ctx.session._client_params:
-            client_caps = ctx.session._client_params.capabilities
-            logger.debug(
-                f"Client advertised capabilities: "
-                f"roots={client_caps.roots is not None}, "
-                f"sampling={client_caps.sampling is not None}, "
-                f"experimental={client_caps.experimental is not None}"
-            )
-
-        if not client_has_sampling:
-            logger.info(
-                f"Client does not support sampling (query: '{query}'), "
-                f"returning {len(search_response.results)} documents"
-            )
-            return SamplingSearchResponse(
-                query=query,
-                generated_answer=(
-                    f"[Sampling not supported by client]\n\n"
-                    f"Your MCP client doesn't support answer generation. "
-                    f"Found {search_response.total_found} relevant documents. "
-                    f"Please review the sources below."
-                ),
-                sources=search_response.results,
-                total_found=search_response.total_found,
-                search_method="semantic_sampling_unsupported",
-                success=True,
-            )
-
-        # 4. Construct context from retrieved documents
+        # 3. Construct context from retrieved documents
        context_parts = []
        for idx, result in enumerate(search_response.results, 1):
            context_parts.append(
@@ -345,7 +273,7 @@ def configure_semantic_tools(mcp: FastMCP):

        context = "\n".join(context_parts)

-        # 5. Construct prompt - reuse user's query, add context and instructions
+        # 4. Construct prompt - reuse user's query, add context and instructions
        prompt = (
            f"{query}\n\n"
            f"Here are relevant documents from Nextcloud (notes, calendar events, deck cards, files, contacts):\n\n"
@@ -354,35 +282,31 @@ def configure_semantic_tools(mcp: FastMCP):
            f"Cite the document numbers when referencing specific information."
        )

-        logger.info(
-            f"Initiating sampling request: query_length={len(query)}, "
-            f"documents={len(search_response.results)}, "
-            f"prompt_length={len(prompt)}, max_tokens={max_answer_tokens}"
+        logger.debug(
+            f"Requesting sampling for query: {query} "
+            f"({len(search_response.results)} documents retrieved)"
        )

-        # 6. Request LLM completion via MCP sampling with timeout
-        import anyio
-
+        # 5. Request LLM completion via MCP sampling
        try:
-            with anyio.fail_after(30):
-                sampling_result = await ctx.session.create_message(
-                    messages=[
-                        SamplingMessage(
-                            role="user",
-                            content=TextContent(type="text", text=prompt),
-                        )
-                    ],
-                    max_tokens=max_answer_tokens,
-                    temperature=0.7,
-                    model_preferences=ModelPreferences(
-                        hints=[ModelHint(name="claude-3-5-sonnet")],
-                        intelligencePriority=0.8,
-                        speedPriority=0.5,
-                    ),
-                    include_context="thisServer",
-                )
+            sampling_result = await ctx.session.create_message(
+                messages=[
+                    SamplingMessage(
+                        role="user",
+                        content=TextContent(type="text", text=prompt),
+                    )
+                ],
+                max_tokens=max_answer_tokens,
+                temperature=0.7,
+                model_preferences=ModelPreferences(
+                    hints=[ModelHint(name="claude-3-5-sonnet")],
+                    intelligencePriority=0.8,
+                    speedPriority=0.5,
+                ),
+                include_context="thisServer",
+            )

-            # 7. Extract answer from sampling response
+            # 6. Extract answer from sampling response
            if sampling_result.content.type == "text":
                generated_answer = sampling_result.content.text
            else:
@@ -394,8 +318,7 @@ def configure_semantic_tools(mcp: FastMCP):

            logger.info(
                f"Sampling successful: model={sampling_result.model}, "
-                f"stop_reason={sampling_result.stopReason}, "
-                f"answer_length={len(generated_answer)}"
+                f"stop_reason={sampling_result.stopReason}"
            )

            return SamplingSearchResponse(
@@ -409,78 +332,23 @@ def configure_semantic_tools(mcp: FastMCP):
                success=True,
            )

-        except TimeoutError:
+        except Exception as e:
+            # Fallback: Return documents without generated answer
            logger.warning(
-                f"Sampling request timed out after 30 seconds for query: '{query}', "
+                f"Sampling failed ({type(e).__name__}: {e}), "
                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"Found {search_response.total_found} relevant documents. "
-                    f"Please review the sources below or try a simpler query."
-                ),
-                sources=search_response.results,
-                total_found=search_response.total_found,
-                search_method="semantic_sampling_timeout",
-                success=True,
-            )
-
-        except McpError as e:
-            # Expected MCP protocol errors (user rejection, unsupported, etc.)
-            error_msg = str(e)
-
-            if "rejected" in error_msg.lower() or "denied" in error_msg.lower():
-                # User explicitly declined - this is normal, not an error
-                logger.info(f"User declined sampling request for query: '{query}'")
-                search_method = "semantic_sampling_user_declined"
-                user_message = "User declined to generate an answer"
-            elif "not supported" in error_msg.lower():
-                # Client doesn't support sampling - also normal
-                logger.info(f"Sampling not supported by client for query: '{query}'")
-                search_method = "semantic_sampling_unsupported"
-                user_message = "Sampling not supported by this client"
-            else:
-                # Other MCP protocol errors
-                logger.warning(
-                    f"MCP error during sampling for query '{query}': {error_msg}"
-                )
-                search_method = "semantic_sampling_mcp_error"
-                user_message = f"Sampling unavailable: {error_msg}"

            return SamplingSearchResponse(
                query=query,
                generated_answer=(
-                    f"[{user_message}]\n\n"
+                    f"[Sampling unavailable: {str(e)}]\n\n"
                    f"Found {search_response.total_found} relevant documents. "
                    f"Please review the sources below."
                ),
                sources=search_response.results,
                total_found=search_response.total_found,
-                search_method=search_method,
-                success=True,
-            )
-
-        except Exception as e:
-            # Truly unexpected errors - these SHOULD have tracebacks
-            logger.error(
-                f"Unexpected error during sampling for query '{query}': "
-                f"{type(e).__name__}: {e}",
-                exc_info=True,
-            )
-
-            return SamplingSearchResponse(
-                query=query,
-                generated_answer=(
-                    f"[Unexpected error during sampling]\n\n"
-                    f"Found {search_response.total_found} relevant documents. "
-                    f"Please review the sources below."
-                ),
-                sources=search_response.results,
-                total_found=search_response.total_found,
-                search_method="semantic_sampling_error",
+                search_method="semantic_sampling_fallback",
                success=True,
            )

@@ -545,7 +413,7 @@ def configure_semantic_tools(mcp: FastMCP):

                # Count documents in collection
                count_result = await qdrant_client.count(
-                    collection_name=settings.get_collection_name()
+                    collection_name=settings.qdrant_collection
                )
                indexed_count = count_result.count

@@ -100,7 +100,7 @@ async def process_document(doc_task: DocumentTask, nc_client: NextcloudClient):
    # Handle deletion
    if doc_task.operation == "delete":
        await qdrant_client.delete(
-            collection_name=settings.get_collection_name(),
+            collection_name=settings.qdrant_collection,
            points_selector=Filter(
                must=[
                    FieldCondition(
@@ -170,11 +170,8 @@ async def _index_document(
    else:
        raise ValueError(f"Unsupported doc_type: {doc_task.doc_type}")

-    # Tokenize and chunk (using configured chunk size and overlap)
-    chunker = DocumentChunker(
-        chunk_size=settings.document_chunk_size,
-        overlap=settings.document_chunk_overlap,
-    )
+    # Tokenize and chunk
+    chunker = DocumentChunker(chunk_size=512, overlap=50)
    chunks = chunker.chunk_text(content)

    # Generate embeddings (I/O bound - external API call)
@@ -212,7 +209,7 @@ async def _index_document(

    # Upsert to Qdrant
    await qdrant_client.upsert(
-        collection_name=settings.get_collection_name(),
+        collection_name=settings.qdrant_collection,
        points=points,
        wait=True,
    )
@@ -59,57 +59,30 @@ async def get_qdrant_client() -> AsyncQdrantClient:
            logger.warning("No Qdrant mode configured, defaulting to :memory:")
            _qdrant_client = AsyncQdrantClient(":memory:")

-        # Get collection name (auto-generated from deployment ID + model)
-        collection_name = settings.get_collection_name()
+        # Ensure collection exists
+        collection_name = settings.qdrant_collection

        # Import here to avoid circular dependency
        from nextcloud_mcp_server.embedding import get_embedding_service

        embedding_service = get_embedding_service()
-        expected_dimension = embedding_service.get_dimension()
+        dimension = embedding_service.get_dimension()

        try:
-            # Get existing collection
-            collection_info = await _qdrant_client.get_collection(collection_name)
-            actual_dimension = collection_info.config.params.vectors.size
-
-            # Validate dimension matches
-            if actual_dimension != expected_dimension:
-                raise ValueError(
-                    f"Dimension mismatch for collection '{collection_name}':\n"
-                    f"  Expected: {expected_dimension} (from embedding model '{settings.ollama_embedding_model}')\n"
-                    f"  Found: {actual_dimension}\n"
-                    f"This usually means you changed the embedding model.\n"
-                    f"Solutions:\n"
-                    f"  1. Delete the old collection: Collection will be recreated with new dimensions\n"
-                    f"  2. Set QDRANT_COLLECTION to use a different collection name\n"
-                    f"  3. Revert OLLAMA_EMBEDDING_MODEL to the original model"
-                )
-
-            logger.info(
-                f"Using existing Qdrant collection: {collection_name} "
-                f"(dimension={actual_dimension}, model={settings.ollama_embedding_model})"
-            )
-
-        except Exception as e:
-            # Check if it's a dimension mismatch error (re-raise it)
-            if isinstance(e, ValueError) and "Dimension mismatch" in str(e):
-                raise
-
-            # Collection doesn't exist or other error, create it
+            await _qdrant_client.get_collection(collection_name)
+            logger.info(f"Using existing Qdrant collection: {collection_name}")
+        except Exception:
+            # Collection doesn't exist, create it
            await _qdrant_client.create_collection(
                collection_name=collection_name,
                vectors_config=VectorParams(
-                    size=expected_dimension,
+                    size=dimension,
                    distance=Distance.COSINE,
                ),
            )
            logger.info(
-                f"Created Qdrant collection: {collection_name}\n"
-                f"  Dimension: {expected_dimension}\n"
-                f"  Model: {settings.ollama_embedding_model}\n"
-                f"  Distance: COSINE\n"
-                f"Background sync will index all documents with this embedding model."
+                f"Created Qdrant collection: {collection_name} "
+                f"(dimension={dimension}, distance=COSINE)"
            )

    return _qdrant_client
@@ -96,7 +96,7 @@ async def scan_user_documents(
        nc_client: Authenticated Nextcloud client
        initial_sync: If True, send all documents (first-time sync)
    """
-    logger.debug(f"Scanning documents for user: {user_id}")
+    logger.info(f"Scanning documents for user: {user_id}")

    # Fetch all notes from Nextcloud
    notes = [note async for note in nc_client.notes.get_all_notes()]
@@ -127,7 +127,7 @@ async def scan_user_documents(
    # Get indexed state from Qdrant
    qdrant_client = await get_qdrant_client()
    scroll_result = await qdrant_client.scroll(
-        collection_name=get_settings().get_collection_name(),
+        collection_name=get_settings().qdrant_collection,
        scroll_filter=Filter(
            must=[
                FieldCondition(key="user_id", match=MatchValue(value=user_id)),
@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.29.1"
+version = "0.29.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"}
@@ -146,23 +146,12 @@ Avoid blocking operations in async code.""",
    assert "search_method" in result

    # For this test, sampling might fail (no real LLM client)
-    # So we check for either success or various fallback states
-    unsupported_methods = {
-        "semantic_sampling_unsupported",
-        "semantic_sampling_user_declined",
-        "semantic_sampling_timeout",
-        "semantic_sampling_mcp_error",
-        "semantic_sampling_fallback",
-    }
-
-    if result["search_method"] in unsupported_methods:
-        # Fallback/unsupported mode - should still have sources
+    # So we check for either success or fallback
+    if "[Sampling unavailable" in result["generated_answer"]:
+        # Fallback mode - should still have sources
+        assert result["search_method"] == "semantic_sampling_fallback"
        assert len(result["sources"]) > 0
-        assert result["total_found"] > 0
-        pytest.skip(
-            f"Sampling not available (method: {result['search_method']}), "
-            f"but search results returned successfully"
-        )
+        pytest.skip("Sampling not supported by test client (expected fallback)")
    else:
        # Successful sampling
        assert result["search_method"] == "semantic_sampling"
@@ -151,111 +151,3 @@ class TestGetSettings:
        assert settings.vector_sync_scan_interval == 600
        assert settings.vector_sync_processor_workers == 5
        assert settings.vector_sync_queue_max_size == 5000
-
-
-class TestChunkConfigValidation:
-    """Test document chunking configuration validation."""
-
-    def test_default_chunk_settings(self):
-        """Test default chunk size and overlap values."""
-        settings = Settings()
-        assert settings.document_chunk_size == 512
-        assert settings.document_chunk_overlap == 50
-
-    def test_valid_chunk_settings(self):
-        """Test valid chunk size and overlap configuration."""
-        settings = Settings(
-            document_chunk_size=1024,
-            document_chunk_overlap=100,
-        )
-        assert settings.document_chunk_size == 1024
-        assert settings.document_chunk_overlap == 100
-
-    def test_overlap_greater_than_or_equal_to_chunk_size_raises_error(self):
-        """Test that overlap >= chunk size raises ValueError."""
-        with pytest.raises(
-            ValueError,
-            match="DOCUMENT_CHUNK_OVERLAP .* must be less than DOCUMENT_CHUNK_SIZE",
-        ):
-            Settings(
-                document_chunk_size=512,
-                document_chunk_overlap=512,
-            )
-
-    def test_overlap_larger_than_chunk_size_raises_error(self):
-        """Test that overlap > chunk size raises ValueError."""
-        with pytest.raises(
-            ValueError,
-            match="DOCUMENT_CHUNK_OVERLAP .* must be less than DOCUMENT_CHUNK_SIZE",
-        ):
-            Settings(
-                document_chunk_size=256,
-                document_chunk_overlap=300,
-            )
-
-    def test_negative_overlap_raises_error(self):
-        """Test that negative overlap raises ValueError."""
-        with pytest.raises(
-            ValueError,
-            match="DOCUMENT_CHUNK_OVERLAP .* cannot be negative",
-        ):
-            Settings(
-                document_chunk_size=512,
-                document_chunk_overlap=-10,
-            )
-
-    def test_small_chunk_size_warning(self, caplog):
-        """Test that chunk size < 100 triggers warning."""
-        import logging
-
-        caplog.set_level(logging.WARNING, logger="nextcloud_mcp_server.config")
-        Settings(
-            document_chunk_size=64,
-            document_chunk_overlap=10,
-        )
-        assert (
-            "DOCUMENT_CHUNK_SIZE is set to 64 words, which is quite small"
-            in caplog.text
-        )
-        assert "Consider using at least 256 words" in caplog.text
-
-    def test_reasonable_chunk_size_no_warning(self, caplog):
-        """Test that chunk size >= 100 doesn't trigger warning."""
-        import logging
-
-        caplog.set_level(logging.WARNING, logger="nextcloud_mcp_server.config")
-        Settings(
-            document_chunk_size=256,
-            document_chunk_overlap=25,
-        )
-        assert "DOCUMENT_CHUNK_SIZE" not in caplog.text
-
-    @patch.dict(
-        os.environ,
-        {
-            "DOCUMENT_CHUNK_SIZE": "1024",
-            "DOCUMENT_CHUNK_OVERLAP": "102",
-        },
-        clear=True,
-    )
-    def test_get_settings_chunk_config(self):
-        """Test get_settings() with chunk configuration."""
-        settings = get_settings()
-        assert settings.document_chunk_size == 1024
-        assert settings.document_chunk_overlap == 102
-
-    @patch.dict(
-        os.environ,
-        {
-            "DOCUMENT_CHUNK_SIZE": "256",
-            "DOCUMENT_CHUNK_OVERLAP": "256",
-        },
-        clear=True,
-    )
-    def test_get_settings_invalid_chunk_config_raises_error(self):
-        """Test get_settings() raises error for invalid chunk config."""
-        with pytest.raises(
-            ValueError,
-            match="DOCUMENT_CHUNK_OVERLAP .* must be less than DOCUMENT_CHUNK_SIZE",
-        ):
-            get_settings()
@@ -1,88 +0,0 @@
-"""Unit tests for logging filters."""
-
-import logging
-
-import pytest
-
-from nextcloud_mcp_server.observability.logging_config import HealthCheckFilter
-
-
-@pytest.mark.unit
-class TestHealthCheckFilter:
-    """Tests for the HealthCheckFilter."""
-
-    def test_filters_health_live_requests(self):
-        """Test that /health/live requests are filtered out."""
-        # Create a log record that looks like a uvicorn access log for /health/live
-        record = logging.LogRecord(
-            name="uvicorn.access",
-            level=logging.INFO,
-            pathname="",
-            lineno=0,
-            msg='127.0.0.1:12345 - "GET /health/live HTTP/1.1" 200',
-            args=(),
-            exc_info=None,
-        )
-
-        filter_instance = HealthCheckFilter()
-        assert filter_instance.filter(record) is False
-
-    def test_filters_health_ready_requests(self):
-        """Test that /health/ready requests are filtered out."""
-        record = logging.LogRecord(
-            name="uvicorn.access",
-            level=logging.INFO,
-            pathname="",
-            lineno=0,
-            msg='127.0.0.1:12345 - "GET /health/ready HTTP/1.1" 200',
-            args=(),
-            exc_info=None,
-        )
-
-        filter_instance = HealthCheckFilter()
-        assert filter_instance.filter(record) is False
-
-    def test_filters_metrics_requests(self):
-        """Test that /metrics requests are filtered out."""
-        record = logging.LogRecord(
-            name="uvicorn.access",
-            level=logging.INFO,
-            pathname="",
-            lineno=0,
-            msg='127.0.0.1:12345 - "GET /metrics HTTP/1.1" 200',
-            args=(),
-            exc_info=None,
-        )
-
-        filter_instance = HealthCheckFilter()
-        assert filter_instance.filter(record) is False
-
-    def test_allows_other_requests(self):
-        """Test that non-health-check requests are not filtered."""
-        record = logging.LogRecord(
-            name="uvicorn.access",
-            level=logging.INFO,
-            pathname="",
-            lineno=0,
-            msg='127.0.0.1:12345 - "GET /mcp/messages HTTP/1.1" 200',
-            args=(),
-            exc_info=None,
-        )
-
-        filter_instance = HealthCheckFilter()
-        assert filter_instance.filter(record) is True
-
-    def test_allows_api_requests(self):
-        """Test that API requests are not filtered."""
-        record = logging.LogRecord(
-            name="uvicorn.access",
-            level=logging.INFO,
-            pathname="",
-            lineno=0,
-            msg='127.0.0.1:12345 - "POST /oauth/login HTTP/1.1" 302',
-            args=(),
-            exc_info=None,
-        )
-
-        filter_instance = HealthCheckFilter()
-        assert filter_instance.filter(record) is True
@@ -1059,7 +1059,7 @@ wheels = [

 [[package]]
 name = "nextcloud-mcp-server"
-version = "0.29.1"
+version = "0.29.2"
 source = { editable = "." }
 dependencies = [
    { name = "aiosqlite" },